github-rest-api 0.40.0__py3-none-any.whl → 0.41.0__py3-none-any.whl

github_rest_api/__init__.py

@@ -1,5 +1,11 @@
 """GitHub REST APIs."""
 
-from .github import Organization, Repository, RepositoryType, User
+from .github import (
+    Organization,
+    Repository,
+    RepositoryType,
+    SecretVisibility,
+    User,
+)
 
-__all__ = ["Organization", "Repository", "RepositoryType", "User"]
+__all__ = ["Organization", "Repository", "RepositoryType", "SecretVisibility", "User"]

github_rest_api/github.py

@@ -1,10 +1,25 @@
 """Simple wrapper of GitHub REST APIs."""
 
 from abc import ABCMeta, abstractmethod
+from base64 import b64encode
+from collections.abc import Sequence
 from enum import StrEnum
 from typing import Any, Callable
 from pathlib import Path
 import requests
+from nacl import encoding, public
+
+URL_API = "https://api.github.com"
+
+
+def _encrypt_secret(public_key: str, value: str) -> str:
+    """Encrypt a secret value using a LibSodium sealed box.
+    :param public_key: The base64-encoded public key to encrypt against.
+    :param value: The plaintext secret value to encrypt.
+    """
+    pkey = public.PublicKey(public_key.encode(), encoding.Base64Encoder)
+    encrypted = public.SealedBox(pkey).encrypt(value.encode())
+    return b64encode(encrypted).decode()
 
 
 def build_http_headers(token: str) -> dict[str, str]:
@@ -36,6 +51,12 @@ class GitHub:
     def _get(
         self, url: str, raise_for_status: bool = True, **kwargs
     ) -> requests.Response:
+        """Send a GET request to a GitHub REST API endpoint.
+        :param url: The endpoint URL to request.
+        :param raise_for_status: Whether to raise on a non-2xx response.
+        :param kwargs: Additional keyword arguments (e.g. `params`) forwarded
+            to `requests.get`.
+        """
         resp = requests.get(
             url=url,
             headers=self._headers,
@@ -49,6 +70,13 @@ class GitHub:
     def _post(
         self, url: str, headers=None, raise_for_status: bool = True, **kwargs
     ) -> requests.Response:
+        """Send a POST request to a GitHub REST API endpoint.
+        :param url: The endpoint URL to request.
+        :param headers: Request headers; defaults to the standard auth headers.
+        :param raise_for_status: Whether to raise on a non-2xx response.
+        :param kwargs: Additional keyword arguments (e.g. `json`) forwarded
+            to `requests.post`.
+        """
         if headers is None:
             headers = self._headers
         resp = requests.post(
@@ -67,17 +95,32 @@ class GitHub:
             resp.raise_for_status()
         return resp
 
-    def _put(self, url, raise_for_status: bool = True) -> requests.Response:
+    def _put(
+        self, url: str, raise_for_status: bool = True, **kwargs
+    ) -> requests.Response:
+        """Send a PUT request to a GitHub REST API endpoint.
+        :param url: The endpoint URL to request.
+        :param raise_for_status: Whether to raise on a non-2xx response.
+        :param kwargs: Additional keyword arguments (e.g. `json`) forwarded
+            to `requests.put`.
+        """
         resp = requests.put(
             url=url,
             headers=self._headers,
             timeout=10,
+            **kwargs,
         )
         if raise_for_status:
             resp.raise_for_status()
         return resp
 
     def _patch(self, url, raise_for_status: bool = True, **kwargs) -> requests.Response:
+        """Send a PATCH request to a GitHub REST API endpoint.
+        :param url: The endpoint URL to request.
+        :param raise_for_status: Whether to raise on a non-2xx response.
+        :param kwargs: Additional keyword arguments (e.g. `json`) forwarded
+            to `requests.patch`.
+        """
         resp = requests.patch(
             url=url,
             headers=self._headers,
@@ -118,8 +161,7 @@ class Repository(GitHub):
         """
         super().__init__(token)
         self._repo = repo
-        self._url = "https://api.github.com/repos"
-        self._url_repo = f"{self._url}/{repo}"
+        self._url_repo = f"{URL_API}/repos/{repo}"
         self._url_tags = f"{self._url_repo}/tags"
         self._url_transfer = f"{self._url_repo}/transfer"
         self._url_pull = f"{self._url_repo}/pulls"
@@ -127,6 +169,7 @@ class Repository(GitHub):
         self._url_refs = f"{self._url_repo}/git/refs"
         self._url_issues = f"{self._url_repo}/issues"
         self._url_releases = f"{self._url_repo}/releases"
+        self._url_secrets = f"{self._url_repo}/actions/secrets"
 
     def get_releases(self, n: int = 0) -> list[dict[str, Any]]:
         """List releases in this repository."""
@@ -157,8 +200,6 @@ class Repository(GitHub):
         For more details, please refer to
         https://docs.github.com/en/rest/releases/releases#create-a-release.
         """
-        if not isinstance(json, dict):
-            raise ValueError("A dict value is required for `json`.")
         return self._post(
             url=self._url_releases,
             json=json,
@@ -171,7 +212,9 @@ class Repository(GitHub):
             path = Path(path)
         with path.open(mode="rb") as fin:
             return self._post(
-                url=f"{self._url_releases.replace('api', 'uploads', 1)}/{release}/assets",
+                url=f"{self._url_releases.replace('api', 'uploads', 1)}/{
+                    release
+                }/assets",
                 params={
                     "name": name,
                 },
@@ -193,8 +236,6 @@ class Repository(GitHub):
         about the pull request to be created.
         It's passed to the json parameter of requests.post.
         """
-        if not isinstance(json, dict):
-            raise ValueError("A dict value is required for `json`.")
         if not ("head" in json and "base" in json):
             raise ValueError("The data dict must contains keys head and base!")
         # return an existing PR
@@ -217,8 +258,6 @@ class Repository(GitHub):
         """Merge a pull request in this repository.
         :param pr_number: The number of the pull quest to be merged.
         """
-        if not isinstance(pr_number, int):
-            raise ValueError("An integer value is required for `pr_number`.")
         return self._put(
             url=f"{self._url_pull}/{pr_number}/merge",
         ).json()
@@ -228,10 +267,6 @@ class Repository(GitHub):
         :param update: The branch to update.
         :param upstream: The upstream branch.
         """
-        if not isinstance(update, str):
-            raise ValueError("A string value is required for `update`.")
-        if not isinstance(upstream, str):
-            raise ValueError("A string value is required for `upstream`.")
         pr = self.create_pull_request(
             {
                 "base": update,
@@ -250,8 +285,6 @@ class Repository(GitHub):
 
         :param pr_number: The number of the pull request.
         """
-        if not isinstance(pr_number, int):
-            raise ValueError("An integer value is required for `pr_number`.")
         return self._extract_all(url=f"{self._url_pull}/{pr_number}/files", n=n)
 
     def get_branches(self, n: int = 0) -> list[dict[str, Any]]:
@@ -272,8 +305,6 @@ class Repository(GitHub):
         """Delete a reference from this repository.
         :param ref: The reference to delete from this repository.
         """
-        if not isinstance(ref, str):
-            raise ValueError("A string value is required for `ref`.")
         return self._delete(
             url=f"{self._url_refs}/{ref}",
         )
@@ -284,6 +315,36 @@ class Repository(GitHub):
         """
         return self.delete_ref(ref=f"heads/{branch}")
 
+    def delete_secret(self, name: str) -> requests.Response:
+        """Delete a secret from this repository.
+        :param name: The name of the secret to delete.
+        """
+        return self._delete(
+            url=f"{self._url_secrets}/{name}",
+        )
+
+    def get_secret_public_key(self) -> dict[str, Any]:
+        """Get the public key for encrypting secrets in this repository."""
+        return self._get(url=f"{self._url_secrets}/public-key").json()
+
+    def create_or_update_secret(
+        self, name: str, value: str, public_key: dict[str, Any]
+    ) -> requests.Response:
+        """Create or update a secret in this repository.
+        :param name: The name of the secret.
+        :param value: The plaintext value of the secret.
+        :param public_key: A public key (as returned by `get_secret_public_key`)
+            to encrypt the secret with. Fetch it once and reuse it to avoid a
+            redundant request when creating or updating multiple secrets.
+        """
+        return self._put(
+            url=f"{self._url_secrets}/{name}",
+            json={
+                "encrypted_value": _encrypt_secret(public_key["key"], value),
+                "key_id": public_key["key_id"],
+            },
+        )
+
     def pr_has_change(
         self, pr_number: int, pred: Callable[[str], bool] = lambda _: True
     ) -> bool:
@@ -313,10 +374,6 @@ class Repository(GitHub):
         :param issue_number: The number of the issue.
         :param body: Body text of the new comment.
         """
-        if not isinstance(issue_number, int):
-            raise ValueError("An integer value is required for `issue_number`.")
-        if not isinstance(body, str):
-            raise ValueError("A string message is required for `body`.")
         return self._post(
             url=f"{self._url_issues}/{issue_number}/comments",
             json={"body": body},
@@ -344,6 +401,12 @@ class RepositoryType(StrEnum):
     PRIVATE = "private"
 
 
+class SecretVisibility(StrEnum):
+    ALL = "all"
+    PRIVATE = "private"
+    SELECTED = "selected"
+
+
 class Owner(GitHub, metaclass=ABCMeta):
     """An abstract owner class representing an organization or user."""
 
@@ -354,6 +417,7 @@ class Owner(GitHub, metaclass=ABCMeta):
         """
         super().__init__(token)
         self._owner = owner
+        self._url_owner = ""
         self._url_repos = ""
         self._url_create_repo = ""
 
@@ -376,6 +440,14 @@ class Owner(GitHub, metaclass=ABCMeta):
     def create_repository(
         self, name: str, description: str = "", private: bool = True, **kwargs
     ) -> dict[str, Any]:
+        """Create a repository for this owner.
+        :param name: The name of the repository.
+        :param description: A short description of the repository.
+        :param private: Whether the repository is private.
+        :param kwargs: Additional keyword arguments forwarded to `_post`
+            (e.g. `params` or `raise_for_status`). Note `json` is already set
+            from the other parameters and must not be passed here.
+        """
         data = {
             "name": name,
             "description": description,
@@ -400,8 +472,9 @@ class User(Owner):
         self._set_urls()
 
     def _set_urls(self) -> None:
-        self._url_repos = f"https://api.github.com/users/{self._owner}/repos"
-        self._url_create_repo = "https://api.github.com/user/repos"
+        self._url_owner = f"{URL_API}/users/{self._owner}"
+        self._url_repos = f"{self._url_owner}/repos"
+        self._url_create_repo = f"{URL_API}/user/repos"
 
 
 class Organization(Owner):
@@ -416,5 +489,54 @@ class Organization(Owner):
         self._set_urls()
 
     def _set_urls(self) -> None:
-        self._url_repos = f"https://api.github.com/orgs/{self._owner}/repos"
+        self._url_owner = f"{URL_API}/orgs/{self._owner}"
+        self._url_repos = f"{self._url_owner}/repos"
         self._url_create_repo = self._url_repos
+        self._url_secrets = f"{self._url_owner}/actions/secrets"
+
+    def delete_secret(self, name: str) -> requests.Response:
+        """Delete an organization secret.
+        :param name: The name of the secret to delete.
+        """
+        return self._delete(
+            url=f"{self._url_secrets}/{name}",
+        )
+
+    def get_secret_public_key(self) -> dict[str, Any]:
+        """Get the public key for encrypting secrets in this organization."""
+        return self._get(url=f"{self._url_secrets}/public-key").json()
+
+    def create_or_update_secret(
+        self,
+        name: str,
+        value: str,
+        public_key: dict[str, Any],
+        visibility: SecretVisibility = SecretVisibility.ALL,
+        selected_repository_ids: Sequence[int] = (),
+    ) -> requests.Response:
+        """Create or update an organization secret.
+        :param name: The name of the secret.
+        :param value: The plaintext value of the secret.
+        :param public_key: A public key (as returned by `get_secret_public_key`)
+            to encrypt the secret with. Fetch it once and reuse it to avoid a
+            redundant request when creating or updating multiple secrets.
+        :param visibility: Which repositories can access the secret
+            (all, private, or selected).
+        :param selected_repository_ids: Repository IDs that can access the secret
+            when visibility is `selected`.
+        """
+        if selected_repository_ids and visibility != SecretVisibility.SELECTED:
+            raise ValueError(
+                "`selected_repository_ids` can only be provided when `visibility` is 'selected'."
+            )
+        json: dict[str, Any] = {
+            "encrypted_value": _encrypt_secret(public_key["key"], value),
+            "key_id": public_key["key_id"],
+            "visibility": visibility,
+        }
+        if selected_repository_ids:
+            json["selected_repository_ids"] = list(selected_repository_ids)
+        return self._put(
+            url=f"{self._url_secrets}/{name}",
+            json=json,
+        )

{github_rest_api-0.40.0.dist-info → github_rest_api-0.41.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-rest-api
-Version: 0.40.0
+Version: 0.41.0
 Summary: Simple wrapper of GitHub REST APIs.
 Author-email: Ben Du <longendu@yahoo.com>
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -10,6 +10,7 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: <4,>=3.12
 Requires-Dist: dulwich>=0.25.1
 Requires-Dist: psutil>=5.9.4
+Requires-Dist: pynacl>=1.5
 Requires-Dist: pyyaml>=6
 Requires-Dist: requests>=2.28.2
 Requires-Dist: tenacity>=9.1.4

{github_rest_api-0.40.0.dist-info → github_rest_api-0.41.0.dist-info}/RECORD

@@ -1,5 +1,5 @@
-github_rest_api/__init__.py,sha256=P-BmW8wD0Uhk0kt3xIBTfWiFY2oQj17zCIQ02pAqb6c,160
-github_rest_api/github.py,sha256=FK1F5lXKtBgL_nizm3xuxQ2i5eRuycbX2bfWePuF1PM,14575
+github_rest_api/__init__.py,sha256=Vx8CfSReDGbrQmTDSgCJ2Z9mjb2amk-t6SUmidFEbVs,223
+github_rest_api/github.py,sha256=qMTTY0iVBcYNxxIvwcebsbx792jU1VXgWk4Wg8xfuNY,19456
 github_rest_api/utils.py,sha256=rs5ZQlHGbPoKvf4f52VeG4FwqwOFePaEPYPhWgfSGWA,2697
 github_rest_api/scripts/__init__.py,sha256=NkHTngnnWXPc0JmO5mqVKjDf4JPofuwWjDW1SU3aE7Y,36
 github_rest_api/scripts/utils.py,sha256=xWswlfwUZI9ocuwQprhAHP1PRt8_tbs6UxyvQTtoVMY,4587
@@ -22,7 +22,7 @@ github_rest_api/scripts/github/workflows/create_pr_to_main.yaml,sha256=mgHPlewkC
 github_rest_api/scripts/github/workflows/remove_branch.yaml,sha256=KDpB76ovrhuRdP0HN5j6Th9gjIQWSDdh8b4b4yAgtoI,544
 github_rest_api/scripts/github/workflows/python/lint.yaml,sha256=toP2oUdVIKyu_n20Dr14k5cJYxN8rPksfbX4sfflXxc,699
 github_rest_api/scripts/github/workflows/python/test.yaml,sha256=86MljYEWX1E9kJYmhMCLwu46WNEWvoyO9PwqeRew540,887
-github_rest_api-0.40.0.dist-info/METADATA,sha256=ZDhv1ZLUjzwW_eRwYdYhSQRGZahYi387LHh0E0UBKaw,825
-github_rest_api-0.40.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-github_rest_api-0.40.0.dist-info/entry_points.txt,sha256=eXMEdbMEpuE1nsTfUiKSILgS4awe09NwKn0N2_fZ9H0,567
-github_rest_api-0.40.0.dist-info/RECORD,,
+github_rest_api-0.41.0.dist-info/METADATA,sha256=uJFonjOAa-XZUqgSJ-NyWLZ0wuXThi2LdCgaM-Yj2mA,852
+github_rest_api-0.41.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+github_rest_api-0.41.0.dist-info/entry_points.txt,sha256=eXMEdbMEpuE1nsTfUiKSILgS4awe09NwKn0N2_fZ9H0,567
+github_rest_api-0.41.0.dist-info/RECORD,,