Merge pull request #1053 from sigmavirus24/docs-updates

Small updates prior to 4.0

docs/source/api-reference/index.rst

@@ -15,6 +15,7 @@
     issues
     notifications
     orgs
+    projects
     pulls
     repos
     search

docs/source/api-reference/projects.rst

@@ -0,0 +1,24 @@
+========================================
+ Projectss and their Associated Objects
+========================================
+
+This section of the documentation covers the representations of various
+objects related to the `Projects API`_.
+
+Project Objects
+---------------
+
+.. autoclass:: github3.projects.Project
+    :inherited-members:
+
+.. autoclass:: github3.projects.ProjectColumn
+    :inherited-members:
+
+.. autoclass:: github3.projects.ProjectCard
+    :inherited-members:
+
+
+.. ---
+.. links
+.. _Projects API:
+    https://docs.github.com/en/rest/reference/projects

docs/source/api-reference/users.rst

@@ -12,6 +12,9 @@ User Objects
 .. autoclass:: github3.users.ShortUser
     :inherited-members:
 
+.. autoclass:: github3.users.Stargazer
+    :inherited-members:
+
 .. autoclass:: github3.users.User
     :inherited-members:
 

docs/source/index.rst

@@ -48,7 +48,6 @@ There are several examples of different aspects of using github3.py
     examples/git
     examples/github
     examples/issue
-    examples/iterators
     examples/logging
     examples/octocat
 

docs/source/release-notes/3.0.0.rst

@@ -1,4 +1,4 @@
-3.0.0: 2021-10-30
+3.0.0: 2021-10-31
 -----------------
 
 Backwards Incompatible Changes
@@ -32,3 +32,6 @@ Features Added
 
 - Add support for beta branch synchronization endpoint
   :meth:`~github3.repos.branch.Branch.sync_with_upstream`
+
+- :class:`~github3.users.Stargazer` was added to give access to the
+  ``starred_at`` value when listing stargazers on a Repository object.

src/github3/github.py

@@ -1428,12 +1428,16 @@ def login_as_app(
         self.session.app_bearer_token_auth(token, expire_in)
 
     def login_as_app_installation(
-        self, private_key_pem, app_id, installation_id
+        self, private_key_pem, app_id, installation_id, expire_in=30
     ):
         """Login using your GitHub App's installation credentials.
 
         .. versionadded:: 1.2.0
 
+        .. versionchanged:: 3.0.0
+
+            Added ``expire_in`` parameter.
+
         .. seealso::
 
             `Authenticating as an Installation`_
@@ -1455,17 +1459,23 @@ def login_as_app_installation(
             The integer identifier for this GitHub Application.
         :param int installation_id:
             The integer identifier of your App's installation.
+        :param int expire_in:
+            (Optional) The number of seconds in the future that the underlying
+            JWT expires. To prevent tokens from being valid for too long and
+            creating a security risk, the library defaults to 30 seconds. In
+            the event that clock drift is significant between your machine and
+            GitHub's servers, you can set this higher than 30.
+            Default: 30
 
         .. _Authenticating as an Installation:
             https://developer.github.com/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-an-installation
         .. _Create a new installation token:
             https://developer.github.com/v3/apps/#create-a-new-installation-token
         """
-        # NOTE(sigmavirus24): This JWT token does not need to last very long.
-        # Instead of allowing it to stick around for 10 minutes, let's limit
-        # it to 30 seconds.
-        jwt_token = apps.create_token(private_key_pem, app_id, expire_in=30)
-        bearer_auth = session.AppBearerTokenAuth(jwt_token, 30)
+        jwt_token = apps.create_token(
+            private_key_pem, app_id, expire_in=expire_in
+        )
+        bearer_auth = session.AppBearerTokenAuth(jwt_token, expire_in)
         url = self._build_url(
             "app", "installations", str(installation_id), "access_tokens"
         )

src/github3/orgs.py

@@ -27,6 +27,9 @@ def _update_attributes(self, team):
         self.members_urlt = URITemplate(team["members_url"])
         self.name = team["name"]
         self.permission = team["permission"]
+        self.privacy = team.get(
+            "privacy"
+        )  # TODO: Re-record cassettes to ensure this exists
         self.repositories_url = team["repositories_url"]
         self.slug = team["slug"]
 
@@ -302,6 +305,10 @@ class ShortTeam(_Team):
         The level of permissions this team has, e.g., ``push``, ``pull``,
         or ``admin``.
 
+    .. attribute:: privacy
+
+        The privacy level of this team inside the organization.
+
     .. attribute:: repos_count
 
         The number of repositories this team can access.

src/github3/repos/repo.py

@@ -2630,10 +2630,16 @@ def stargazers(self, number=-1, etag=None):
         :returns:
             generator of users
         :rtype:
-            :class:`~github3.users.ShortUser`
+            :class:`~github3.users.Stargazer`
         """
         url = self._build_url("stargazers", base_url=self._api)
-        return self._iter(int(number), url, users.ShortUser, etag=etag)
+        return self._iter(
+            int(number),
+            url,
+            users.Stargazer,
+            etag=etag,
+            headers={"Accept": "application/vnd.github.v3.star+json"},
+        )
 
     def statuses(self, sha, number=-1, etag=None):
         """Iterate over the statuses for a specific SHA.

src/github3/users.py

@@ -840,6 +840,28 @@ class ShortUser(_User):
     _refresh_to = User
 
 
+class Stargazer(_User):
+    """Object representing a user that has starred a repository.
+
+    .. versionadded:: 3.0.0
+
+    This object contains all of the attributes available on
+    :class:`~github3.users.ShortUser` as well as the following:
+
+    .. attribute:: starred_at
+
+        The time and date that the user starred the repository this was
+        queried from.
+    """
+
+    class_name = "Stargazer"
+    _refresh_to = User
+
+    def _update_attributes(self, stargazer):
+        super()._update_attributes(stargazer["user"])
+        self.starred_at = self._strptime(stargazer["starred_at"])
+
+
 class AuthenticatedUser(User):
     """Object to represent the currently authenticated user.
 

tests/integration/test_repos_repo.py

@@ -1212,7 +1212,8 @@ def test_stargazers(self):
 
         assert len(stargazers) > 0
         for user in stargazers:
-            assert isinstance(user, github3.users.ShortUser)
+            assert isinstance(user, github3.users._User)
+            assert isinstance(user, github3.users.Stargazer)
 
     def test_statuses(self):
         """Test the ability to retrieve a commit's statuses."""

tests/unit/test_repos_repo.py

@@ -1384,7 +1384,9 @@ def test_stargazers(self):
         self.get_next(i)
 
         self.session.get.assert_called_once_with(
-            url_for("stargazers"), params={"per_page": 100}, headers={}
+            url_for("stargazers"),
+            params={"per_page": 100},
+            headers={"Accept": "application/vnd.github.v3.star+json"},
         )
 
     def test_statuses(self):