From fcb8c8d33b72f66a0c94b3f2b0a65cb2a2e06697 Mon Sep 17 00:00:00 2001 From: Isa Hassen Date: Sun, 20 Dec 2015 21:53:47 -0500 Subject: [PATCH] Docs: clarify the precedence of `auth=` over `netrc` This closes #2062 by clarifying in the docs which auth header takes precedence: 1st auth= 2nd .netrc 3rd headers= This precedence order is already tested in test_requests.py, in the test_basicauth_with_netrc method. Perhaps we should add further tests for non-basic auth schemes. --- docs/user/authentication.rst | 4 ++-- docs/user/quickstart.rst | 4 +++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/user/authentication.rst b/docs/user/authentication.rst index dd0bf2b8..2779e9c8 100644 --- a/docs/user/authentication.rst +++ b/docs/user/authentication.rst @@ -37,7 +37,8 @@ netrc Authentication If no authentication method is given with the ``auth`` argument, Requests will attempt to get the authentication credentials for the URL's hostname from the -user's netrc file. +user's netrc file. The netrc file overrides raw HTTP authentication headers +set with `headers=`. If credentials for the hostname are found, the request is sent with HTTP Basic Auth. @@ -125,4 +126,3 @@ Further examples can be found under the `Requests organization`_ and in the .. _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 1ff66593..5de5b0ca 100644 --- a/docs/user/quickstart.rst +++ b/docs/user/quickstart.rst @@ -197,7 +197,9 @@ For example, we didn't specify our user-agent in the previous example:: Note: Custom headers are given less precedence than more specific sources of information. For instance: -* Authorization headers will be overridden if credentials are passed via the ``auth`` parameter or are specified in a ``.netrc`` accessible in the environment. +* Authorization headers set with `headers=` will be overridden if credentials +are specified in ``.netrc``, which in turn will be overridden by the ``auth=`` +parameter. * Authorization headers will be removed if you get redirected off-host. * Proxy-Authorization headers will be overridden by proxy credentials provided in the URL. * Content-Length headers will be overridden when we can determine the length of the content.