diff options
Diffstat (limited to 'docs/user')
| -rw-r--r-- | docs/user/advanced.rst | 61 | ||||
| -rw-r--r-- | docs/user/authentication.rst | 10 | ||||
| -rw-r--r-- | docs/user/quickstart.rst | 15 |
3 files changed, 60 insertions, 26 deletions
diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 613df205..e5f7f297 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -196,18 +196,18 @@ As a result an ``SSL: CERTIFICATE_VERIFY_FAILED`` is thrown. You can get around this behaviour by explicity merging the environment settings into your session:: from requests import Request, Session - + s = Session() req = Request('GET', url) - + prepped = s.prepare_request(req) - + # Merge environment settings into session settings = s.merge_environment_settings(prepped.url, None, None, None, None) resp = s.send(prepped, **settings) - + print(resp.status_code) - + .. _verification: SSL Cert Verification @@ -274,20 +274,19 @@ If you specify a wrong path or an invalid cert, you'll get a SSLError:: CA Certificates --------------- -By default, Requests bundles a set of root CAs that it trusts, sourced from the -`Mozilla trust store`_. However, these are only updated once for each Requests -version. This means that if you pin a Requests version your certificates can -become extremely out of date. +Requests uses certificates from the package `certifi`_. This allows for users +to update their trusted certificates without changing the version of Requests. -From Requests version 2.4.0 onwards, Requests will attempt to use certificates -from `certifi`_ if it is present on the system. This allows for users to update -their trusted certificates without having to change the code that runs on their -system. +Before version 2.16, Requests bundled a set of root CAs that it trusted, +sourced from the `Mozilla trust store`_. The certificates were only updated +once for each Requests version. When ``certifi`` was not installed, this led to +extremely out-of-date certificate bundles when using significantly older +versions of Requests. For the sake of security we recommend upgrading certifi frequently! .. _HTTP persistent connection: https://en.wikipedia.org/wiki/HTTP_persistent_connection -.. _connection pooling: http://urllib3.readthedocs.io/en/latest/reference/index.html#module-urllib3.connectionpool +.. _connection pooling: https://urllib3.readthedocs.io/en/latest/reference/index.html#module-urllib3.connectionpool .. _certifi: http://certifi.io/ .. _Mozilla trust store: https://hg.mozilla.org/mozilla-central/raw-file/tip/security/nss/lib/ckfw/builtins/certdata.txt @@ -436,7 +435,7 @@ You can assign a hook function on a per-request basis by passing a ``{hook_name: callback_function}`` dictionary to the ``hooks`` request parameter:: - hooks=dict(response=print_url) + hooks={'response': print_url} That ``callback_function`` will receive a chunk of data as its first argument. @@ -452,12 +451,36 @@ If the callback function returns a value, it is assumed that it is to replace the data that was passed in. If the function doesn't return anything, nothing else is effected. +:: + + def record_hook(r, *args, **kwargs): + r.hook_called = True + return r + Let's print some request method arguments at runtime:: - >>> requests.get('http://httpbin.org', hooks=dict(response=print_url)) + >>> requests.get('http://httpbin.org', hooks={'response': print_url}) http://httpbin.org <Response [200]> +You can add multiple hooks to a single request. Let's call two hooks at once:: + + >>> r = requests.get('http://httpbin.org', hooks={'response': [print_url, record_hook]}) + >>> r.hook_called + True + +You can also add hooks to a ``Session`` instance. Any hooks you add will then +be called on every request made to the session. For example:: + + >>> s = requests.Session() + >>> s.hooks['response'].append(print_url) + >>> s.get('http://httpbin.org') + http://httpbin.org + <Response [200]> + +A ``Session`` can have multiple hooks, which will be called in the order +they are added. + .. _custom-auth: Custom Authentication @@ -633,7 +656,7 @@ When you receive a response, Requests makes a guess at the encoding to use for decoding the response when you access the :attr:`Response.text <requests.Response.text>` attribute. Requests will first check for an encoding in the HTTP header, and if none is present, will use `chardet -<http://pypi.python.org/pypi/chardet>`_ to attempt to guess the encoding. +<https://pypi.python.org/pypi/chardet>`_ to attempt to guess the encoding. The only time Requests will not do this is if no explicit charset is present in the HTTP headers **and** the ``Content-Type`` @@ -860,7 +883,7 @@ Link Headers Many HTTP APIs feature Link headers. They make APIs more self describing and discoverable. -GitHub uses these for `pagination <http://developer.github.com/v3/#pagination>`_ +GitHub uses these for `pagination <https://developer.github.com/v3/#pagination>`_ in their API, for example:: >>> url = 'https://api.github.com/users/kennethreitz/repos?page=1&per_page=10' @@ -927,9 +950,9 @@ passed-through to `urllib3`. We'll make a Transport Adapter that instructs the library to use SSLv3:: import ssl + from urllib3.poolmanager import PoolManager from requests.adapters import HTTPAdapter - from requests.packages.urllib3.poolmanager import PoolManager class Ssl3HttpAdapter(HTTPAdapter): diff --git a/docs/user/authentication.rst b/docs/user/authentication.rst index 8ffab504..411f79fd 100644 --- a/docs/user/authentication.rst +++ b/docs/user/authentication.rst @@ -136,11 +136,11 @@ Further examples can be found under the `Requests organization`_ and in the .. _OAuth: http://oauth.net/ .. _requests_oauthlib: https://github.com/requests/requests-oauthlib -.. _requests-oauthlib OAuth2 documentation: http://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html -.. _Web Application Flow: http://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#web-application-flow -.. _Mobile Application Flow: http://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#mobile-application-flow -.. _Legacy Application Flow: http://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#legacy-application-flow -.. _Backend Application Flow: http://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#backend-application-flow +.. _requests-oauthlib OAuth2 documentation: https://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html +.. _Web Application Flow: https://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#web-application-flow +.. _Mobile Application Flow: https://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#mobile-application-flow +.. _Legacy Application Flow: https://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#legacy-application-flow +.. _Backend Application Flow: https://requests-oauthlib.readthedocs.io/en/latest/oauth2_workflow.html#backend-application-flow .. _Kerberos: https://github.com/requests/requests-kerberos .. _NTLM: https://github.com/requests/requests-ntlm .. _Requests organization: https://github.com/requests diff --git a/docs/user/quickstart.rst b/docs/user/quickstart.rst index 109c3415..d393bf05 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -110,7 +110,7 @@ using, and change it, using the ``r.encoding`` property:: If you change the encoding, Requests will use the new value of ``r.encoding`` whenever you call ``r.text``. You might want to do this in any situation where you can apply special logic to work out what the encoding of the content will -be. For example, HTTP and XML have the ability to specify their encoding in +be. For example, HTML and XML have the ability to specify their encoding in their body. In situations like this, you should use ``r.content`` to find the encoding, and then set ``r.encoding``. This will let you use ``r.text`` with the correct encoding. @@ -171,7 +171,7 @@ server, you can access ``r.raw``. If you want to do this, make sure you set >>> r = requests.get('https://api.github.com/events', stream=True) >>> r.raw - <requests.packages.urllib3.response.HTTPResponse object at 0x101194810> + <urllib3.response.HTTPResponse object at 0x101194810> >>> r.raw.read(10) '\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03' @@ -189,6 +189,14 @@ download, the above is the preferred and recommended way to retrieve the content. Note that ``chunk_size`` can be freely adjusted to a number that may better fit your use cases. +.. note:: + + An important note about using ``Response.iter_content`` versus ``Response.raw``. + ``Response.iter_content`` will automatically decode the ``gzip`` and ``deflate`` + transfer-encodings. ``Response.raw`` is a raw stream of bytes -- it does not + transform the response content. If you really need access to the bytes as they + were returned, use ``Response.raw``. + Custom Headers -------------- @@ -273,6 +281,9 @@ the ``json`` parameter (added in version 2.4.2) and it will be encoded automatic >>> r = requests.post(url, json=payload) +Note, the ``json`` parameter is ignored if either ``data`` or ``files`` is passed. + +Using the ``json`` parameter in the request will change the ``Content-Type`` in the header to ``application/json``. POST a Multipart-Encoded File ----------------------------- |