.. _Adapter:

=============
Adapter Usage
=============

Creating an Adapter
===================

The standard `requests`_ means of using a `transport adapter`_ is to `mount`_ it on a created session.
This is not the only way to load the adapter, however the same interactions will be used.

When mounting an adapter, keep in mind that:

* for a given URL, `requests`_ will use the adapter associated to the longest matching prefix;
* session are created with adapters for the :py:const:`http://` and :py:const:`https://` prefixes
  (and thus adapters mounted on :py:const:`http` or :py:const:`https` will never be used);
* `requests`_ only prepares URLs for *http* schemes (start with http and only contains letters, numbers, and the + and - signs).
  In particular :py:data:`params` won't work with the :py:const:`mock://` scheme, but will with :py:const:`http+mock://`.

If you are not familiar with adapters, prefer the mocker approach (see :ref:`Mocker`).

.. doctest::

    >>> import requests
    >>> import requests_mock

    >>> session = requests.Session()
    >>> adapter = requests_mock.Adapter()
    >>> session.mount('mock://', adapter)

At this point any requests made by the session to a URI starting with `mock://` will be sent to our adapter.

.. _requests: https://requests.readthedocs.io
.. _transport adapter: https://requests.readthedocs.io/en/master/user/advanced/#transport-adapters
.. _mount: https://requests.readthedocs.io/en/master/api/#requests.Session.mount