Vehicle-Anti-Theft-Face-Recognition-System/venv/Lib/site-packages/requests_toolbelt-0.7.0.dist-info/DESCRIPTION.rst

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()

Known Issues
------------

On Python 3.3.0 and 3.3.1, the standard library's ``http`` module will fail
when passing an instance of the ``MultipartEncoder``. This is fixed in later
minor releases of Python 3.3. Please consider upgrading to a later minor
version or Python 3.4. *There is absolutely nothing this library can do to
work around that bug.*

Contributing
------------

Please read the `suggested workflow
<https://toolbelt.readthedocs.org/en/latest/contributing.html>`_ for
contributing to this project.

.. _Cory Benfield's blog: https://lukasa.co.uk/2013/01/Choosing_SSL_Version_In_Requests/
.. _python-requests: https://github.com/kennethreitz/requests


History
=======

0.7.0 -- 2016-07-21
-------------------

More information about this release can be found on the `0.7.0 milestone`_.

New Features
~~~~~~~~~~~~

- Add ``BaseUrlSession`` to allow developers to have a session that has a
  "Base" URL. See the documentation for more details and examples.

- Split the logic of ``stream_response_to_file`` into two separate functions:

  * ``get_download_file_path`` to generate the file name from the Response.

  * ``stream_response_to_file`` which will use ``get_download_file_path`` if
    necessary

Fixed Bugs
~~~~~~~~~~

- Fixed the issue for people using *very* old versions of Requests where they
  would see an ImportError from ``requests_toolbelt._compat`` when trying to
  import ``connection``.


.. _0.7.0 milestone:
    https://github.com/sigmavirus24/requests-toolbelt/milestones/0.7.0

0.6.2 -- 2016-05-10
-------------------

Fixed Bugs
~~~~~~~~~~

- When passing a timeout via Requests, it was not appropriately translated to
  the timeout that the urllib3 code was expecting.

0.6.1 -- 2016-05-05
-------------------

Fixed Bugs
~~~~~~~~~~

- Remove assertion about request URLs in the AppEngineAdapter.

- Prevent pip from installing requests 3.0.0 when that is released until we
  are ready to handle it.

0.6.0 -- 2016-01-27
-------------------

More information about this release can be found on the `0.6.0 milestone`_.

New Features
~~~~~~~~~~~~

- Add ``AppEngineAdapter`` to support developers using Google's AppEngine
  platform with Requests.

- Add ``GuessProxyAuth`` class to support guessing between Basic and Digest
  Authentication for proxies.

Fixed Bugs
~~~~~~~~~~

- Ensure that proxies use the correct TLS version when using the
  ``SSLAdapter``.

- Fix an ``AttributeError`` when using the ``HTTPProxyDigestAuth`` class.

Miscellaneous
~~~~~~~~~~~~~

- Drop testing support for Python 3.2. virtualenv and pip have stopped
  supporting it meaning that it is harder to test for this with our CI
  infrastructure. Moving forward we will make a best-effort attempt to
  support 3.2 but will not test for it.


.. _0.6.0 milestone:
    https://github.com/sigmavirus24/requests-toolbelt/milestones/0.6.0

0.5.1 -- 2015-12-16
-------------------

More information about this release can be found on the `0.5.1 milestone`_.

Fixed Bugs
~~~~~~~~~~

- Now papers over the differences in requests' ``super_len`` function from
  versions prior to 2.9.0 and versions 2.9.0 and later.


.. _0.5.1 milestone:
    https://github.com/sigmavirus24/requests-toolbelt/milestones/0.5.1

0.5.0 -- 2015-11-24
-------------------

More information about this release can be found on the `milestone
<https://github.com/sigmavirus24/requests-toolbelt/issues?utf8=%E2%9C%93&q=is%3Aall+milestone%3A0.5+>`_
for 0.5.0.

New Features
~~~~~~~~~~~~

- The ``tee`` submodule was added to ``requests_toolbelt.downloadutils``. It
  allows you to iterate over the bytes of a response while also writing them
  to a file. The ``tee.tee`` function, expects you to pass an open file
  object, while ``tee.tee_to_file`` will use the provided file name to open
  the file for you.

- Added a new parameter to ``requests_toolbelt.utils.user_agent`` that allows
  the user to specify additional items.

- Added nested form-data helper,
  ``requests_toolbelt.utils.formdata.urlencode``.

- Added the ``ForgetfulCookieJar`` to ``requests_toolbelt.cookies``.

- Added utilities for dumping the information about a request-response cycle
  in ``requests_toolbelt.utils.dump``.

- Implemented the API described in the ``requests_toolbelt.threaded`` module
  docstring, i.e., added ``requests_toolbelt.threaded.map`` as an available
  function.

Fixed Bugs
~~~~~~~~~~

- Now papers over the API differences in versions of requests installed from
  system packages versus versions of requests installed from PyPI.

- Allow string types for ``SourceAddressAdapter``.

0.4.0 -- 2015-04-03
-------------------

For more information about this release, please see `milestone 0.4.0
<https://github.com/sigmavirus24/requests-toolbelt/issues?q=milestone%3A0.4>`_
on the project's page.

New Features
~~~~~~~~~~~~

- A naive implemenation of a thread pool is now included in the toolbelt. See
  the docs in ``docs/threading.rst`` or on `Read The Docs
  <https://toolbelt.readthedocs.org>`_.

- The ``StreamingIterator`` now accepts files (such as ``sys.stdin``) without
  a specific length and will properly stream them.

- The ``MultipartEncoder`` now accepts exactly the same format of fields as
  requests' ``files`` parameter does. In other words, you can now also pass in
  extra headers to add to a part in the body. You can also now specify a
  custom ``Content-Type`` for a part.

- An implementation of HTTP Digest Authentication for Proxies is now included.

- A transport adapter that allows a user to specify a specific Certificate
  Fingerprint is now included in the toolbelt.

- A transport adapter that simplifies how users specify socket options is now
  included.

- A transport adapter that simplifies how users can specify TCP Keep-Alive
  options is now included in the toolbelt.

- Deprecated functions from ``requests.utils`` are now included and
  maintained.

- An authentication tool that allows users to specify how to authenticate to
  several different domains at once is now included.

- A function to save streamed responses to disk by analyzing the
  ``Content-Disposition`` header is now included in the toolbelt.

Fixed Bugs
~~~~~~~~~~

- The ``MultipartEncoder`` will now allow users to upload files larger than
  4GB on 32-bit systems.

- The ``MultipartEncoder`` will now accept empty unicode strings for form
  values.

0.3.1 -- 2014-06-23
-------------------

- Fix the fact that 0.3.0 bundle did not include the ``StreamingIterator``

0.3.0 -- 2014-05-21
-------------------

Bug Fixes
~~~~~~~~~

- Complete rewrite of ``MultipartEncoder`` fixes bug where bytes were lost in
  uploads

New Features
~~~~~~~~~~~~

- ``MultipartDecoder`` to accept ``multipart/form-data`` response bodies and
  parse them into an easy to use object.

- ``SourceAddressAdapter`` to allow users to choose a local address to bind
  connections to.

- ``GuessAuth`` which accepts a username and password and uses the
  ``WWW-Authenticate`` header to determine how to authenticate against a
  server.

- ``MultipartEncoderMonitor`` wraps an instance of the ``MultipartEncoder``
  and keeps track of how many bytes were read and will call the provided
  callback.

- ``StreamingIterator`` will wrap an iterator and stream the upload instead of
  chunk it, provided you also provide the length of the content you wish to
  upload.

0.2.0 -- 2014-02-24
-------------------

- Add ability to tell ``MultipartEncoder`` which encoding to use. By default
  it uses 'utf-8'.

- Fix #10 - allow users to install with pip

- Fix #9 - Fix ``MultipartEncoder#to_string`` so that it properly handles file
  objects as fields

0.1.2 -- 2014-01-19
-------------------

- At some point during development we broke how we handle normal file objects.
  Thanks to @konomae this is now fixed.

0.1.1 -- 2014-01-19
-------------------

- Handle ``io.BytesIO``-like objects better

0.1.0 -- 2014-01-18
-------------------

- Add initial implementation of the streaming ``MultipartEncoder``

- Add initial implementation of the ``user_agent`` function

- Add the ``SSLAdapter``