feat: display human-readable attribute in `repr()` if present

17 files changed, 54 insertions, 51 deletions

diff --git a/gitlab/base.py b/gitlab/base.py
index 7f68542..a1cd30f 100644
--- a/gitlab/base.py
+++ b/gitlab/base.py
@@ -49,8 +49,12 @@ class RESTObject:
     another. This allows smart updates, if the object allows it.
 
     You can redefine ``_id_attr`` in child classes to specify which attribute
-    must be used as uniq ID. ``None`` means that the object can be updated
+    must be used as the unique ID. ``None`` means that the object can be updated
     without ID in the url.
+
+    Likewise, you can define a ``_repr_attr`` in subclasses to specify which
+    attribute should be added as a human-readable identifier when called in the
+    object's ``__repr__()`` method.
     """
 
     _id_attr: Optional[str] = "id"
@@ -58,7 +62,7 @@ class RESTObject:
     _created_from_list: bool  # Indicates if object was created from a list() action
     _module: ModuleType
     _parent_attrs: Dict[str, Any]
-    _short_print_attr: Optional[str] = None
+    _repr_attr: Optional[str] = None
     _updated_attrs: Dict[str, Any]
     manager: "RESTManager"
 
@@ -158,10 +162,19 @@ class RESTObject:
         print(self.pformat())
 
     def __repr__(self) -> str:
+        name = self.__class__.__name__
+
+        if (self._id_attr and self._repr_attr) and (self._id_attr != self._repr_attr):
+            return (
+                f"<{name} {self._id_attr}:{self.get_id()} "
+                f"{self._repr_attr}:{getattr(self, self._repr_attr)}>"
+            )
         if self._id_attr:
-            return f"<{self.__class__.__name__} {self._id_attr}:{self.get_id()}>"
-        else:
-            return f"<{self.__class__.__name__}>"
+            return f"<{name} {self._id_attr}:{self.get_id()}>"
+        if self._repr_attr:
+            return f"<{name} {self._repr_attr}:{getattr(self, self._repr_attr)}>"
+
+        return f"<{name}>"
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, RESTObject):
diff --git a/gitlab/v4/cli.py b/gitlab/v4/cli.py
index 6830b08..245897e 100644
--- a/gitlab/v4/cli.py
+++ b/gitlab/v4/cli.py
@@ -449,12 +449,12 @@ class LegacyPrinter:
             if obj._id_attr:
                 id = getattr(obj, obj._id_attr)
                 print(f"{obj._id_attr.replace('_', '-')}: {id}")
-            if obj._short_print_attr:
-                value = getattr(obj, obj._short_print_attr) or "None"
+            if obj._repr_attr:
+                value = getattr(obj, obj._repr_attr, "None")
                 value = value.replace("\r", "").replace("\n", " ")
                 # If the attribute is a note (ProjectCommitComment) then we do
                 # some modifications to fit everything on one line
-                line = f"{obj._short_print_attr}: {value}"
+                line = f"{obj._repr_attr}: {value}"
                 # ellipsize long lines (comments)
                 if len(line) > 79:
                     line = f"{line[:76]}..."
diff --git a/gitlab/v4/objects/applications.py b/gitlab/v4/objects/applications.py
index c91dee1..926d189 100644
--- a/gitlab/v4/objects/applications.py
+++ b/gitlab/v4/objects/applications.py
@@ -9,7 +9,7 @@ __all__ = [
 
 class Application(ObjectDeleteMixin, RESTObject):
     _url = "/applications"
-    _short_print_attr = "name"
+    _repr_attr = "name"
 
 
 class ApplicationManager(ListMixin, CreateMixin, DeleteMixin, RESTManager):
diff --git a/gitlab/v4/objects/commits.py b/gitlab/v4/objects/commits.py
index 5f13f5c..19098af 100644
--- a/gitlab/v4/objects/commits.py
+++ b/gitlab/v4/objects/commits.py
@@ -21,7 +21,7 @@ __all__ = [
 
 
 class ProjectCommit(RESTObject):
-    _short_print_attr = "title"
+    _repr_attr = "title"
 
     comments: "ProjectCommitCommentManager"
     discussions: ProjectCommitDiscussionManager
@@ -172,7 +172,7 @@ class ProjectCommitManager(RetrieveMixin, CreateMixin, RESTManager):
 
 class ProjectCommitComment(RESTObject):
     _id_attr = None
-    _short_print_attr = "note"
+    _repr_attr = "note"
 
 
 class ProjectCommitCommentManager(ListMixin, CreateMixin, RESTManager):
diff --git a/gitlab/v4/objects/events.py b/gitlab/v4/objects/events.py
index b7d8fd1..048f280 100644
--- a/gitlab/v4/objects/events.py
+++ b/gitlab/v4/objects/events.py
@@ -29,7 +29,7 @@ __all__ = [
 
 class Event(RESTObject):
     _id_attr = None
-    _short_print_attr = "target_title"
+    _repr_attr = "target_title"
 
 
 class EventManager(ListMixin, RESTManager):
diff --git a/gitlab/v4/objects/files.py b/gitlab/v4/objects/files.py
index 435e71b..e5345ce 100644
--- a/gitlab/v4/objects/files.py
+++ b/gitlab/v4/objects/files.py
@@ -24,7 +24,7 @@ __all__ = [
 
 class ProjectFile(SaveMixin, ObjectDeleteMixin, RESTObject):
     _id_attr = "file_path"
-    _short_print_attr = "file_path"
+    _repr_attr = "file_path"
     file_path: str
     manager: "ProjectFileManager"
 
diff --git a/gitlab/v4/objects/groups.py b/gitlab/v4/objects/groups.py
index a3a1051..28f3623 100644
--- a/gitlab/v4/objects/groups.py
+++ b/gitlab/v4/objects/groups.py
@@ -48,7 +48,7 @@ __all__ = [
 
 
 class Group(SaveMixin, ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "name"
+    _repr_attr = "name"
 
     access_tokens: GroupAccessTokenManager
     accessrequests: GroupAccessRequestManager
diff --git a/gitlab/v4/objects/hooks.py b/gitlab/v4/objects/hooks.py
index 0b0092e..f37d514 100644
--- a/gitlab/v4/objects/hooks.py
+++ b/gitlab/v4/objects/hooks.py
@@ -15,7 +15,7 @@ __all__ = [
 
 class Hook(ObjectDeleteMixin, RESTObject):
     _url = "/hooks"
-    _short_print_attr = "url"
+    _repr_attr = "url"
 
 
 class HookManager(NoUpdateMixin, RESTManager):
@@ -28,7 +28,7 @@ class HookManager(NoUpdateMixin, RESTManager):
 
 
 class ProjectHook(SaveMixin, ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "url"
+    _repr_attr = "url"
 
 
 class ProjectHookManager(CRUDMixin, RESTManager):
@@ -75,7 +75,7 @@ class ProjectHookManager(CRUDMixin, RESTManager):
 
 
 class GroupHook(SaveMixin, ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "url"
+    _repr_attr = "url"
 
 
 class GroupHookManager(CRUDMixin, RESTManager):
diff --git a/gitlab/v4/objects/issues.py b/gitlab/v4/objects/issues.py
index f20252b..693c18f 100644
--- a/gitlab/v4/objects/issues.py
+++ b/gitlab/v4/objects/issues.py
@@ -42,7 +42,7 @@ __all__ = [
 
 class Issue(RESTObject):
     _url = "/issues"
-    _short_print_attr = "title"
+    _repr_attr = "title"
 
 
 class IssueManager(RetrieveMixin, RESTManager):
@@ -108,7 +108,7 @@ class ProjectIssue(
     ObjectDeleteMixin,
     RESTObject,
 ):
-    _short_print_attr = "title"
+    _repr_attr = "title"
     _id_attr = "iid"
 
     awardemojis: ProjectIssueAwardEmojiManager
diff --git a/gitlab/v4/objects/members.py b/gitlab/v4/objects/members.py
index 5ee0b0e..d5d8766 100644
--- a/gitlab/v4/objects/members.py
+++ b/gitlab/v4/objects/members.py
@@ -28,7 +28,7 @@ __all__ = [
 
 
 class GroupMember(SaveMixin, ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "username"
+    _repr_attr = "username"
 
 
 class GroupMemberManager(CRUDMixin, RESTManager):
@@ -50,7 +50,7 @@ class GroupMemberManager(CRUDMixin, RESTManager):
 
 
 class GroupBillableMember(ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "username"
+    _repr_attr = "username"
 
     memberships: "GroupBillableMemberMembershipManager"
 
@@ -73,7 +73,7 @@ class GroupBillableMemberMembershipManager(ListMixin, RESTManager):
 
 
 class GroupMemberAll(RESTObject):
-    _short_print_attr = "username"
+    _repr_attr = "username"
 
 
 class GroupMemberAllManager(RetrieveMixin, RESTManager):
@@ -88,7 +88,7 @@ class GroupMemberAllManager(RetrieveMixin, RESTManager):
 
 
 class ProjectMember(SaveMixin, ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "username"
+    _repr_attr = "username"
 
 
 class ProjectMemberManager(CRUDMixin, RESTManager):
@@ -110,7 +110,7 @@ class ProjectMemberManager(CRUDMixin, RESTManager):
 
 
 class ProjectMemberAll(RESTObject):
-    _short_print_attr = "username"
+    _repr_attr = "username"
 
 
 class ProjectMemberAllManager(RetrieveMixin, RESTManager):
diff --git a/gitlab/v4/objects/merge_request_approvals.py b/gitlab/v4/objects/merge_request_approvals.py
index d34484b..3617131 100644
--- a/gitlab/v4/objects/merge_request_approvals.py
+++ b/gitlab/v4/objects/merge_request_approvals.py
@@ -165,7 +165,7 @@ class ProjectMergeRequestApprovalManager(GetWithoutIdMixin, UpdateMixin, RESTMan
 
 class ProjectMergeRequestApprovalRule(SaveMixin, ObjectDeleteMixin, RESTObject):
     _id_attr = "approval_rule_id"
-    _short_print_attr = "approval_rule"
+    _repr_attr = "approval_rule"
     id: int
 
     @exc.on_http_error(exc.GitlabUpdateError)
diff --git a/gitlab/v4/objects/milestones.py b/gitlab/v4/objects/milestones.py
index da75826..e415330 100644
--- a/gitlab/v4/objects/milestones.py
+++ b/gitlab/v4/objects/milestones.py
@@ -22,7 +22,7 @@ __all__ = [
 
 
 class GroupMilestone(SaveMixin, ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "title"
+    _repr_attr = "title"
 
     @cli.register_custom_action("GroupMilestone")
     @exc.on_http_error(exc.GitlabListError)
@@ -102,7 +102,7 @@ class GroupMilestoneManager(CRUDMixin, RESTManager):
 
 
 class ProjectMilestone(PromoteMixin, SaveMixin, ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "title"
+    _repr_attr = "title"
     _update_uses_post = True
 
     @cli.register_custom_action("ProjectMilestone")
diff --git a/gitlab/v4/objects/projects.py b/gitlab/v4/objects/projects.py
index 7d9c834..b7df9ab 100644
--- a/gitlab/v4/objects/projects.py
+++ b/gitlab/v4/objects/projects.py
@@ -129,7 +129,7 @@ class ProjectGroupManager(ListMixin, RESTManager):
 
 
 class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTObject):
-    _short_print_attr = "path"
+    _repr_attr = "path"
 
     access_tokens: ProjectAccessTokenManager
     accessrequests: ProjectAccessRequestManager
@@ -186,16 +186,6 @@ class Project(RefreshMixin, SaveMixin, ObjectDeleteMixin, RepositoryMixin, RESTO
     variables: ProjectVariableManager
     wikis: ProjectWikiManager
 
-    def __repr__(self) -> str:
-        project_repr = super().__repr__()
-
-        if hasattr(self, "name_with_namespace"):
-            return (
-                f'{project_repr[:-1]} name_with_namespace:"{self.name_with_namespace}">'
-            )
-        else:
-            return project_repr
-
     @cli.register_custom_action("Project", ("forked_from_id",))
     @exc.on_http_error(exc.GitlabCreateError)
     def create_fork_relation(self, forked_from_id: int, **kwargs: Any) -> None:
diff --git a/gitlab/v4/objects/snippets.py b/gitlab/v4/objects/snippets.py
index 9d9dcc4..83b1378 100644
--- a/gitlab/v4/objects/snippets.py
+++ b/gitlab/v4/objects/snippets.py
@@ -21,7 +21,7 @@ __all__ = [
 
 
 class Snippet(UserAgentDetailMixin, SaveMixin, ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "title"
+    _repr_attr = "title"
 
     @cli.register_custom_action("Snippet")
     @exc.on_http_error(exc.GitlabGetError)
@@ -91,7 +91,7 @@ class SnippetManager(CRUDMixin, RESTManager):
 
 class ProjectSnippet(UserAgentDetailMixin, SaveMixin, ObjectDeleteMixin, RESTObject):
     _url = "/projects/{project_id}/snippets"
-    _short_print_attr = "title"
+    _repr_attr = "title"
 
     awardemojis: ProjectSnippetAwardEmojiManager
     discussions: ProjectSnippetDiscussionManager
diff --git a/gitlab/v4/objects/tags.py b/gitlab/v4/objects/tags.py
index c76799d..748cbad 100644
--- a/gitlab/v4/objects/tags.py
+++ b/gitlab/v4/objects/tags.py
@@ -13,7 +13,7 @@ __all__ = [
 
 class ProjectTag(ObjectDeleteMixin, RESTObject):
     _id_attr = "name"
-    _short_print_attr = "name"
+    _repr_attr = "name"
 
 
 class ProjectTagManager(NoUpdateMixin, RESTManager):
@@ -30,7 +30,7 @@ class ProjectTagManager(NoUpdateMixin, RESTManager):
 
 class ProjectProtectedTag(ObjectDeleteMixin, RESTObject):
     _id_attr = "name"
-    _short_print_attr = "name"
+    _repr_attr = "name"
 
 
 class ProjectProtectedTagManager(NoUpdateMixin, RESTManager):
diff --git a/gitlab/v4/objects/users.py b/gitlab/v4/objects/users.py
index ddcee70..09964b1 100644
--- a/gitlab/v4/objects/users.py
+++ b/gitlab/v4/objects/users.py
@@ -66,7 +66,7 @@ __all__ = [
 
 
 class CurrentUserEmail(ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "email"
+    _repr_attr = "email"
 
 
 class CurrentUserEmailManager(RetrieveMixin, CreateMixin, DeleteMixin, RESTManager):
@@ -96,7 +96,7 @@ class CurrentUserGPGKeyManager(RetrieveMixin, CreateMixin, DeleteMixin, RESTMana
 
 
 class CurrentUserKey(ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "title"
+    _repr_attr = "title"
 
 
 class CurrentUserKeyManager(RetrieveMixin, CreateMixin, DeleteMixin, RESTManager):
@@ -112,7 +112,7 @@ class CurrentUserKeyManager(RetrieveMixin, CreateMixin, DeleteMixin, RESTManager
 
 class CurrentUserStatus(SaveMixin, RESTObject):
     _id_attr = None
-    _short_print_attr = "message"
+    _repr_attr = "message"
 
 
 class CurrentUserStatusManager(GetWithoutIdMixin, UpdateMixin, RESTManager):
@@ -128,7 +128,7 @@ class CurrentUserStatusManager(GetWithoutIdMixin, UpdateMixin, RESTManager):
 
 class CurrentUser(RESTObject):
     _id_attr = None
-    _short_print_attr = "username"
+    _repr_attr = "username"
 
     emails: CurrentUserEmailManager
     gpgkeys: CurrentUserGPGKeyManager
@@ -147,7 +147,7 @@ class CurrentUserManager(GetWithoutIdMixin, RESTManager):
 
 
 class User(SaveMixin, ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "username"
+    _repr_attr = "username"
 
     customattributes: UserCustomAttributeManager
     emails: "UserEmailManager"
@@ -373,7 +373,7 @@ class ProjectUserManager(ListMixin, RESTManager):
 
 
 class UserEmail(ObjectDeleteMixin, RESTObject):
-    _short_print_attr = "email"
+    _repr_attr = "email"
 
 
 class UserEmailManager(RetrieveMixin, CreateMixin, DeleteMixin, RESTManager):
@@ -392,7 +392,7 @@ class UserActivities(RESTObject):
 
 class UserStatus(RESTObject):
     _id_attr = None
-    _short_print_attr = "message"
+    _repr_attr = "message"
 
 
 class UserStatusManager(GetWithoutIdMixin, RESTManager):
diff --git a/gitlab/v4/objects/wikis.py b/gitlab/v4/objects/wikis.py
index c4055da..a7028cf 100644
--- a/gitlab/v4/objects/wikis.py
+++ b/gitlab/v4/objects/wikis.py
@@ -13,7 +13,7 @@ __all__ = [
 
 class ProjectWiki(SaveMixin, ObjectDeleteMixin, RESTObject):
     _id_attr = "slug"
-    _short_print_attr = "slug"
+    _repr_attr = "slug"
 
 
 class ProjectWikiManager(CRUDMixin, RESTManager):
@@ -34,7 +34,7 @@ class ProjectWikiManager(CRUDMixin, RESTManager):
 
 class GroupWiki(SaveMixin, ObjectDeleteMixin, RESTObject):
     _id_attr = "slug"
-    _short_print_attr = "slug"
+    _repr_attr = "slug"
 
 
 class GroupWikiManager(CRUDMixin, RESTManager):