Add Stargazer and use stargazer media type

Closes #594

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/release-notes/3.0.0.rst

@@ -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/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):