feat(objects): list starred projects of a userfeat/starred-projects

4 files changed, 73 insertions, 3 deletions

diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
index 0b251ea..c00c554 100644
--- a/docs/gl_objects/projects.rst
+++ b/docs/gl_objects/projects.rst
@@ -57,6 +57,11 @@ Results can also be sorted using the following parameters:
 
 .. note::
 
+   To list the starred projects of another user, see the
+   :ref:`Users API docs <users_examples>`.
+
+.. note::
+
    Fetching a list of projects, doesn't include all attributes of all projects.
    To retrieve all attributes, you'll need to fetch a single project
 
diff --git a/docs/gl_objects/users.rst b/docs/gl_objects/users.rst
index dd6db6a..aa3a660 100644
--- a/docs/gl_objects/users.rst
+++ b/docs/gl_objects/users.rst
@@ -1,3 +1,5 @@
+.. _users_examples:
+
 ######################
 Users and current user
 ######################
@@ -19,7 +21,10 @@ References
   + :class:`gitlab.v4.objects.UserManager`
   + :attr:`gitlab.Gitlab.users`
 
-* GitLab API: https://docs.gitlab.com/ce/api/users.html
+* GitLab API:
+
+  + https://docs.gitlab.com/ce/api/users.html
+  + https://docs.gitlab.com/ee/api/projects.html#list-projects-starred-by-a-user
 
 Examples
 --------
@@ -97,6 +102,9 @@ Get the followings of a user
 
     user.following_users.list()
 
+List a user's starred projects
+
+    user.starred_projects.list()
 
 User custom attributes
 ======================
diff --git a/gitlab/v4/objects/users.py b/gitlab/v4/objects/users.py
index e4bbcf1..4f8721a 100644
--- a/gitlab/v4/objects/users.py
+++ b/gitlab/v4/objects/users.py
@@ -1,3 +1,8 @@
+"""
+GitLab API:
+https://docs.gitlab.com/ee/api/users.html
+https://docs.gitlab.com/ee/api/projects.html#list-projects-starred-by-a-user
+"""
 from typing import Any, cast, Dict, List, Union
 
 import requests
@@ -38,6 +43,8 @@ __all__ = [
     "UserManager",
     "ProjectUser",
     "ProjectUserManager",
+    "StarredProject",
+    "StarredProjectManager",
     "UserEmail",
     "UserEmailManager",
     "UserActivities",
@@ -129,6 +136,7 @@ class User(SaveMixin, ObjectDeleteMixin, RESTObject):
     memberships: "UserMembershipManager"
     personal_access_tokens: UserPersonalAccessTokenManager
     projects: "UserProjectManager"
+    starred_projects: "StarredProjectManager"
     status: "UserStatusManager"
 
     @cli.register_custom_action("User")
@@ -502,6 +510,32 @@ class UserProjectManager(ListMixin, CreateMixin, RESTManager):
         return ListMixin.list(self, path=path, **kwargs)
 
 
+class StarredProject(RESTObject):
+    pass
+
+
+class StarredProjectManager(ListMixin, RESTManager):
+    _path = "/users/%(user_id)s/starred_projects"
+    _obj_cls = StarredProject
+    _from_parent_attrs = {"user_id": "id"}
+    _list_filters = (
+        "archived",
+        "membership",
+        "min_access_level",
+        "order_by",
+        "owned",
+        "search",
+        "simple",
+        "sort",
+        "starred",
+        "statistics",
+        "visibility",
+        "with_custom_attributes",
+        "with_issues_enabled",
+        "with_merge_requests_enabled",
+    )
+
+
 class UserFollowersManager(ListMixin, RESTManager):
     _path = "/users/%(user_id)s/followers"
     _obj_cls = User
diff --git a/tests/unit/objects/test_users.py b/tests/unit/objects/test_users.py
index e46a315..a2ea5de 100644
--- a/tests/unit/objects/test_users.py
+++ b/tests/unit/objects/test_users.py
@@ -1,10 +1,14 @@
 """
-GitLab API: https://docs.gitlab.com/ce/api/users.html
+GitLab API:
+https://docs.gitlab.com/ce/api/users.html
+https://docs.gitlab.com/ee/api/projects.html#list-projects-starred-by-a-user
 """
 import pytest
 import responses
 
-from gitlab.v4.objects import User, UserMembership, UserStatus
+from gitlab.v4.objects import StarredProject, User, UserMembership, UserStatus
+
+from .test_projects import project_content
 
 
 @pytest.fixture
@@ -174,6 +178,19 @@ def resp_followers_following():
         yield rsps
 
 
+@pytest.fixture
+def resp_starred_projects():
+    with responses.RequestsMock() as rsps:
+        rsps.add(
+            method=responses.GET,
+            url="http://localhost/api/v4/users/1/starred_projects",
+            json=[project_content],
+            content_type="application/json",
+            status=200,
+        )
+        yield rsps
+
+
 def test_get_user(gl, resp_get_user):
     user = gl.users.get(1)
     assert isinstance(user, User)
@@ -215,3 +232,9 @@ def test_list_followers(user, resp_followers_following):
     assert followers[0].id == 2
     assert isinstance(followings[0], User)
     assert followings[1].id == 4
+
+
+def test_list_starred_projects(user, resp_starred_projects):
+    projects = user.starred_projects.list()
+    assert isinstance(projects[0], StarredProject)
+    assert projects[0].id == project_content["id"]