https://github.com/requests/toolbelt
A toolbelt of useful classes and functions to be used with python-requests
https://github.com/requests/toolbelt
http python python-requests toolbox
Last synced: 7 months ago
JSON representation
A toolbelt of useful classes and functions to be used with python-requests
- Host: GitHub
- URL: https://github.com/requests/toolbelt
- Owner: requests
- License: other
- Created: 2013-12-29T21:19:08.000Z (almost 12 years ago)
- Default Branch: master
- Last Pushed: 2025-01-09T01:04:53.000Z (11 months ago)
- Last Synced: 2025-05-07T23:04:54.751Z (7 months ago)
- Topics: http, python, python-requests, toolbox
- Language: Python
- Homepage: https://toolbelt.readthedocs.org
- Size: 790 KB
- Stars: 1,014
- Watchers: 20
- Forks: 190
- Open Issues: 95
-
Metadata Files:
- Readme: README.rst
- Changelog: HISTORY.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.rst
- Security: SECURITY.md
- Authors: AUTHORS.rst
Awesome Lists containing this project
- best-of-web-python - GitHub - 43% open · ⏱️ 09.01.2025): (HTTP Clients)
- starred-awesome - toolbelt - A toolbelt of useful classes and functions to be used with python-requests (Python)
- jimsghstars - requests/toolbelt - A toolbelt of useful classes and functions to be used with python-requests (Python)
README
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
`_ 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