Description

The Requests Toolbelt ===================== This is just a collection of utilities for `python-requests`_, but don't really belong in ``requests`` proper. The minimum tested requests version is ``2.1.0``. In reality, the toolbelt should work with ``2.0.1`` as well, but some idiosyncracies prevent effective or sane testing on that version. ``pip install requests-toolbelt`` to get started! multipart/form-data Encoder --------------------------- The main attraction is a streaming multipart form-data object, ``MultipartEncoder``. Its API looks like this: .. code-block:: python from requests_toolbelt import MultipartEncoder import requests m = MultipartEncoder( fields={'field0': 'value', 'field1': 'value', 'field2': ('filename', open('file.py', 'rb'), 'text/plain')} ) r = requests.post('http://httpbin.org/post', data=m, headers={'Content-Type': m.content_type}) You can also use ``multipart/form-data`` encoding for requests that don't require files: .. code-block:: python from requests_toolbelt import MultipartEncoder import requests m = MultipartEncoder(fields={'field0': 'value', 'field1': 'value'}) r = requests.post('http://httpbin.org/post', data=m, headers={'Content-Type': m.content_type}) Or, you can just create the string and examine the data: .. code-block:: python # Assuming `m` is one of the above m.to_string() # Always returns unicode User-Agent constructor ---------------------- You can easily construct a requests-style ``User-Agent`` string:: from requests_toolbelt import user_agent headers = { 'User-Agent': user_agent('my_package', '0.0.1') } r = requests.get('https://api.github.com/users', headers=headers) SSLAdapter ---------- The ``SSLAdapter`` was originally published on `Cory Benfield's blog`_. This adapter allows the user to choose one of the SSL protocols made available in Python's ``ssl`` module for outgoing HTTPS connections: .. code-block:: python from requests_toolbelt import SSLAdapter import requests import ssl s = requests.Session() s.mount('https://', SSLAdapter(ssl.PROTOCOL_TLSv1)) cookies/ForgetfulCookieJar -------------------------- The ``ForgetfulCookieJar`` prevents a particular requests session from storing cookies: .. code-block:: python from requests_toolbelt.cookies.forgetful import ForgetfulCookieJar session = requests.Session() session.cookies = ForgetfulCookieJar() Contributing ------------ Please read the `suggested workflow <https://toolbelt.readthedocs.io/en/latest/contributing.html>`_ for contributing to this project. Please report any bugs on the `issue tracker`_ .. _Cory Benfield's blog: https://lukasa.co.uk/2013/01/Choosing_SSL_Version_In_Requests/ .. _python-requests: https://github.com/kennethreitz/requests .. _issue tracker: https://github.com/requests/toolbelt/issues History ======= 1.0.0 -- 2023-05-01 ------------------- Breaking Changes ~~~~~~~~~~~~~~~~ - Removed Google App Engine support to allow using urllib3 2.0 Fixed Bugs ~~~~~~~~~~ - Ensured the test suite no longer reaches the Internet Miscellaneous ~~~~~~~~~~~~~ - Added explicit support for Python 3.11 0.10.1 -- 2022-10-25 -------------------- Fixed Bugs ~~~~~~~~~~ - Fix urllib3 warning to only emit on X509Adapter usage 0.10.0 -- 2022-10-06 -------------------- New Features ~~~~~~~~~~~~ - Add support for preparing requests in BaseUrlSession Fixed Bugs ~~~~~~~~~~ - Fixing missing newline in dump utility 0.9.1 -- 2019-01-29 ------------------- Fixed Bugs ~~~~~~~~~~ - Fix import of pyOpenSSL shim from urllib3 for PKCS12 adapter 0.9.0 -- 2019-01-29 ------------------- New Features ~~~~~~~~~~~~ - Add X509 Adapter that can handle PKCS12 - Add stateless solution for streaming files by MultipartEncoder from one host to another (in chunks) Fixed Bugs ~~~~~~~~~~ - Update link to example - Move import of ``ABCs`` from collections into version-specific part of _compat module - Fix backwards incompatibility in ``get_encodings_from_content`` - Correct callback documentation for ``MultipartEncoderMonitor`` - Fix bug when ``MultipartEncoder`` is asked to encode zero parts - Correct the type of non string request body dumps - Removed content from being stored in MultipartDecoder - Fix bug by enabling support for contenttype with capital letters. - Coerce proxy URL to bytes before dumping request - Avoid bailing out with exception upon empty response reason - Corrected Pool documentation - Corrected parentheses match in example usage - Fix "oject" to "object" in ``MultipartEncoder`` - Fix URL for the project after the move - Add fix for OSX TCPKeepAliveAdapter Miscellaneous ~~~~~~~~~~~~~ - Remove py33 from testing and add Python 3.6 and nightly testing to the travis matrix. 0.8.0 -- 2017-05-20 ------------------- More information about this release can be found on the `0.8.0 mil