recipe_engine/third_party/requests/docs/user/authentication.rst - Issue 2164713003: Vendor requests.

Side by Side Diff: recipe_engine/third_party/requests/docs/user/authentication.rst

Issue 2164713003: Vendor requests. (Closed) Base URL: https://chromium.googlesource.com/external/github.com/luci/recipes-py@master

Patch Set: Fix deps.pyl Created 4 years, 5 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View unified diff | Download patch

OLD	NEW
	(Empty)
1 .. _authentication:

2

3 Authentication

4 ==============

5

6 This document discusses using various kinds of authentication with Requests.

7

8 Many web services require authentication, and there are many different types.

9 Below, we outline various forms of authentication available in Requests, from

10 the simple to the complex.

11

12

13 Basic Authentication

14 --------------------

15

16 Many web services that require authentication accept HTTP Basic Auth. This is

17 the simplest kind, and Requests supports it straight out of the box.

18

19 Making requests with HTTP Basic Auth is very simple::

20

21 >>> from requests.auth import HTTPBasicAuth

22 >>> requests.get('https://api.github.com/user', auth=HTTPBasicAuth('user', ' pass'))

23 <Response [200]>

24

25 In fact, HTTP Basic Auth is so common that Requests provides a handy shorthand

26 for using it::

27

28 >>> requests.get('https://api.github.com/user', auth=('user', 'pass'))

29 <Response [200]>

30

31 Providing the credentials in a tuple like this is exactly the same as the

32 ``HTTPBasicAuth`` example above.

33

34

35 netrc Authentication

36 ~~~~~~~~~~~~~~~~~~~~

37

38 If no authentication method is given with the ``auth`` argument, Requests will

39 attempt to get the authentication credentials for the URL's hostname from the

40 user's netrc file. The netrc file overrides raw HTTP authentication headers

41 set with `headers=`.

42

43 If credentials for the hostname are found, the request is sent with HTTP Basic

44 Auth.

45

46

47 Digest Authentication

48 ---------------------

49

50 Another very popular form of HTTP Authentication is Digest Authentication,

51 and Requests supports this out of the box as well::

52

53 >>> from requests.auth import HTTPDigestAuth

54 >>> url = 'http://httpbin.org/digest-auth/auth/user/pass'

55 >>> requests.get(url, auth=HTTPDigestAuth('user', 'pass'))

56 <Response [200]>

57

58

59 OAuth 1 Authentication

60 ----------------------

61

62 A common form of authentication for several web APIs is OAuth. The ``requests-oa uthlib``

63 library allows Requests users to easily make OAuth authenticated requests::

64

65 >>> import requests

66 >>> from requests_oauthlib import OAuth1

67

68 >>> url = 'https://api.twitter.com/1.1/account/verify_credentials.json'

69 >>> auth = OAuth1('YOUR_APP_KEY', 'YOUR_APP_SECRET',

70 'USER_OAUTH_TOKEN', 'USER_OAUTH_TOKEN_SECRET')

71

72 >>> requests.get(url, auth=auth)

73 <Response [200]>

74

75 For more information on how to OAuth flow works, please see the official `OAuth` _ website.

76 For examples and documentation on requests-oauthlib, please see the `requests_oa uthlib`_

77 repository on GitHub

78

79

80 Other Authentication

81 --------------------

82

83 Requests is designed to allow other forms of authentication to be easily and

84 quickly plugged in. Members of the open-source community frequently write

85 authentication handlers for more complicated or less commonly-used forms of

86 authentication. Some of the best have been brought together under the

87 `Requests organization`_, including:

88

89 - Kerberos_

90 - NTLM_

91

92 If you want to use any of these forms of authentication, go straight to their

93 GitHub page and follow the instructions.

94

95

96 New Forms of Authentication

97 ---------------------------

98

99 If you can't find a good implementation of the form of authentication you

100 want, you can implement it yourself. Requests makes it easy to add your own

101 forms of authentication.

102

103 To do so, subclass :class:`AuthBase <requests.auth.AuthBase>` and implement the

104 ``__call__()`` method::

105

106 >>> import requests

107 >>> class MyAuth(requests.auth.AuthBase):

108 ... def __call__(self, r):

109 ... # Implement my authentication

110 ... return r

111 ...

112 >>> url = 'http://httpbin.org/get'

113 >>> requests.get(url, auth=MyAuth())

114 <Response [200]>

115

116 When an authentication handler is attached to a request,

117 it is called during request setup. The ``__call__`` method must therefore do

118 whatever is required to make the authentication work. Some forms of

119 authentication will additionally add hooks to provide further functionality.

120

121 Further examples can be found under the `Requests organization`_ and in the

122 ``auth.py`` file.

123

124 .. _OAuth: http://oauth.net/

125 .. _requests_oauthlib: https://github.com/requests/requests-oauthlib

126 .. _Kerberos: https://github.com/requests/requests-kerberos

127 .. _NTLM: https://github.com/requests/requests-ntlm

128 .. _Requests organization: https://github.com/requests

OLD	NEW