github-bot-api 0.7.0__py3-none-any.whl → 0.7.1__py3-none-any.whl

github_bot_api/__init__.py

@@ -1,5 +1,5 @@
 __author__ = "Niklas Rosenstein <nrosenstein@palantir.com>"
-__version__ = "0.7.0"
+__version__ = "0.7.1"
 
 from .app import GithubApp
 from .event import Event, accept_event

github_bot_api/app.py

@@ -6,8 +6,11 @@ import dataclasses
 import logging
 import sys
 import threading
+import time
 import typing as t
+from urllib.parse import parse_qs, urlencode
 
+import deprecated
 import requests
 import urllib3
 
@@ -75,9 +78,22 @@ class GithubApp:
     app_id: int
     """GitHub Application ID."""
 
-    private_key: str
+    private_key: str = dataclasses.field(repr=False)
     """RSA private key to sign the JWT with."""
 
+    client_id: t.Optional[str] = None
+    """The GitHub App's OAuth client ID. This is required for OAuth2 authorization URL generation. Can be omitted
+    if the app does not use OAuth2."""
+
+    client_secret: t.Optional[str] = dataclasses.field(default=None, repr=False)
+    """The GitHub App's OAuth client secret. This is required for OAuth2 authorization URL generation. Can be omitted
+    if the app does not use OAuth2. Note that this must be specified if #client_id is specified."""
+
+    redirect_uri: t.Optional[str] = None
+    """The GitHub App's OAuth redirect URI. This is required for OAuth2 authorization URL generation. Can be omitted
+    if the app does not use OAuth2. This field is optional, but required for the web authorization flow with
+    #oauth2_web_application_flow_url()."""
+
     v3_api_url: str = PUBLIC_GITHUB_V3_API_URL
     """GitHub API base URL. Defaults to the public GitHub API."""
 
@@ -86,6 +102,13 @@ class GithubApp:
         self._lock = threading.Lock()
         self._installation_tokens: t.Dict[int, InstallationTokenSupplier] = {}
 
+        if self.client_id is not None:
+            if self.client_secret is None:
+                raise ValueError("client_secret must be specified if client_id is specified.")
+        if self.redirect_uri is not None:
+            if self.client_id is None:
+                raise ValueError("redirect_uri does not make sense without client_id.")
+
     def _get_base_github_client_settings(self) -> GithubClientSettings:
         return GithubClientSettings(self.v3_api_url, self.get_user_agent())
 
@@ -140,7 +163,11 @@ class GithubApp:
             headers={"Authorization": auth_header, "User-Agent": user_agent},
         ).json()
 
+    @deprecated.deprecated(reason="Use .installation_token_supplier() instead.", version="0.8.0")
     def get_installation_token_supplier(self, installation_id: int) -> InstallationTokenSupplier:
+        return self.installation_token_supplier(installation_id)
+
+    def installation_token_supplier(self, installation_id: int) -> InstallationTokenSupplier:
         """
         Create an #InstallationTokenSupplier for your GitHub application to act within the scope of the given
         *installation_id*.
@@ -186,3 +213,168 @@ class GithubApp:
         token = self.installation_token(installation_id).value
         settings = self._get_base_github_client_settings().update(settings)
         return settings.make_client(login_or_token=token)
+
+    def oauth2_web_application_flow_url(self, state: t.Optional[str] = None) -> str:
+        """
+        Returns the URL for a user to begin the OAuth2 web authorization flow.
+
+        Preconditions:
+        - You must have provided a `client_id` when constructing the #GithubApp instance.
+
+        Documentation: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-web-application-flow-to-generate-a-user-access-token
+        """
+
+        if self.client_id is None:
+            raise ValueError("client_id must be specified to generate OAuth2 authorization URL.")
+        if self.client_secret is None:
+            raise ValueError("client_secret must be specified to generate OAuth2 authorization URL.")
+        if not self.redirect_uri:
+            raise ValueError("redirect_uri must be specified to generate OAuth2 authorization URL.")
+
+        params = {
+            "client_id": self.client_id,
+            "redirect_uri": self.redirect_uri,
+        }
+        if state is not None:
+            params["state"] = state
+
+        url = self.v3_api_url.replace("api.", "").replace("/api/v3", "").rstrip("/")
+        return f"{url}/login/oauth/authorize?" + urlencode(params)
+
+    def oauth2_device_flow(self) -> "OAuth2DeviceCodeFlow":
+        """
+        Makes a request to GitHub to request a device code for the OAuth2 device flow.
+
+        Prerequisites:
+
+        - "Enable Device Flow" must be checked in your GitHub app's settings.
+        - You must have provided a `client_id` when constructing the #GithubApp instance.
+
+        Documentation: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-device-flow-to-generate-a-user-access-token
+        """
+
+        params = {"client_id": self.client_id}
+        url = self.v3_api_url.replace("api.", "").replace("/api/v3", "").rstrip("/")
+        response = requests.post(f"{url}/login/device/code", params=params)
+        response.raise_for_status()
+        payload = {k: v[0] for k, v in parse_qs(response.text).items()}
+        return OAuth2DeviceCodeFlow(
+            device_code=payload["device_code"],
+            user_code=payload["user_code"],
+            verification_uri=payload["verification_uri"],
+            expires_in=int(payload["expires_in"]),
+            interval=int(payload["interval"]),
+            app=self,
+        )
+
+    def oauth2_access_token(
+        self, *, code: t.Optional[str] = None, device_code: t.Optional[str] = None
+    ) -> t.Optional["OAuth2TokenInfo"]:
+        """
+        Makes a request to GitHub to exchange an OAuth2 code for an access token.
+
+        Important: You must provide the correct `code` or `device_code` parameter, but not both.
+
+        Documentation: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#generating-a-user-access-token-when-a-user-installs-your-app
+
+        Returns None if the token is not yet available (in the case of the device flow). Otherwise, returns a
+        #TokenInfo object. If an error occurs, an #AccessTokenError is raised.
+        """
+
+        params = {"client_id": self.client_id, "client_secret": self.client_secret}
+        if code is not None:
+            params["code"] = code
+        elif device_code is not None:
+            params["device_code"] = device_code
+            params["grant_type"] = "urn:ietf:params:oauth:grant-type:device_code"
+        else:
+            raise ValueError("You must provide either a code or a device_code.")
+
+        url = self.v3_api_url.replace("api.", "").replace("/api/v3", "").rstrip("/")
+        response = requests.post(f"{url}/login/oauth/access_token", params=params)
+        payload = {k: v[0] for k, v in parse_qs(response.text).items()}
+
+        if (error := payload.get("error")) == "authorization_pending":
+            return None
+        elif error is not None:
+            return OAuth2TokenInfo(
+                access_token=payload["access_token"],
+                expires_in=int(payload["expires_in"]),
+                scope=payload.get("scope"),
+                token_type=payload["token_type"],
+                refresh_token=payload.get("refresh_token"),
+                refresh_token_expires_in=int(payload["refresh_token_expires_in"])
+                if "refresh_token_expires_in" in payload
+                else None,
+            )
+        else:
+            raise AccessTokenError(error)  # type: ignore[arg-type]
+
+
+@dataclasses.dataclass
+class OAuth2DeviceCodeFlow:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    expires_in: int
+    interval: int
+
+    # If you want to use this object to poll for the token, you need the GitHub App.
+    app: t.Optional[GithubApp] = None
+
+    def wait_for_token(
+        self, aborted: t.Optional[threading.Event] = None, max_duration: t.Optional[float] = None
+    ) -> "OAuth2TokenInfo":
+        """
+        Polls GitHub for the access token until it is available.
+
+        If you pass in a threading.Event object, it will be used to abort the polling when the
+        event is set. If *max_duration* is specified, the polling will stop after that many seconds and
+        raise a #TimeoutError if the token is not available by then.
+        """
+
+        assert self.app is not None, "You must set the 'app' attribute to use this method."
+
+        tstart = time.perf_counter()
+
+        while True:
+            if max_duration is not None and time.perf_counter() - tstart > max_duration:
+                raise TimeoutError("Timed out waiting for token.")
+            if aborted and aborted.is_set():
+                raise RuntimeError("Polling for token was aborted.")
+            try:
+                if token := self.app.oauth2_access_token(device_code=self.device_code):
+                    return token
+            except AccessTokenError as e:
+                if e.error == "slow_down":
+                    time.sleep(5)
+                else:
+                    raise
+            time.sleep(self.interval)
+
+
+@dataclasses.dataclass
+class OAuth2TokenInfo:
+    access_token: str
+    expires_in: int
+    token_type: str
+    scope: t.Optional[str] = None
+    refresh_token: t.Optional[str] = None
+    refresh_token_expires_in: t.Optional[int] = None
+
+    @property
+    def auth_header(self) -> str:
+        return f"{self.token_type} {self.access_token}"
+
+
+@dataclasses.dataclass
+class AccessTokenError(Exception):
+    error: t.Literal[
+        "slow_down",
+        "expired_token",
+        "unsupported_grant_type",
+        "incorrect_client_credentials",
+        "incorrect_device_code",
+        "access_denied",
+        "device_flow_disabled",
+    ]

github_bot_api/token.py

@@ -59,7 +59,7 @@ def create_jwt(app_id: int, expires_in: int, private_key: str) -> TokenInfo:
 
     now = int(time.time())
     exp = now + expires_in
-    payload = {"iss": app_id, "iat": now, "exp": exp}
+    payload = {"iss": str(app_id), "iat": now, "exp": exp}
     token = jwt.encode(payload, private_key, algorithm="RS256")
     return TokenInfo(exp, "Bearer", token)
 

{github_bot_api-0.7.0.dist-info → github_bot_api-0.7.1.dist-info}/METADATA

@@ -1,13 +1,12 @@
 Metadata-Version: 2.1
 Name: github-bot-api
-Version: 0.7.0
+Version: 0.7.1
 Summary: API for creating GitHub bots and webhooks in Python.
 Author-Email: Niklas Rosenstein <rosensteinniklas@gmail.com>
 License: MIT
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -15,15 +14,14 @@ Classifier: Programming Language :: Python :: 3.13
 Project-URL: Bug Tracker, https://github.com/NiklasRosenstein/python-github-bot-api/issues
 Project-URL: Documentation, https://niklasrosenstein.github.io/python-github-bot-api/
 Project-URL: Repository, https://github.com/NiklasRosenstein/python-github-bot-api
-Requires-Python: <4.0,>=3.9
+Requires-Python: <4.0,>=3.10
 Requires-Dist: cryptography<44.0.1,>=44.0.0
 Requires-Dist: pygithub>=2.5.0
 Requires-Dist: PyJWT<3.0.0,>=2.6.0
 Requires-Dist: requests<3.0.0,>=2.28.2
-Requires-Dist: urllib3<2.4.0,>=2.3.0
+Requires-Dist: urllib3<2.6.4,>=2.6.3
 Description-Content-Type: text/markdown
 
-<p align="center"><img src="https://i.imgur.com/5SiDsz8.png"></p>
 <h1 align="center">python-github-bot-api</h1>
 <p align="center">
 <a href="https://pypi.org/project/github-bot-api"><img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/github-bot-api"></a></p>
@@ -32,18 +30,31 @@ Description-Content-Type: text/markdown
 
 A thin Python library for creating GitHub bots and webhooks in Python with [PyGithub].
 
+## Quickstart
+
 ```python
-from github import Github
 from github_bot_api import GithubApp
 from pathlib import Path
 
 app = GithubApp(
     user_agent='my-bot/0.0.0',
-    app_id="67890",
+    app_id="12345",
     private_key=Path("app-private.key").read_text(),
 )
+```
 
-client: Github = app.installation_client(12345)
+Create a PyGithub client for the app itself:
+
+```python
+from github import Github
+client: Github = app.app_client()
+```
+
+Create a PyGithub client for an app's installation scope:
+
+```python
+from github import Github
+client: Github = app.installation_client(45678)
 ```
 
 For more examples, check out the [documentation](https://niklasrosenstein.github.io/python-github-bot-api/).

{github_bot_api-0.7.0.dist-info → github_bot_api-0.7.1.dist-info}/RECORD

@@ -1,19 +1,19 @@
-github_bot_api-0.7.0.dist-info/METADATA,sha256=5LKKkccaGa0K0a1vHe6rUUMfXE0XW9spXjd5c-eQc64,1913
-github_bot_api-0.7.0.dist-info/WHEEL,sha256=thaaA2w1JzcGC48WYufAs8nrYZjJm8LqNfnXFOFyCC4,90
-github_bot_api-0.7.0.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
-github_bot_api-0.7.0.dist-info/licenses/LICENSE,sha256=bDVcEAS5rCEemhGT133WyYPEWhviXjCvQ46Pi_1gInQ,998
-github_bot_api/__init__.py,sha256=s4tkqx8qRBA66ELE6S583mEIi-REkLl_jW5mC4ubl1c,239
-github_bot_api/app.py,sha256=nRnQCkK_3OpPUknq8KpeWqMppgqunXTEsZAcArgC5mk,6575
+github_bot_api-0.7.1.dist-info/METADATA,sha256=z8jP-zLCXol5QlS0LumejKZt3VZZ0KQ3_8KICmWQh60,2007
+github_bot_api-0.7.1.dist-info/WHEEL,sha256=Wb0ASbVj8JvWHpOiIpPi7ucfIgJeCi__PzivviEAQFc,90
+github_bot_api-0.7.1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+github_bot_api-0.7.1.dist-info/licenses/LICENSE,sha256=bDVcEAS5rCEemhGT133WyYPEWhviXjCvQ46Pi_1gInQ,998
+github_bot_api/__init__.py,sha256=TcfSurT9yvlflzPlzACB5PbOJXjOcE7CWbcOGTSWbrA,239
+github_bot_api/app.py,sha256=BJh4yZuNnfGO9V8SwKwUMZZi4CMB0KJYHfYAfGmoKLA,14876
 github_bot_api/app_test.py,sha256=cKcdHKAVJ5DANWShQ0VG3BZgv1_fpEOvsiv0JYWWtGM,541
 github_bot_api/event.py,sha256=uxznCpkNfUGqjjvMxKUAX5TAUB_tbTaGhTyW8bSyaNU,3253
 github_bot_api/flask.py,sha256=2yVZW7_eor9m2Y_IsgpGPQ4rwtoVDAWSSyxeWnYZQKo,1583
 github_bot_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 github_bot_api/signature.py,sha256=ZMFEykII2FiutpL6qInfgIiqBZTkZbW4MJPWXlyZM84,1675
 github_bot_api/tests/test_import.py,sha256=BUyUDZW7imoS6Kqg7nHnmv3UKZ-yQPmAcf8DJhz_TX0,59
-github_bot_api/token.py,sha256=lWDnAs4WV7fsDcCTQcHNMjE6urier0J-Lm_cRsyF7Uk,4493
+github_bot_api/token.py,sha256=84XoildTyc75Zn46n8EjpTRjFGY3IPPDoLqfgenwsMI,4498
 github_bot_api/utils/__init__.py,sha256=n1bnYdeb_bNDBKASWGywTRa0Ne9hMAkal3AuVZJgovI,5
 github_bot_api/utils/functions.py,sha256=4xqf7G3A-CXVIan2se4XRzSwnUqRdVizNoF3JCrMgOg,748
 github_bot_api/utils/mime.py,sha256=e5b0zB2biy7FgDnTWXNUELicFy6CQ7rm-nbA-R2xMaM,738
 github_bot_api/utils/types.py,sha256=0AMwej7xeVmJULIBGiAowbItZhFASM6pgua_gT5holY,233
 github_bot_api/webhook.py,sha256=syDxg6NSOaqdS-CzDRPYW-RY27zk6YgIEeWNGL8zhDI,2055
-github_bot_api-0.7.0.dist-info/RECORD,,
+github_bot_api-0.7.1.dist-info/RECORD,,

{github_bot_api-0.7.0.dist-info → github_bot_api-0.7.1.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: pdm-backend (2.4.3)
+Generator: pdm-backend (2.4.7)
 Root-Is-Purelib: true
 Tag: py3-none-any