8000 Merge pull request #1053 from sigmavirus24/docs-updates · davisagli/github3.py@535eb22 · GitHub
[go: up one dir, main page]
Skip to content

Commit 535eb22

Browse files
sigmavirus24sigmavirus24
authored
Merge pull request sigmavirus24#1053 from sigmavirus24/docs-updates
Small updates prior to 4.0
2 parents 9218903 + 0777b75 commit 535eb22

File tree

13 files changed

+91
-84
lines changed

13 files changed

+91
-84
lines changed

‎docs/source/api-reference/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
issues
1616
notifications
1717
orgs
18+
projects
1819
pulls
1920
repos
2021
search

‎docs/source/api-reference/projects.rst

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
========================================
2+
Projectss and their Associated Objects
3+
========================================
4+
5+
This section of the documentation covers the representations of various
6+
objects related to the `Projects API`_.
7+
8+
Project Objects
9+
---------------
10+
11+
.. autoclass:: github3.projects.Project
12+
:inherited-members:
13+
14+
.. autoclass:: github3.projects.ProjectColumn
15+
:inherited-members:
16+
17+
.. autoclass:: github3.projects.ProjectCard
18+
:inherited-members:
19+
20+
21+
.. ---
22+
.. links
23+
.. _Projects API:
24+
https://docs.github.com/en/rest/reference/projects

‎docs/source/api-reference/users.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,9 @@ User Objects
1212
.. autoclass:: github3.users.ShortUser
1313
:inherited-members:
1414

15+
.. autoclass:: github3.users.Stargazer
16+
:inherited-members:
17+
1518
.. autoclass:: github3.users.User
1619
:inherited-members:
1720

‎docs/source/examples/iterators.rst

Lines changed: 0 additions & 71 deletions
This file was deleted.

‎docs/source/index.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,6 @@ There are several examples of different aspects of using github3.py
4848
examples/git
4949
examples/github
5050
examples/issue
51-
examples/iterators
5251
examples/logging
5352
examples/octocat
5453

‎docs/source/release-notes/3.0.0.rst

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
3.0.0: 2021-10-30
1+
3.0.0: 2021-10-31
22
-----------------
33

44
Backwards Incompatible Changes
@@ -32,3 +32,6 @@ Features Added
3232

3333
- Add support for beta branch synchronization endpoint
3434
:meth:`~github3.repos.branch.Branch.sync_with_upstream`
35+
36+
- :class:`~github3.users.Stargazer` was added to give access to the
37+
``starred_at`` value when listing stargazers on a Repository object.

‎src/github3/github.py

Lines changed: 16 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1428,12 +1428,16 @@ def login_as_app(
14281428
self.session.app_bearer_token_auth(token, expire_in)
14291429

14301430
def login_as_app_installation(
1431-
self, private_key_pem, app_id, installation_id
1431+
self, private_key_pem, app_id, installation_id, expire_in=30
14321432
):
14331433
"""Login using your GitHub App's installation credentials.
14341434
14351435
.. versionadded:: 1.2.0
14361436
1437+
.. versionchanged:: 3.0.0
1438+
1439+
Added ``expire_in`` parameter.
1440+
14371441
.. seealso::
14381442
14391443
`Authenticating as an Installation`_
@@ -1455,17 +1459,23 @@ def login_as_app_installation(
14551459
The integer identifier for this GitHub Application.
14561460
:param int installation_id:
14571461
The integer identifier of your App's installation.
1462+
:param int expire_in:
1463+
(Optional) The number of seconds in the future that the underlying
1464+
JWT expires. To prevent tokens from being valid for too long and
1465+
creating a security risk, the library defaults to 30 seconds. In
1466+
the event that clock drift is significant between your machine and
1467+
GitHub's servers, you can set this higher than 30.
1468+
Default: 30
14581469
14591470
.. _Authenticating as an Installation:
14601471
https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation
14611472
.. _Create a new installation token:
14621473
https://developer.github.com/v3/apps/#create-a-new-installation-token
14631474
"""
1464-
# NOTE(sigmavirus24): This JWT token does not need to last very long.
1465-
# Instead of allowing it to stick around for 10 minutes, let's limit
1466-
# it to 30 seconds.
1467-
jwt_token = apps.create_token(private_key_pem, app_id, expire_in=30)
1468-
bearer_auth = session.AppBearerTokenAuth(jwt_token, 30)
1475+
jwt_token = apps.create_token(
1476+
private_key_pem, app_id, expire_in=expire_in
1477+
)
1478+
bearer_auth = session.AppBearerTokenAuth(jwt_token, expire_in)
14691479
url = self._build_url(
14701480
"app", "installations", str(installation_id), "access_tokens"
14711481
)

‎src/github3/orgs.py

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ def _update_attributes(self, team):
2727
self.members_urlt = URITemplate(team["members_url"])
2828
self.name = team["name"]
2929
self.permission = team["permission"]
30+
self.privacy = team.get(
31+
"privacy"
32+
) # TODO: Re-record cassettes to ensure this exists
3033
self.repositories_url = team["repositories_url"]
3134
self.slug = team["slug"]
3235

@@ -302,6 +305,10 @@ class ShortTeam(_Team):
302305
The level of permissions this team has, e.g., ``push``, ``pull``,
303306
or ``admin``.
304307
308+
.. attribute:: privacy
309+
310+
The privacy level of this team inside the organization.
311+
305312
.. attribute:: repos_count
306313
307314
The number of repositories this team can access.

‎src/github3/repos/repo.py

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2630,10 +2630,16 @@ def stargazers(self, number=-1, etag=None):
26302630
:returns:
26312631
generator of users
26322632
:rtype:
2633-
:class:`~github3.users.ShortUser`
2633+
:class:`~github3.users.Stargazer`
26342634
"""
26352635
url = self._build_url("stargazers", base_url=self._api)
2636-
return self._iter(int(number), url, users.ShortUser, etag=etag)
2636+
return self._iter(
2637+
int(number),
2638+
url,
2639+
users.Stargazer,
2640+
etag=etag,
2641+
headers={"Accept": "application/vnd.github.v3.star+json"},
2642+
)
26372643

26382644
def statuses(self, sha, number=-1, etag=None):
26392645
"""Iterate over the statuses for a specific SHA.

‎src/github3/users.py

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -840,6 +840,28 @@ class ShortUser(_User):
840840
_refresh_to = User
841841

842842

843+
class Stargazer(_User):
844+
"""Object representing a user that has starred a repository.
845+
846+
.. versionadded:: 3.0.0
847+
848+
This object contains all of the attributes available on
849+
:class:`~github3.users.ShortUser` as well as the following:
850+
851+
.. attribute:: starred_at
852+
853+
The time and date that the user starred the repository this was
854+
queried from.
855+
"""
856+
857+
class_name = "Stargazer"
858+
_refresh_to = User
859+
860+
def _update_attributes(self, stargazer):
861+
super()._update_attributes(stargazer["user"])
862+
self.starred_at = self._strptime(stargazer["starred_at"])
863+
864+
843865
class AuthenticatedUser(User):
844866
"""Object to represent the currently authenticated user.
845867

0 commit comments

Comments
 (0)
0