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: 2 days 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 (about 11 years ago)
• Default Branch: master
• Last Pushed: 2024-04-11T17:23:10.000Z (9 months ago)
• Last Synced: 2025-01-03T01:54:52.412Z (9 days ago)
• Topics: http, python, python-requests, toolbox
• Language: Python
• Homepage: https://toolbelt.readthedocs.org
• Size: 788 KB
• Stars: 998
• Watchers: 21
• Forks: 186
• 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

• 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)
• best-of-web-python - GitHub - 43% open · ⏱️ 11.04.2024): (HTTP Clients)

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