11# -*- 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."""
93from __future__ import unicode_literals
104
115from .decorators import requires_basic_auth
126from .models import GitHubCore
137
148
159class Authorization (GitHubCore ):
10+ """Representation of an OAuth Authorization.
1611
17- """The :class:`Authorization <Authorization>` object.
12+ See also: https://developer.github.com/v3/oauth_authorizations/
1813
19- Two authorization instances can be checked like so: :
14+ This object has the following attributes :
2015
21- a1 == a2
22- a1 != a2
16+ .. attribute:: app
2317
24- And is equivalent to::
18+ Details about the application the authorization was created for.
2519
26- a1.id == a2.id
27- a1.id != a2.id
20+ .. attribute:: created_at
2821
29- See also: http://developer.github.com/v3/oauth/#oauth-authorizations-api
22+ A :class:`~datetime.datetime` representing when this authorization was
23+ created.
3024
31- """
25+ .. attribute:: fingerprint
3226
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.
3547
36- #: Details about the application (name, url)
37- self .app = self ._get_attribute (auth , 'app' , {})
48+ .. attribute:: note_url
3849
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.
4152
42- #: App name
43- self .name = self ._get_attribute (self .app , 'name' )
53+ .. attribute:: note
4454
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.
4756
48- #: Note about the authorization
49- self .note = self ._get_attribute (auth , 'note' )
57+ .. attribute:: scopes
5058
51- #: List of scopes this applies to
52- self .scopes = self ._get_attribute (auth , 'scopes' )
59+ The list of scopes assigned to this token.
5360
54- #: Unique id of the authorization
55- self .id = self ._get_attribute (auth , 'id' )
61+ .. seealso::
5662
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
5966
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' ])
62102
63103 def _repr (self ):
64104 return '<Authorization [{0}]>' .format (self .name )
@@ -79,23 +119,32 @@ def _update(self, scopes_data, note, note_url):
79119
80120 @requires_basic_auth
81121 def add_scopes (self , scopes , note = None , note_url = None ):
82- """Adds the scopes to this authorization.
122+ """Add the scopes to this authorization.
83123
84124 .. versionadded:: 1.0
85125
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
93136 """
94137 return self ._update ({'add_scopes' : scopes }, note , note_url )
95138
96139 @requires_basic_auth
97140 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+ """
99148 return self ._boolean (self ._delete (self ._api ), 204 , 404 )
100149
101150 @requires_basic_auth
@@ -104,13 +153,16 @@ def remove_scopes(self, scopes, note=None, note_url=None):
104153
105154 .. versionadded:: 1.0
106155
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
114166 """
115167 return self ._update ({'rm_scopes' : scopes }, note , note_url )
116168
@@ -120,11 +172,15 @@ def replace_scopes(self, scopes, note=None, note_url=None):
120172
121173 .. versionadded:: 1.0
122174
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
129185 """
130186 return self ._update ({'scopes' : scopes }, note , note_url )
0 commit comments