## File: README.md # Requests [](https://pypi.org/project/requests/) [](https://pypi.org/project/requests) [](https://pepy.tech/project/requests) [](https://github.com/psf/requests/graphs/contributors) [](https://requests.readthedocs.io) **Requests** is a simple, yet elegant, HTTP library. ```python >>> 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](https://github.com/psf/requests/network/dependents?package_id=UGFja2FnZS01NzA4OTExNg%3D%3D) by `4,000,000+` repositories. ## Installing Requests and Supported Versions Requests is available on PyPI: ```console $ python -m pip install requests ``` Requests 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](https://github.com/psf/requests/issues/2690) for more background): ```shell git clone -c fetch.fsck.badTimezone=ignore https://github.com/psf/requests.git ``` You can also apply this setting to your global Git config: ```shell git config --global fetch.fsck.badTimezone ignore ``` --- [](https://kennethreitz.org) [](https://www.python.org/psf) --- ## File: 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 `_ or `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 `. Why not Httplib2? ----------------- Chris Adams gave an excellent summary on `Hacker News `_: 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 `_ 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 `_. 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 ` 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 `_ - `Issac Kelly's 'Consuming Web APIs' talk `_ - `Blog post about Requests via Yum `_ - `Russian blog post introducing Requests `_ - `Sending JSON in Requests `_ --- ## 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 was ``v10.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 a ``Response`` 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 with ``v10.`` 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 released ``v10.2.7`` the hotfix release would be versioned as ``v10.2.8``. Hotfixes will **not** include upgrades to vendored dependencies after ``v2.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 on `Stack Overflow `_ 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 `_. Send a Tweet ------------ If your question is less than 280 characters, feel free to send a tweet to `@nateprewitt `_, `@sethmlarson `_, or `@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 through `the GitHub repo `_. .. include:: ../../HISTORY.md --- ## File: docs/community/vulnerabilities.rst Vulnerability Disclosure ======================== The latest vulnerability disclosure information can be found on GitHub in our `Security Policy `_. --- ## 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 the `Python 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.