1
1
# -*- coding: utf-8 -*-
2
- """
3
- github3.auths
4
- =============
5
-
6
- This module contains the Authorization object.
7
-
8
- """
2
+ """This module contains the Authorization object."""
9
3
from __future__ import unicode_literals
10
4
11
5
from .decorators import requires_basic_auth
12
6
from .models import GitHubCore
13
7
14
8
15
9
class Authorization (GitHubCore ):
10
+ """Representation of an OAuth Authorization.
16
11
17
- """The :class:`Authorization <Authorization>` object.
12
+ See also: https://developer.github.com/v3/oauth_authorizations/
18
13
19
- Two authorization instances can be checked like so: :
14
+ This object has the following attributes :
20
15
21
- a1 == a2
22
- a1 != a2
16
+ .. attribute:: app
23
17
24
- And is equivalent to::
18
+ Details about the application the authorization was created for.
25
19
26
- a1.id == a2.id
27
- a1.id != a2.id
20
+ .. attribute:: created_at
28
21
29
- See also: http://developer.github.com/v3/oauth/#oauth-authorizations-api
22
+ A :class:`~datetime.datetime` representing when this authorization was
23
+ created.
30
24
31
- """
25
+ .. attribute:: fingerprint
32
26
33
- def _update_attributes (self , auth ):
34
- self ._api = self ._get_attribute (auth , 'url' )
27
+ .. versionadded:: 1.0
28
+
29
+ The optional parameter that is used to allow an OAuth application to
30
+ create multiple authorizations for the same user. This will help
31
+ distinguish two authorizations for the same app.
32
+
33
+ .. attribute:: hashed_token
34
+
35
+ .. versionadded:: 1.0
36
+
37
+ This is the base64 of the SHA-256 digest of the token.
38
+
39
+ .. seealso::
40
+
41
+ `Removing Authorization Tokens`_
42
+ The blog post announcing the removal of :attr:`token`.
43
+
44
+ .. attribute:: id
45
+
46
+ The unique identifier for this authorization.
35
47
36
- #: Details about the application (name, url)
37
- self .app = self ._get_attribute (auth , 'app' , {})
48
+ .. attribute:: note_url
38
49
39
- #: Returns the Authorization token
40
- self . token = self . _get_attribute ( auth , 'token' )
50
+ The URL that points to a longer description about the purpose of this
51
+ autohrization.
41
52
42
- #: App name
43
- self .name = self ._get_attribute (self .app , 'name' )
53
+ .. attribute:: note
44
54
45
- #: URL about the note
46
- self .note_url = self ._get_attribute (auth , 'note_url' )
55
+ The short note provided when this authorization was created.
47
56
48
- #: Note about the authorization
49
- self .note = self ._get_attribute (auth , 'note' )
57
+ .. attribute:: scopes
50
58
51
- #: List of scopes this applies to
52
- self .scopes = self ._get_attribute (auth , 'scopes' )
59
+ The list of scopes assigned to this token.
53
60
54
- #: Unique id of the authorization
55
- self .id = self ._get_attribute (auth , 'id' )
61
+ .. seealso::
56
62
57
- #: datetime object representing when the authorization was created.
58
- self .created_at = self ._strptime_attribute (auth , 'created_at' )
63
+ `Scopes for OAuth Applications`_
64
+ GitHub's documentation around available scopes and what they
65
+ mean
59
66
60
- #: datetime object representing when the authorization was updated.
61
- self .updated_at = self ._strptime_attribute (auth , 'updated_at' )
67
+ .. attribute:: token
68
+
69
+ If this authorization was created, this will contain the full token.
70
+ Otherwise, this attribute will be an empty string.
71
+
72
+ .. attribute:: token_last_eight
73
+
74
+ .. versionadded:: 1.0
75
+
76
+ The last eight characters of the token. This allows users to identify
77
+ a token after the initial retrieval.
78
+
79
+ .. attribute:: updated_at
80
+
81
+ A :class:`~datetime.datetime` representing when this authorization was
82
+ most recently updated.
83
+
84
+ .. _Scopes for OAuth Applications:
85
+ https://developer.github.com/apps/building-oauth-apps/scopes-for-oauth-apps/
86
+ .. _Removing Authorization Tokens:
87
+ https://developer.github.com/changes/2014-12-08-removing-authorizations-token/#what-should-you-do
88
+ """
89
+
90
+ def _update_attributes (self , auth ):
91
+ self ._api = auth ['url' ]
92
+ self .app = auth ['app' ]
93
+ self .created_at = self ._strptime (auth ['created_at' ])
94
+ self .fingerprint = auth ['fingerprint' ]
95
+ self .id = auth ['id' ]
96
+ self .note_url = auth ['note_url' ]
97
+ self .note = auth ['note' ]
98
+ self .scopes = auth ['scopes' ]
99
+ self .token = auth ['token' ]
100
+ self .token_last_eight = auth ['token_last_eight' ]
101
+ self .updated_at = self ._strptime (auth ['updated_at' ])
62
102
63
103
def _repr (self ):
64
104
return '<Authorization [{0}]>' .format (self .name )
@@ -79,23 +119,32 @@ def _update(self, scopes_data, note, note_url):
79
119
80
120
@requires_basic_auth
81
121
def add_scopes (self , scopes , note = None , note_url = None ):
82
- """Adds the scopes to this authorization.
122
+ """Add the scopes to this authorization.
83
123
84
124
.. versionadded:: 1.0
85
125
86
- :param list scopes: Adds these scopes to the ones present on this
87
- authorization
88
- :param str note: (optional), Note about the authorization
89
- :param str note_url: (optional), URL to link to when the user views
90
- the authorization
91
- :returns: True if successful, False otherwise
92
- :rtype: bool
126
+ :param list scopes:
127
+ Adds these scopes to the ones present on this authorization
128
+ :param str note:
129
+ (optional), Note about the authorization
130
+ :param str note_url:
131
+ (optional), URL to link to when the user views the authorization
132
+ :returns:
133
+ True if successful, False otherwise
134
+ :rtype:
135
+ bool
93
136
"""
94
137
return self ._update ({'add_scopes' : scopes }, note , note_url )
95
138
96
139
@requires_basic_auth
97
140
def delete (self ):
98
- """Delete this authorization."""
141
+ """Delete this authorization.
142
+
143
+ :returns:
144
+ True if successful, False otherwise
145
+ :rtype:
146
+ bool
147
+ """
99
148
return self ._boolean (self ._delete (self ._api ), 204 , 404 )
100
149
101
150
@requires_basic_auth
@@ -104,13 +153,16 @@ def remove_scopes(self, scopes, note=None, note_url=None):
104
153
105
154
.. versionadded:: 1.0
106
155
107
- :param list scopes: Remove these scopes from the ones present on this
108
- authorization
109
- :param str note: (optional), Note about the authorization
110
- :param str note_url: (optional), URL to link to when the user views
111
- the authorization
112
- :returns: True if successful, False otherwise
113
- :rtype: bool
156
+ :param list scopes:
157
+ Remove these scopes from the ones present on this authorization
158
+ :param str note:
159
+ (optional), Note about the authorization
160
+ :param str note_url:
161
+ (optional), URL to link to when the user views the authorization
162
+ :returns:
163
+ True if successful, False otherwise
164
+ :rtype:
165
+ bool
114
166
"""
115
167
return self ._update ({'rm_scopes' : scopes }, note , note_url )
116
168
@@ -120,11 +172,15 @@ def replace_scopes(self, scopes, note=None, note_url=None):
120
172
121
173
.. versionadded:: 1.0
122
174
123
- :param list scopes: Use these scopes instead of the previous list
124
- :param str note: (optional), Note about the authorization
125
- :param str note_url: (optional), URL to link to when the user views
126
- the authorization
127
- :returns: True if successful, False otherwise
128
- :rtype: bool
175
+ :param list scopes:
176
+ Use these scopes instead of the previous list
177
+ :param str note:
178
+ (optional), Note about the authorization
179
+ :param str note_url:
180
+ (optional), URL to link to when the user views the authorization
181
+ :returns:
182
+ True if successful, False otherwise
183
+ :rtype:
184
+ bool
129
185
"""
130
186
return self ._update ({'scopes' : scopes }, note , note_url )
0 commit comments