Add RepositoryDiscussion powered by GraphQL API (PyGithub#3048)

Adds `RepositoryDiscussion`, `RepositoryDiscussionComment` and
`RepositoryDiscussionCategory` as pure GraphQL API classes. Retrieved
GraphQL data with user-defined schema can be used to populate those
GraphQL objects and inner REST API objects (all other existing PyGithub
classes).

Fixes PyGithub#2283.

---------

Co-authored-by: Sebastián Ramírez <[email protected]>

Author: EnricoMi

github/DiscussionBase.py

@@ -0,0 +1,117 @@
+############################ Copyrights and license ############################
+#                                                                              #
+# Copyright 2024 Enrico Minack <[email protected]>                      #
+#                                                                              #
+# This file is part of PyGithub.                                               #
+# http://pygithub.readthedocs.io/                                              #
+#                                                                              #
+# PyGithub is free software: you can redistribute it and/or modify it under    #
+# the terms of the GNU Lesser General Public License as published by the Free  #
+# Software Foundation, either version 3 of the License, or (at your option)    #
+# any later version.                                                           #
+#                                                                              #
+# PyGithub is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS    #
+# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more #
+# details.                                                                     #
+#                                                                              #
+# You should have received a copy of the GNU Lesser General Public License     #
+# along with PyGithub. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                              #
+################################################################################
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+import github.GithubObject
+import github.NamedUser
+from github.GithubObject import Attribute, CompletableGithubObject, NotSet
+
+
+class DiscussionBase(CompletableGithubObject):
+    """
+    This class represents a the shared attributes between RepositoryDiscussion and TeamDiscussion
+    https://docs.github.com/en/graphql/reference/objects#discussion
+    https://docs.github.com/en/rest/reference/teams#discussions
+    """
+
+    def _initAttributes(self) -> None:
+        self._author: Attribute[github.NamedUser.NamedUser | None] = NotSet
+        self._body: Attribute[str] = NotSet
+        self._body_html: Attribute[str] = NotSet
+        self._created_at: Attribute[datetime] = NotSet
+        self._last_edited_at: Attribute[datetime] = NotSet
+        self._number: Attribute[int] = NotSet
+        self._title: Attribute[str] = NotSet
+        self._updated_at: Attribute[datetime] = NotSet
+        self._url: Attribute[str] = NotSet
+
+    def __repr__(self) -> str:
+        return self.get__repr__({"number": self._number.value, "title": self._title.value})
+
+    @property
+    def author(self) -> github.NamedUser.NamedUser | None:
+        self._completeIfNotSet(self._author)
+        return self._author.value
+
+    @property
+    def body(self) -> str:
+        self._completeIfNotSet(self._body)
+        return self._body.value
+
+    @property
+    def body_html(self) -> str:
+        self._completeIfNotSet(self._body_html)
+        return self._body_html.value
+
+    @property
+    def created_at(self) -> datetime:
+        self._completeIfNotSet(self._created_at)
+        return self._created_at.value
+
+    @property
+    def last_edited_at(self) -> datetime:
+        self._completeIfNotSet(self._last_edited_at)
+        return self._last_edited_at.value
+
+    @property
+    def number(self) -> int:
+        self._completeIfNotSet(self._number)
+        return self._number.value
+
+    @property
+    def title(self) -> str:
+        self._completeIfNotSet(self._title)
+        return self._title.value
+
+    @property
+    def updated_at(self) -> datetime:
+        self._completeIfNotSet(self._updated_at)
+        return self._updated_at.value
+
+    @property
+    def url(self) -> str:
+        self._completeIfNotSet(self._url)
+        return self._url.value
+
+    def _useAttributes(self, attributes: dict[str, Any]) -> None:
+        if "author" in attributes:  # pragma no branch
+            self._author = self._makeClassAttribute(github.NamedUser.NamedUser, attributes["author"])
+        if "body" in attributes:  # pragma no branch
+            self._body = self._makeStringAttribute(attributes["body"])
+        if "body_html" in attributes:  # pragma no branch
+            self._body_html = self._makeStringAttribute(attributes["body_html"])
+        if "created_at" in attributes:  # pragma no branch
+            self._created_at = self._makeDatetimeAttribute(attributes["created_at"])
+        if "last_edited_at" in attributes:  # pragma no branch
+            self._last_edited_at = self._makeDatetimeAttribute(attributes["last_edited_at"])
+        if "number" in attributes:  # pragma no branch
+            self._number = self._makeIntAttribute(attributes["number"])
+        if "title" in attributes:
+            self._title = self._makeStringAttribute(attributes["title"])
+        if "updated_at" in attributes:  # pragma no branch
+            self._updated_at = self._makeDatetimeAttribute(attributes["updated_at"])
+        if "url" in attributes:  # pragma no branch
+            self._url = self._makeStringAttribute(attributes["url"])

github/DiscussionCommentBase.py

@@ -0,0 +1,117 @@
+############################ Copyrights and license ############################
+#                                                                              #
+# Copyright 2024 Enrico Minack <[email protected]>                      #
+#                                                                              #
+# This file is part of PyGithub.                                               #
+# http://pygithub.readthedocs.io/                                              #
+#                                                                              #
+# PyGithub is free software: you can redistribute it and/or modify it under    #
+# the terms of the GNU Lesser General Public License as published by the Free  #
+# Software Foundation, either version 3 of the License, or (at your option)    #
+# any later version.                                                           #
+#                                                                              #
+# PyGithub is distributed in the hope that it will be useful, but WITHOUT ANY  #
+# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS    #
+# FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more #
+# details.                                                                     #
+#                                                                              #
+# You should have received a copy of the GNU Lesser General Public License     #
+# along with PyGithub. If not, see <http://www.gnu.org/licenses/>.             #
+#                                                                              #
+################################################################################
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+import github.GithubObject
+import github.NamedUser
+from github.GithubObject import Attribute, CompletableGithubObject, NotSet
+
+
+class DiscussionCommentBase(CompletableGithubObject):
+    """
+    This class represents a the shared attributes between RepositoryDiscussionComment and TeamDiscussionComment
+    https://docs.github.com/en/graphql/reference/objects#discussioncomment
+    https://docs.github.com/de/rest/teams/discussion-comments
+    """
+
+    def _initAttributes(self) -> None:
+        self._author: Attribute[github.NamedUser.NamedUser | None] = NotSet
+        self._body: Attribute[str] = NotSet
+        self._body_html: Attribute[str] = NotSet
+        self._created_at: Attribute[datetime] = NotSet
+        self._html_url: Attribute[str] = NotSet
+        self._last_edited_at: Attribute[datetime] = NotSet
+        self._node_id: Attribute[str] = NotSet
+        self._updated_at: Attribute[datetime] = NotSet
+        self._url: Attribute[str] = NotSet
+
+    def __repr__(self) -> str:
+        return self.get__repr__({"node_id": self._node_id.value})
+
+    @property
+    def author(self) -> github.NamedUser.NamedUser | None:
+        self._completeIfNotSet(self._author)
+        return self._author.value
+
+    @property
+    def body(self) -> str:
+        self._completeIfNotSet(self._body)
+        return self._body.value
+
+    @property
+    def body_html(self) -> str:
+        self._completeIfNotSet(self._body_html)
+        return self._body_html.value
+
+    @property
+    def created_at(self) -> datetime:
+        self._completeIfNotSet(self._created_at)
+        return self._created_at.value
+
+    @property
+    def html_url(self) -> str:
+        self._completeIfNotSet(self._html_url)
+        return self._html_url.value
+
+    @property
+    def last_edited_at(self) -> datetime:
+        self._completeIfNotSet(self._last_edited_at)
+        return self._last_edited_at.value
+
+    @property
+    def node_id(self) -> str:
+        self._completeIfNotSet(self._node_id)
+        return self._node_id.value
+
+    @property
+    def updated_at(self) -> datetime:
+        self._completeIfNotSet(self._updated_at)
+        return self._updated_at.value
+
+    @property
+    def url(self) -> str:
+        self._completeIfNotSet(self._url)
+        return self._url.value
+
+    def _useAttributes(self, attributes: dict[str, Any]) -> None:
+        if "author" in attributes:  # pragma no branch
+            self._author = self._makeClassAttribute(github.NamedUser.NamedUser, attributes["author"])
+        if "body" in attributes:  # pragma no branch
+            self._body = self._makeStringAttribute(attributes["body"])
+        if "body_html" in attributes:  # pragma no branch
+            self._body_html = self._makeStringAttribute(attributes["body_html"])
+        if "created_at" in attributes:  # pragma no branch
+            self._created_at = self._makeDatetimeAttribute(attributes["created_at"])
+        if "html_url" in attributes:  # pragma no branch
+            self._html_url = self._makeStringAttribute(attributes["html_url"])
+        if "last_edited_at" in attributes:  # pragma no branch
+            self._last_edited_at = self._makeDatetimeAttribute(attributes["last_edited_at"])
+        if "node_id" in attributes:  # pragma no branch
+            self._node_id = self._makeStringAttribute(attributes["node_id"])
+        if "updated_at" in attributes:  # pragma no branch
+            self._updated_at = self._makeDatetimeAttribute(attributes["updated_at"])
+        if "url" in attributes:  # pragma no branch
+            self._url = self._makeStringAttribute(attributes["url"])

github/GithubIntegration.py

@@ -255,8 +255,10 @@ def get_installation(self, owner: str, repo: str) -> Installation:
         """
         Deprecated by get_repo_installation.
 
-        :calls: `GET /repos/{owner}/{repo}/installation
-        <https://docs.github.com/en/rest/reference/apps#get-a-repository-installation-for-the-authenticated-app>`
+        :calls:`GET /repos/{owner}/{repo}/installation <https://docs.github.com/en/rest/reference/apps#get-a-repository-
+        installation-for-the-authenticated-app>`
+        :calls:`GET /repos/{owner}/{repo}/installation <https://docs.github.com/en/rest/reference/apps#get-a-repository-
+        installation-for-the-authenticated-app>`
 
         """
         owner = urllib.parse.quote(owner)

github/GithubObject.py

@@ -48,11 +48,12 @@
 ################################################################################
 
 import email.utils
+import re
 import typing
 from datetime import datetime, timezone
 from decimal import Decimal
 from operator import itemgetter
-from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple, Type, Union
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple, Type, Union, overload
 
 from typing_extensions import Protocol, TypeGuard
 
@@ -139,6 +140,62 @@ def is_optional_list(v: Any, type: Union[Type, Tuple[Type, ...]]) -> bool:
     return isinstance(v, _NotSetType) or isinstance(v, list) and all(isinstance(element, type) for element in v)
 
 
+camel_to_snake_case_regexp = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+@overload
+def as_rest_api_attributes(graphql_attributes: Dict[str, Any]) -> Dict[str, Any]:
+    ...
+
+
+@overload
+def as_rest_api_attributes(graphql_attributes: None) -> None:
+    ...
+
+
+def as_rest_api_attributes(graphql_attributes: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """
+    Converts attributes from GraphQL schema to REST API schema.
+
+    The GraphQL API uses lower camel case (e.g. createdAt), whereas REST API uses snake case (created_at). Initializing
+    REST API GithubObjects from GraphQL API attributes requires transformation provided by this method.
+
+    Further renames GraphQL attributes to REST API attributes where the case conversion is not sufficient. For example,
+    GraphQL attribute 'id' is equivalent to REST API attribute 'node_id'.
+
+    """
+    if graphql_attributes is None:
+        return None
+
+    attribute_translation = {
+        "id": "node_id",
+        "databaseId": "id",  # must be after 'id': 'node_id'!
+        "url": "html_url",
+    }
+
+    def translate(attr: str) -> str:
+        def un_capitalize(match: re.Match) -> str:
+            return match.group(1) + match.group(2).lower()
+
+        attr = attribute_translation.get(attr, attr)
+        attr = re.sub(r"([A-Z])([A-Z]+)", un_capitalize, attr)
+        attr = camel_to_snake_case_regexp.sub("_", attr)
+        attr = attr.lower()
+
+        return attr
+
+    return {
+        translate(k): as_rest_api_attributes(v)
+        if isinstance(v, dict)
+        else (as_rest_api_attributes_list(v) if isinstance(v, list) else v)
+        for k, v in graphql_attributes.items()
+    }
+
+
+def as_rest_api_attributes_list(graphql_attributes: List[Optional[Dict[str, Any]]]) -> List[Optional[Dict[str, Any]]]:
+    return [as_rest_api_attributes(v) if isinstance(v, dict) else v for v in graphql_attributes]
+
+
 class _ValuedAttribute(Attribute[T]):
     def __init__(self, value: T):
         self._value = value
@@ -172,6 +229,14 @@ class GithubObject:
     CHECK_AFTER_INIT_FLAG = False
     _url: Attribute[str]
 
+    @classmethod
+    def is_rest(cls) -> bool:
+        return not cls.is_graphql()
+
+    @classmethod
+    def is_graphql(cls) -> bool:
+        return False
+
     @classmethod
     def setCheckAfterInitFlag(cls, flag: bool) -> None:
         cls.CHECK_AFTER_INIT_FLAG = flag
@@ -397,6 +462,12 @@ def _completeIfNeeded(self) -> None:
         raise NotImplementedError("BUG: Not Implemented _completeIfNeeded")
 
 
+class GraphQlObject:
+    @classmethod
+    def is_graphql(cls) -> bool:
+        return True
+
+
 class NonCompletableGithubObject(GithubObject):
     def _completeIfNeeded(self) -> None:
         pass

github/MainClass.py

@@ -143,6 +143,7 @@
     from github.Project import Project
     from github.ProjectColumn import ProjectColumn
     from github.Repository import Repository
+    from github.RepositoryDiscussion import RepositoryDiscussion
     from github.Topic import Topic
 
 TGithubObject = TypeVar("TGithubObject", bound=GithubObject)
@@ -326,8 +327,7 @@ def get_rate_limit(self) -> RateLimit:
         """
         Rate limit status for different resources (core/search/graphql).
 
-        :calls: `GET /rate_limit
-        <https://docs.github.com/en/rest/reference/rate-limit>`_
+        :calls:`GET /rate_limit <https://docs.github.com/en/rest/reference/rate-limit>`_
 
         """
         headers, data = self.__requester.requestJsonAndCheck("GET", "/rate_limit")
@@ -468,6 +468,11 @@ def get_repos(
             url_parameters,
         )
 
+    def get_repository_discussion(self, node_id: str, discussion_graphql_schema: str) -> RepositoryDiscussion:
+        return self.__requester.graphql_node_class(
+            node_id, discussion_graphql_schema, github.RepositoryDiscussion.RepositoryDiscussion, "Discussion"
+        )
+
     def get_project(self, id: int) -> Project:
         """
         :calls: `GET /projects/{project_id} <https://docs.github.com/en/rest/reference/projects#get-a-project>`_