File: README.md
Requests
Requests is a simple, yet elegant, HTTP library.
>>> import requests
>>> r = requests.get('https://httpbin.org/basic-auth/user/pass', auth=('user', 'pass'))
>>> r.status_code
200
>>> r.headers['content-type']
'application/json; charset=utf8'
>>> r.encoding
'utf-8'
>>> r.text
'{"authenticated": true, ...'
>>> r.json()
{'authenticated': True, ...}Requests allows you to send HTTP/1.1 requests extremely easily. There’s no need to manually add query strings to your URLs, or to form-encode your PUT & POST data — but nowadays, just use the json method!
Requests is one of the most downloaded Python packages today, pulling in around 300M downloads / week — according to GitHub, Requests is currently depended upon by 4,000,000+ repositories.
Installing Requests and Supported Versions
Requests is available on PyPI:
$ python -m pip install requestsRequests officially supports Python 3.10+.
Supported Features & Best–Practices
Requests is ready for the demands of building robust and reliable HTTP–speaking applications, for the needs of today.
- Keep-Alive & Connection Pooling
- International Domains and URLs
- Sessions with Cookie Persistence
- Browser-style TLS/SSL Verification
- Basic & Digest Authentication
- Familiar
dict–like Cookies - Automatic Content Decompression and Decoding
- Multi-part File Uploads
- SOCKS Proxy Support
- Connection Timeouts
- Streaming Downloads
- Automatic honoring of
.netrc - Chunked HTTP Requests
Cloning the repository
When cloning the Requests repository, you may need to add the -c fetch.fsck.badTimezone=ignore flag to avoid an error about a bad commit timestamp (see
this issue for more background):
git clone -c fetch.fsck.badTimezone=ignore https://github.com/psf/requests.gitYou can also apply this setting to your global Git config:
git config --global fetch.fsck.badTimezone ignoreFile: docs/community/faq.rst
.. _faq:
Frequently Asked Questions
This part of the documentation answers common questions about Requests.
Encoded Data?
Requests automatically decompresses gzip-encoded responses, and does
its best to decode response content to unicode when possible.
When either the brotli <https://pypi.org/project/Brotli/>_ or brotlicffi <https://pypi.org/project/brotlicffi/>_
package is installed, requests also decodes Brotli-encoded responses.
You can get direct access to the raw response (and even the socket),
if needed as well.
Custom User-Agents?
Requests allows you to easily override User-Agent strings, along with
any other HTTP Header. See :ref:documentation about headers <custom-headers>.
Why not Httplib2?
Chris Adams gave an excellent summary onHacker News <https://news.ycombinator.com/item?id=2884406>_:
httplib2 is part of why you should use requests: it's far more respectable
as a client but not as well documented and it still takes way too much code
for basic operations. I appreciate what httplib2 is trying to do, that
there's a ton of hard low-level annoyances in building a modern HTTP
client, but really, just use requests instead. Kenneth Reitz is very
motivated and he gets the degree to which simple things should be simple
whereas httplib2 feels more like an academic exercise than something
people should use to build production systems[1].
Disclosure: I'm listed in the requests AUTHORS file but can claim credit
for, oh, about 0.0001% of the awesomeness.
1. https://code.google.com/p/httplib2/issues/detail?id=96 is a good example:
an annoying bug that affected many people, there was a fix available for
months, which worked great when I applied it in a fork and pounded a couple
TB of data through it, but it took over a year to make it into trunk and
even longer to make it onto PyPI where any other project which required "
httplib2" would get the working version.Python 3 Support?
Yes! Requests supports all officially supported versions of Python <https://devguide.python.org/versions/>_
and recent releases of PyPy.
Python 2 Support?
No! As of Requests 2.28.0, Requests no longer supports Python 2.7. Users who
have been unable to migrate should pin to requests<2.28. Full information
can be found in psf/requests#6023 <https://github.com/psf/requests/issues/6023>_.
It is highly recommended users migrate to a supported Python 3.x version now since
Python 2.7 is no longer receiving bug fixes or security updates as of January 1, 2020.
What are "hostname doesn't match" errors?
These errors occur when :ref:SSL certificate verification <verification>
fails to match the certificate the server responds with to the hostname
Requests thinks it's contacting. If you're certain the server's SSL setup is
correct (for example, because you can visit the site with your browser) and
you're using Python 2.7, a possible explanation is that you need
Server-Name-Indication.
Server-Name-Indication, or SNI, is an official extension to SSL where the
client tells the server what hostname it is contacting. This is important
when servers are using Virtual Hosting. When such servers are hosting
more than one SSL site they need to be able to return the appropriate
certificate based on the hostname the client is connecting to.
Python 3 already includes native support for SNI in their SSL modules.
.. _Server-Name-Indication: https://en.wikipedia.org/wiki/Server_Name_Indication
.. _virtual hosting: https://en.wikipedia.org/wiki/Virtual_hosting
File: docs/community/out-there.rst
Integrations
Articles & Talks
Daniel Greenfeld's Review of Requests <https://pydanny.blogspot.com/2011/05/python-http-requests-for-humans.html>_Issac Kelly's 'Consuming Web APIs' talk <https://issackelly.github.io/Consuming-Web-APIs-with-Python-Talk/slides/slides.html>_Blog post about Requests via Yum <https://arunsag.wordpress.com/2011/08/17/new-package-python-requests-http-for-humans/>_Russian blog post introducing Requests <https://habr.com/post/126262/>_Sending JSON in Requests <https://www.coglib.com/~icordasc/blog/2014/11/sending-json-in-requests.html>_
File: docs/community/recommended.rst
.. _recommended:
Recommended Packages and Extensions
Requests has a great variety of powerful and useful third-party extensions.
This page provides an overview of some of the best of them.
Certifi CA Bundle
Certifi_ is a carefully curated collection of Root Certificates for
validating the trustworthiness of SSL certificates while verifying the
identity of TLS hosts. It has been extracted from the Requests project.
.. _Certifi: https://github.com/certifi/python-certifi
CacheControl
CacheControl_ is an extension that adds a full HTTP cache to Requests. This
makes your web requests substantially more efficient, and should be used
whenever you're making a lot of web requests.
.. _CacheControl: https://cachecontrol.readthedocs.io/en/latest/
Requests-Toolbelt
Requests-Toolbelt_ is a collection of utilities that some users of Requests may desire,
but do not belong in Requests proper. This library is actively maintained
by members of the Requests core team, and reflects the functionality most
requested by users within the community.
.. _Requests-Toolbelt: https://toolbelt.readthedocs.io/en/latest/index.html
Requests-Threads
Requests-Threads_ is a Requests session that returns the amazing Twisted's awaitable Deferreds instead of Response objects. This allows the use of async/await keyword usage on Python 3, or Twisted's style of programming, if desired.
.. _Requests-Threads: https://github.com/requests/requests-threads
Requests-OAuthlib
requests-oauthlib_ makes it possible to do the OAuth dance from Requests
automatically. This is useful for the large number of websites that use OAuth
to provide authentication. It also provides a lot of tweaks that handle ways
that specific OAuth providers differ from the standard specifications.
.. _requests-oauthlib: https://requests-oauthlib.readthedocs.io/en/latest/
Betamax
Betamax_ records your HTTP interactions so the NSA does not have to.
A VCR imitation designed only for Python-Requests.
.. _betamax: https://github.com/betamaxpy/betamax
File: docs/community/release-process.rst
Release Process and Rules
.. versionadded:: v2.6.2
Starting with the version to be released after v2.6.2, the following rules
will govern and describe how the Requests core team produces a new release.
Major Releases
A major release will include breaking changes. When it is versioned, it will
be versioned as vX.0.0. For example, if the previous release wasv10.2.7 the next version will be v11.0.0.
Breaking changes are changes that break backwards compatibility with prior
versions. If the project were to change the text attribute on aResponse object to a method, that would only happen in a Major release.
Major releases may also include miscellaneous bug fixes. The core developers of
Requests are committed to providing a good user experience. This means we're
also committed to preserving backwards compatibility as much as possible. Major
releases will be infrequent and will need strong justifications before they are
considered.
Minor Releases
A minor release will not include breaking changes but may include miscellaneous
bug fixes. If the previous version of Requests released was v10.2.7 a minor
release would be versioned as v10.3.0.
Minor releases will be backwards compatible with releases that have the same
major version number. In other words, all versions that would start withv10. should be compatible with each other.
Hotfix Releases
A hotfix release will only include bug fixes that were missed when the project
released the previous version. If the previous version of Requests releasedv10.2.7 the hotfix release would be versioned as v10.2.8.
Hotfixes will not include upgrades to vendored dependencies afterv2.6.2
Reasoning
In the 2.5 and 2.6 release series, the Requests core team upgraded vendored
dependencies and caused a great deal of headaches for both users and the core
team. To reduce this pain, we're forming a concrete set of procedures so
expectations will be properly set.
File: docs/community/support.rst
.. _support:
Support
If you have questions or issues about Requests, there are several options:
Stack Overflow
If your question does not contain sensitive (possibly proprietary)
information or can be properly anonymized, please ask a question onStack Overflow <https://stackoverflow.com/questions/tagged/python-requests>_
and use the tag python-requests.
File an Issue
If you notice some unexpected behaviour in Requests, or want to see support
for a new feature,file an issue on GitHub <https://github.com/psf/requests/issues>_.
Send a Tweet
If your question is less than 280 characters, feel free to send a tweet to@nateprewitt <https://twitter.com/nateprewitt>,@sethmlarson <https://twitter.com/sethmlarson>, or@sigmavirus24 <https://twitter.com/sigmavirus24>_.
File: docs/community/updates.rst
.. _updates:
Community Updates
If you'd like to stay up to date on the community and development of Requests,
there are several options:
GitHub
The best way to track the development of Requests is throughthe GitHub repo <https://github.com/psf/requests>_.
.. include:: ../../HISTORY.md
File: docs/community/vulnerabilities.rst
Vulnerability Disclosure
The latest vulnerability disclosure information can be found on GitHub in ourSecurity Policy <https://github.com/psf/requests/blob/main/.github/SECURITY.md>_.
File: docs/dev/contributing.rst
.. _contributing:
Contributor's Guide
If you're reading this, you're probably interested in contributing to Requests.
Thank you very much! Open source projects live-and-die based on the support
they receive from others, and the fact that you're even considering
contributing to the Requests project is very generous of you.
This document lays out guidelines and advice for contributing to this project.
If you're thinking of contributing, please start by reading this document and
getting a feel for how contributing to this project works. If you have any
questions, feel free to reach out to either Nate Prewitt, Ian Cordasco,
or Seth Michael Larson_, the primary maintainers.
.. _Ian Cordasco: https://www.coglib.com/~icordasc/
.. _Nate Prewitt: https://www.nateprewitt.com/
.. _Seth Michael Larson: https://sethmlarson.dev/
The guide is split into sections based on the type of contribution you're
thinking of making, with a section that covers general guidelines for all
contributors.
Code of Conduct
The Python community is made up of members from around the globe with a diverse
set of skills, personalities, and experiences. It is through these differences
that our community experiences great successes and continued growth. When you're
working with members of the community, follow thePython Software Foundation Code of Conduct_ to help steer your interactions
and keep Python a positive, successful, and growing community.
.. _Python Software Foundation Code of Conduct: https://policies.python.org/python.org/code-of-conduct/
.. _early-feedback:
Get Early Feedback
If you are contributing, do not feel the need to sit on your contribution until
it is perfectly polished and complete. It helps everyone involved for you to
seek feedback as early as you possibly can. Submitting an early, unfinished
version of your contribution for feedback in no way prejudices your chances of
getting that contribution accepted, and can save you from putting a lot of work
into a contribution that is not suitable for the project.
Contribution Suitability
Our project maintainers have the last word on whether or not a contribution is
suitable for Requests. All contributions will be considered carefully, but from
time to time, contributions will be rejected because they do not suit the
current goals or needs of the project.
If your contribution is rejected, don't despair! As long as you followed these
guidelines, you will have a much better chance of getting your next
contribution accepted.
Code Contributions
Steps for Submitting Code
When contributing code, you'll want to follow this checklist:
1. Fork the repository on GitHub.
2. Run the tests to confirm they all pass on your system. If they don't, you'll
need to investigate why they fail. If you're unable to diagnose this
yourself, raise it as a bug report by following the guidelines in this
document: :ref:`bug-reports`.
3. Write tests that demonstrate your bug or feature. Ensure that they fail.
4. Make your change.
5. Run the entire test suite again, confirming that all tests pass *including
the ones you just added*.
6. Send a GitHub Pull Request to the main repository's ``main`` branch.
GitHub Pull Requests are the expected method of code collaboration on this
project.
The following sub-sections go into more detail on some of the points above.
Code Review
~~~~~~~~~~~
Contributions will not be merged until they've been code reviewed. You should
implement any code review feedback unless you strongly object to it. In the
event that you object to the code review feedback, you should make your case
clearly and calmly. If, after doing so, the feedback is judged to still apply,
you must either apply the feedback or withdraw your contribution.
Code Style
~~~~~~~~~~
Requests uses a collection of tools to ensure the code base has a consistent
style as it grows. We have these orchestrated using a tool called
`pre-commit`_. This can be installed locally and run over your changes prior
to opening a PR, and will also be run as part of the CI approval process
before a change is merged.
You can find the full list of formatting requirements specified in the
`.pre-commit-config.yaml`_ at the top level directory of Requests.
.. _pre-commit: https://pre-commit.com/
.. _.pre-commit-config.yaml: https://github.com/psf/requests/blob/main/.pre-commit-config.yaml
New Contributors
~~~~~~~~~~~~~~~~
If you are new or relatively new to Open Source, welcome! Requests aims to
be a gentle introduction to the world of Open Source. If you're concerned about
how best to contribute, please consider mailing a maintainer (listed above) and
asking for help.
Please also check the :ref:`early-feedback` section.
Documentation Contributions
---------------------------
Documentation improvements are always welcome! The documentation files live in
the ``docs/`` directory of the codebase. They're written in
`reStructuredText`_, and use `Sphinx`_ to generate the full suite of
documentation.
When contributing documentation, please do your best to follow the style of the
documentation files. This means a soft-limit of 79 characters wide in your text
files and a semi-formal, yet friendly and approachable, prose style.
When presenting Python code, use single-quoted strings (``'hello'`` instead of
``"hello"``).
.. _reStructuredText: https://docutils.sourceforge.net/rst.html
.. _Sphinx: https://www.sphinx-doc.org/en/master/
.. _bug-reports:
Bug Reports
-----------
Bug reports are hugely important! Before you raise one, though, please check
through the `GitHub issues`_, **both open and closed**, to confirm that the bug
hasn't been reported before. Duplicate bug reports are a huge drain on the time
of other contributors, and should be avoided as much as possible.
.. _GitHub issues: https://github.com/psf/requests/issues
Feature Requests
----------------
Requests is in a perpetual feature freeze, only the BDFL can add or approve of
new features. The maintainers believe that Requests is a feature-complete
piece of software at this time.
One of the most important skills to have while maintaining a largely-used
open source project is learning the ability to say "no" to suggested changes,
while keeping an open ear and mind.
If you believe there is a feature missing, feel free to raise a feature
request, but please do be aware that the overwhelming likelihood is that your
feature request will not be accepted.