8000 Merge pull request #773 from sigmavirus24/consistency-is-a-hobgoblin · pythonthings/github3.py@508efde · GitHub
[go: up one dir, main page]
Skip to content

Commit 508efde

Browse files
sigmavirus24sigmavirus24
authored
Merge pull request sigmavirus24#773 from sigmavirus24/consistency-is-a-hobgoblin
Consistency is a hobgoblin of a small mind
2 parents 17d0fb9 + 7e5a00b commit 508efde

File tree

107 files changed

+7456
-3751
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

107 files changed

+7456
-3751
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,3 +18,4 @@ build/
1818
.ipynb_checkpoints
1919
.cache/
2020
tests/id_rsa
21+
*.DS_Store

‎LATEST_VERSION_NOTES.rst

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,38 @@
33
Unreleased
44
~~~~~~~~~~
55

6+
Breaking Changes (since 1.0.0a4)
7+
````````````````````````````````
8+
9+
- Remove ``Thread.comment``, ``Thread.thread``, ``Thread.urls`` attributes.
10+
11+
- Remove ``Thread#is_unread`` method. Use the ``Thread.unread`` attribute
12+
instead.
13+
14+
- ``Subscription`` has been split into two objects: ``ThreadSubscription`` and
15+
``RepositorySubscription`` with the same methods.
16+
17+
- Remove ``is_ignored`` method from our Subscription objects. Use the
18+
``ignored`` attribute instead.
19+
20+
- Remove ``is_subscribed`` method from our Subscription objects. Use the
21+
``subscribed`` attribute instead.
22+
23+
Features Added (since 1.0.0a4)
24+
``````````````````````````````
25+
626
- Add ``Organization#all_events``.
7-
- Deprecate ``Organization#events`` in favor of ``Organization#public_events``.
8-
- Fix test failtures on windows caused by unclosed file handles.
27+
928
- Add ``Tag.tagger_as_User`` which attempts to return the tagger as as User.
29+
1030
- Add ``Repo.statuses`` and a corresponding ``repo.status.CombinedStatus`` to
31+
32+
Deprecations and Other Changes (since 1.0.0a4)
33+
``````````````````````````````````````````````
34+
35+
- Deprecate ``Organization#events`` in favor of ``Organization#public_events``.
36+
37+
- Fix test failtures on windows caused by unclosed file handles.
1138
get a combined view of commit statuses for a given ref.
1239

1340
1.0.0a4: 2016-02-19
F438

‎docs/git.rst

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,6 @@ section of the GitHub API.
99

1010
- :class:`Blob <Blob>`
1111
- :class:`Commit <Commit>`
12-
- :class:`GitData <GitData>`
1312
- :class:`GitObject <GitObject>`
1413
- :class:`Hash <Hash>`
1514
- :class:`Reference <Reference>`
@@ -27,12 +26,12 @@ Git Objects
2726

2827
------
2928

30-
.. autoclass:: Commit
29+
.. autoclass:: ShortCommit
3130
:inherited-members:
3231

3332
------
3433

35-
.. autoclass:: GitData
34+
.. autoclass:: Commit
3635
:inherited-members:
3736

3837
------
@@ -59,3 +58,8 @@ Git Objects
5958

6059
.. autoclass:: Tree
6160
:inherited-members:
61+
62+
------
63+
64+
.. autoclass:: CommitTree
65+
:inherited-members:

‎docs/models.rst

Lines changed: 0 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,3 @@ Objects
1313

1414
.. autoclass:: GitHubCore
1515
:inherited-members:
16-
17-
------
18-
19-
.. autoclass:: BaseAccount
20-
:inherited-members:
21-
22-
------
23-
24-
.. autoclass:: BaseComment
25-
:inherited-members:
26-
27-
------
28-
29-
.. autoclass:: BaseCommit
30-
:inherited-members:

‎docs/notifications.rst

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,10 @@
44
Notifications
55
=============
66

7-
This part of the documentation covers the :class:`Thread <Thread>` and
8-
:class:`Subscription <Subscription>` objects.
7+
This part of the documentation covers the
8+
:class:`~github3.notifications.Thread`,
9+
:class:`~github3.notifications.RepositorySubscription`, and
10+
:class:`~github3.notifications.ThreadSubscription` objects.
911

1012
Notification Objects
1113
--------------------
@@ -15,5 +17,10 @@ Notification Objects
1517

1618
------
1719

18-
.. autoclass:: Subscription
20+
.. autoclass:: RepositorySubscription
21+
:inherited-members:
22+
23+
------
24+
25+
.. autoclass:: ThreadSubscription
1926
:inherited-members:

‎github3/auths.py

Lines changed: 114 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,104 @@
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."""
93
from __future__ import unicode_literals
104

115
from .decorators import requires_basic_auth
126
from .models import GitHubCore
137

148

159
class 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)

‎github3/decorators.py

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,5 @@
11
# -*- coding: utf-8 -*-
2-
"""
3-
github3.decorators
4-
==================
5-
6-
This module provides decorators to the rest of the library
7-
8-
"""
2+
"""This module provides decorators to the rest of the library."""
93

104
from functools import wraps
115
from requests.models import Response
@@ -20,7 +14,10 @@
2014

2115

2216
class RequestsStringIO(StringIO):
17+
"""Shim compatibility for string IO."""
18+
2319
def read(self, n=-1, *args, **kwargs):
20+
"""Ignore extra args and kwargs."""
2421
# StringIO is an old-style class, so can't use super
2522
return StringIO.read(self, n)
2623

@@ -86,6 +83,7 @@ def auth_wrapper(self, *args, **kwargs):
8683

8784

8885
def generate_fake_error_response(msg, status_code=401, encoding='utf-8'):
86+
"""Generate a fake Response from requests."""
8987
r = Response()
9088
r.status_code = status_code
9189
r.encoding = encoding

0 commit comments

Comments
 (0)
0