Make requester a public attribute (#3056)

minrk · EnricoMi · web-flow · commit c44ec523b183 · 2024-10-09T15:17:08.000Z
There will always be new APIs not yet supported by PyGitHub (e.g. #2718). This adds an escape hatch for users to send requests directly without having to start from scratch or use private APIs while waiting for PyGitHub to add support. Changes: - private `object._requester` `.__requester` is now available via public `.requester` attribute on MainClass, GitHubObject, etc. - add Requester APIs to docs as public methods, indicating status as stable public APIs Fixes #2071 which received only positive feedback, but was closed for inactivity. --------- Co-authored-by: Enrico Minack <github@enrico.minack.dev>
diff --git a/doc/utilities.rst b/doc/utilities.rst
@@ -39,3 +39,12 @@ Input classes
 .. autoclass:: github.InputFileContent.InputFileContent
 .. autoclass:: github.InputGitAuthor.InputGitAuthor
 .. autoclass:: github.InputGitTreeElement.InputGitTreeElement
+
+Raw Requests
+------------
+
+If you need to make requests to APIs not yet supported by PyGithub,
+you can use the :class:`.Requester` object directly, available as :attr:`object.requester` on most PyGithub objects.
+
+.. autoclass:: github.Requester.Requester
+    :members:
diff --git a/github/GithubIntegration.py b/github/GithubIntegration.py
@@ -182,6 +182,16 @@ def get_github_for_installation(
         auth = self.auth.get_installation_auth(installation_id, token_permissions, self.__requester)
         return github.Github(**self.__requester.withAuth(auth).kwargs)
 
+    @property
+    def requester(self) -> Requester:
+        """
+        Return my Requester object.
+
+        For example, to make requests to API endpoints not yet supported by PyGitHub.
+
+        """
+        return self.__requester
+
     def _get_headers(self) -> dict[str, str]:
         """
         Get headers for the requests.
diff --git a/github/GithubObject.py b/github/GithubObject.py
@@ -199,6 +199,16 @@ def _storeAndUseAttributes(self, headers: Dict[str, Union[str, int]], attributes
         self._rawData = attributes
         self._useAttributes(attributes)
 
+    @property
+    def requester(self) -> "Requester":
+        """
+        Return my Requester object.
+
+        For example, to make requests to API endpoints not yet supported by PyGitHub.
+
+        """
+        return self._requester
+
     @property
     def raw_data(self) -> Dict[str, Any]:
         """
diff --git a/github/Installation.py b/github/Installation.py
@@ -104,6 +104,16 @@ def __repr__(self) -> str:
     def get_github_for_installation(self) -> Github:
         return github.Github(**self._requester.kwargs)
 
+    @property
+    def requester(self) -> Requester:
+        """
+        Return my Requester object.
+
+        For example, to make requests to API endpoints not yet supported by PyGitHub.
+
+        """
+        return self._requester
+
     @property
     def id(self) -> int:
         return self._id.value
diff --git a/github/MainClass.py b/github/MainClass.py
@@ -273,6 +273,16 @@ def __enter__(self) -> Github:
     def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
         self.close()
 
+    @property
+    def requester(self) -> Requester:
+        """
+        Return my Requester object.
+
+        For example, to make requests to API endpoints not yet supported by PyGitHub.
+
+        """
+        return self.__requester
+
     @property
     def FIX_REPO_GET_GIT_REF(self) -> bool:
         return self.__requester.FIX_REPO_GET_GIT_REF
diff --git a/github/Requester.py b/github/Requester.py
@@ -547,6 +547,15 @@ def requestJsonAndCheck(
         headers: Optional[Dict[str, str]] = None,
         input: Optional[Any] = None,
     ) -> Tuple[Dict[str, Any], Any]:
+        """
+        Send a request with JSON body.
+
+        :param input: request body, serialized to JSON if specified
+
+        :return: ``(headers: dict, JSON Response: Any)``
+        :raises: :class:`GithubException` for error status codes
+
+        """
         return self.__check(*self.requestJson(verb, url, parameters, headers, input, self.__customConnection(url)))
 
     def requestMultipartAndCheck(
@@ -557,6 +566,15 @@ def requestMultipartAndCheck(
         headers: Optional[Dict[str, Any]] = None,
         input: Optional[Dict[str, str]] = None,
     ) -> Tuple[Dict[str, Any], Optional[Dict[str, Any]]]:
+        """
+        Send a request with multi-part-encoded body.
+
+        :param input: request body, will be multi-part encoded if specified
+
+        :return: ``(headers: dict, JSON Response: Any)``
+        :raises: :class:`GithubException` for error status codes
+
+        """
         return self.__check(*self.requestMultipart(verb, url, parameters, headers, input, self.__customConnection(url)))
 
     def requestBlobAndCheck(
@@ -568,6 +586,15 @@ def requestBlobAndCheck(
         input: Optional[str] = None,
         cnx: Optional[Union[HTTPRequestsConnectionClass, HTTPSRequestsConnectionClass]] = None,
     ) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+        """
+        Send a request with a file for the body.
+
+        :param input: path to a file to use for the request body
+
+        :return: ``(headers: dict, JSON Response: Any)``
+        :raises: :class:`GithubException` for error status codes
+
+        """
         return self.__check(*self.requestBlob(verb, url, parameters, headers, input, self.__customConnection(url)))
 
     def graphql_query(self, query: str, variables: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
@@ -709,6 +736,14 @@ def requestJson(
         input: Optional[Any] = None,
         cnx: Optional[Union[HTTPRequestsConnectionClass, HTTPSRequestsConnectionClass]] = None,
     ) -> Tuple[int, Dict[str, Any], str]:
+        """
+        Send a request with JSON input.
+
+        :param input: request body, will be serialized as JSON
+        :returns:``(status, headers, body)``
+
+        """
+
         def encode(input: Any) -> Tuple[str, str]:
             return "application/json", json.dumps(input)
 
@@ -723,6 +758,14 @@ def requestMultipart(
         input: Optional[Dict[str, str]] = None,
         cnx: Optional[Union[HTTPRequestsConnectionClass, HTTPSRequestsConnectionClass]] = None,
     ) -> Tuple[int, Dict[str, Any], str]:
+        """
+        Send a request with multi-part encoding.
+
+        :param input: request body, will be serialized as multipart form data
+        :returns:``(status, headers, body)``
+
+        """
+
         def encode(input: Dict[str, Any]) -> Tuple[str, str]:
             boundary = "----------------------------3c3ba8b523b2"
             eol = "\r\n"
@@ -747,6 +790,13 @@ def requestBlob(
         input: Optional[str] = None,
         cnx: Optional[Union[HTTPRequestsConnectionClass, HTTPSRequestsConnectionClass]] = None,
     ) -> Tuple[int, Dict[str, Any], str]:
+        """
+        Send a request with a file as request body.
+
+        :param input: path to a local file to use for request body
+        :returns:``(status, headers, body)``
+
+        """
         if headers is None:
             headers = {}
 
@@ -772,6 +822,15 @@ def requestMemoryBlobAndCheck(
         file_like: BinaryIO,
         cnx: Optional[Union[HTTPRequestsConnectionClass, HTTPSRequestsConnectionClass]] = None,
     ) -> Tuple[Dict[str, Any], Any]:
+        """
+        Send a request with a binary file-like for the body.
+
+        :param file_like: file-like object to use for the request body
+        :return: ``(headers: dict, JSON Response: Any)``
+        :raises: :class:`GithubException` for error status codes
+
+        """
+
         # The expected signature of encode means that the argument is ignored.
         def encode(_: Any) -> Tuple[str, Any]:
             return headers["Content-Type"], file_like
diff --git a/tests/GithubIntegration.py b/tests/GithubIntegration.py
@@ -280,3 +280,6 @@ def testGetApp(self):
 
         self.assertEqual(app.name, "PyGithubTest")
         self.assertEqual(app.url, "/apps/pygithubtest")
+
+        assert github_integration.requester is github_integration.__requester
+        assert app.requester is app._requester
diff --git a/tests/Github_.py b/tests/Github_.py
@@ -628,3 +628,6 @@ def testGetEvents(self):
             lambda e: e.type,
             ["PushEvent", "WatchEvent", "PushEvent", "CommitCommentEvent"],
         )
+
+    def testRequester(self):
+        assert self.g.requester is self.g.__requester
diff --git a/tests/Installation.py b/tests/Installation.py
@@ -95,3 +95,8 @@ def testGetGithubForInstallation(self):
 
             repo = g.get_repo("PyGithub/PyGithub")
             self.assertEqual(repo.full_name, "PyGithub/PyGithub")
+
+    def testRequester(self):
+        self.assertEqual(len(self.installations), 1)
+        installation = self.installations[0]
+        assert installation.requester is installation._requester
diff --git a/tests/Repository.py b/tests/Repository.py
@@ -2081,3 +2081,7 @@ def testChangeAutomateFixWhenNoVulnerabilityAlert(self):
     def testGetVulnerabilityAlertWhenTurnedOff(self):
         lazy_repo = self.getEagerRepository()
         self.assertFalse(lazy_repo.get_vulnerability_alert())
+
+    def testRequester(self):
+        lazy_repo = self.getLazyRepository()
+        assert lazy_repo.requester is lazy_repo._requester

Original file line number	Diff line number	Diff line change
`@@ -628,3 +628,6 @@ def testGetEvents(self):`
`628`	`628`	`lambda e: e.type,`
`629`	`629`	`["PushEvent", "WatchEvent", "PushEvent", "CommitCommentEvent"],`
`630`	`630`	`)`
	`631`	`+`
	`632`	`+ def testRequester(self):`
	`633`	`+ assert self.g.requester is self.g.__requester`