github-bot-api 0.5.1__tar.gz → 0.6.0__tar.gz

github-bot-api-0.5.1/LICENSE.txt → github_bot_api-0.6.0/LICENSE

@@ -1,6 +1,6 @@
-The MIT License
+MIT License
 
-Copyright (c) 2021 Niklas Rosenstein
+Copyright (c) 2022 Niklas Rosenstein
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 this software and associated documentation files (the "Software"), to deal in

github_bot_api-0.6.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.1
+Name: github-bot-api
+Version: 0.6.0
+Summary: API for creating GitHub bots and webhooks in Python.
+License: MIT
+Author: Niklas Rosenstein
+Author-email: rosensteinniklas@gmail.com
+Requires-Python: >=3.8,<4.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: PyGithub (>=1.58,<2.0)
+Requires-Dist: PyJWT (>=2.6.0,<3.0.0)
+Requires-Dist: cryptography (>=42.0.5,<43.0.0)
+Requires-Dist: flask
+Requires-Dist: requests (>=2.28.2,<3.0.0)
+Requires-Dist: urllib3 (>=1.26.15,<2.0.0)
+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
+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>
+
+  [PyGithub]: https://pypi.org/project/PyGithub/
+
+A thin Python library for creating GitHub bots and webhooks in Python with [PyGithub].
+
+```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",
+    private_key=Path("app-private.key").read_text(),
+)
+
+client: Github = app.installation_client(12345)
+```
+
+For more examples, check out the [documentation](https://niklasrosenstein.github.io/python-github-bot-api/).
+

github_bot_api-0.6.0/README.md

@@ -0,0 +1,24 @@
+<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>
+
+  [PyGithub]: https://pypi.org/project/PyGithub/
+
+A thin Python library for creating GitHub bots and webhooks in Python with [PyGithub].
+
+```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",
+    private_key=Path("app-private.key").read_text(),
+)
+
+client: Github = app.installation_client(12345)
+```
+
+For more examples, check out the [documentation](https://niklasrosenstein.github.io/python-github-bot-api/).

github_bot_api-0.6.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "github-bot-api"
+version = "0.6.0"
+description = "API for creating GitHub bots and webhooks in Python."
+authors = ["Niklas Rosenstein <rosensteinniklas@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "github_bot_api", from = "src" }]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11"
+]
+keywords = []
+
+[tool.poetry.urls]
+"Bug Tracker" = "https://github.com/NiklasRosenstein/python-github-bot-api/issues"
+Documentation = "https://niklasrosenstein.github.io/python-github-bot-api/"
+Repository = "https://github.com/NiklasRosenstein/python-github-bot-api"
+
+[tool.poetry.dependencies]
+python = "^3.8"
+cryptography = "^42.0.5"
+flask = { version = "*", optional = true }
+PyGithub = { version = "^1.58", optional = true }
+PyJWT = "^2.6.0"
+requests = "^2.28.2"
+urllib3 = "^1.26.15"
+
+[tool.poetry.dev-dependencies]
+black = "*"
+flake8 = "*"
+isort = "*"
+mypy = "*"
+pytest = "*"
+types-flask = "*"
+types-requests = "*"
+
+[tool.slap]
+typed = true
+
+[tool.slap.test]
+check = "slap check"
+mypy = "dmypy run src"
+pytest = "pytest -vv"
+black = "black --check src"
+isort = "isort --check-only src"
+flake8 = "flake8 src"
+
+[tool.slap.run]
+fmt = "black src && isort src"
+
+[tool.mypy]
+python_version = "3.8"
+explicit_package_bases = true
+mypy_path = ["src"]
+namespace_packages = true
+pretty = true
+show_error_codes = true
+show_error_context = true
+# strict = true
+warn_no_return = true
+warn_redundant_casts = true
+warn_unreachable = true
+warn_unused_ignores = true
+check_untyped_defs = true
+
+[tool.isort]
+profile = "black"
+line_length = 120
+combine_as_imports = true
+
+[tool.black]
+line-length = 120

github_bot_api-0.6.0/src/github_bot_api/__init__.py

@@ -0,0 +1,8 @@
+__author__ = "Niklas Rosenstein <nrosenstein@palantir.com>"
+__version__ = "0.6.0"
+
+from .app import GithubApp
+from .event import Event, accept_event
+from .webhook import Webhook
+
+__all__ = ["GithubApp", "Event", "accept_event", "Webhook"]

github_bot_api-0.6.0/src/github_bot_api/app.py

@@ -0,0 +1,188 @@
+"""
+Registry for GitHub event handlers.
+"""
+
+import dataclasses
+import logging
+import sys
+import threading
+import typing as t
+
+import requests
+import urllib3
+
+from . import __version__
+from .token import InstallationTokenSupplier, JwtSupplier, TokenInfo
+from .utils.functions import coalesce
+
+T = t.TypeVar("T")
+logger = logging.getLogger(__name__)
+user_agent = f"python/{sys.version.split()[0]} github-bot-api/{__version__}"
+
+if t.TYPE_CHECKING:
+    import github
+
+
+@dataclasses.dataclass
+class GithubClientSettings:
+    """
+    Settings for constructing a #github.Github client object.
+    """
+
+    base_url: t.Optional[str] = None
+    user_agent: t.Optional[str] = None
+    timeout: t.Optional[int] = None
+    per_page: t.Optional[int] = None
+    verify: t.Optional[bool] = None
+    retry: t.Optional[urllib3.Retry] = None
+
+    def update(self, other: "GithubClientSettings") -> "GithubClientSettings":
+        result = GithubClientSettings()
+        for field in dataclasses.fields(self):
+            value = getattr(other, field.name)
+            if value is None:
+                value = getattr(self, field.name)
+            setattr(result, field.name, value)
+        return result
+
+    def make_client(self, login_or_token: t.Optional[str] = None, jwt: t.Optional[str] = None) -> "github.Github":
+        import github
+        import github.Consts
+
+        return github.Github(
+            login_or_token=login_or_token,
+            jwt=jwt,
+            base_url=self.base_url or github.Consts.DEFAULT_BASE_URL,
+            user_agent=self.user_agent or "PyGithub/Python",
+            timeout=coalesce(self.timeout, github.Consts.DEFAULT_TIMEOUT),
+            per_page=coalesce(self.per_page, github.Consts.DEFAULT_PER_PAGE),
+            verify=coalesce(self.verify, True),
+            retry=self.retry,
+        )
+
+
+@dataclasses.dataclass
+class GithubApp:
+    """
+    Represents a GitHub application and all the required details.
+    """
+
+    PUBLIC_GITHUB_V3_API_URL = "https://api.github.com"
+
+    user_agent: str
+    """User agent of the application. This will be respected in #get_user_agent()."""
+
+    app_id: int
+    """GitHub Application ID."""
+
+    private_key: str
+    """RSA private key to sign the JWT with."""
+
+    v3_api_url: str = PUBLIC_GITHUB_V3_API_URL
+    """GitHub API base URL. Defaults to the public GitHub API."""
+
+    def __post_init__(self):
+        self._jwt_supplier = JwtSupplier(self.app_id, self.private_key)
+        self._lock = threading.Lock()
+        self._installation_tokens: t.Dict[int, InstallationTokenSupplier] = {}
+
+    def _get_base_github_client_settings(self) -> GithubClientSettings:
+        return GithubClientSettings(self.v3_api_url, self.get_user_agent())
+
+    def get_user_agent(self, installation_id: t.Optional[int] = None) -> str:
+        """
+        Create a user agent string for the PyGithub client, including the installation if specified.
+        """
+
+        user_agent = f"{self.user_agent} PyGithub/python (app_id={self.app_id}"
+        if installation_id:
+            user_agent += f", installation_id={installation_id})"
+        return user_agent
+
+    @property
+    def jwt(self) -> TokenInfo:
+        """
+        Returns the JWT for your GitHub application. The JWT is the token to use with GitHub application APIs.
+        """
+
+        return self._jwt_supplier()
+
+    @property
+    def jwt_supplier(self) -> JwtSupplier:
+        """
+        Returns a new #JwtSupplier that is used for generating JWT tokens for your GitHub application.
+        """
+
+        return JwtSupplier(self.app_id, self.private_key)
+
+    def app_client(self, settings: t.Union[GithubClientSettings, t.Dict[str, t.Any], None] = None) -> "github.Github":
+        """
+        Returns a PyGithub client for your GitHub application.
+
+        Note that the client's token will expire after 10 minutes and you will have to create a new client or update the
+        client's token with the value returned by #jwt. It is recommended that you create a new client for each atomic
+        operation you perform.
+
+        This requires you to install `PyGithub>=1.58`.
+        """
+
+        if isinstance(settings, dict):
+            settings = GithubClientSettings(**settings)
+        elif settings is None:
+            settings = GithubClientSettings()
+
+        settings = self._get_base_github_client_settings().update(settings)
+        return settings.make_client(jwt=self.jwt.value)
+
+    def __requestor(self, auth_header: str, installation_id: int) -> t.Dict[str, str]:
+        return requests.post(
+            self.v3_api_url.rstrip("/") + f"/app/installations/{installation_id}/access_tokens",
+            headers={"Authorization": auth_header, "User-Agent": user_agent},
+        ).json()
+
+    def get_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*.
+        """
+
+        with self._lock:
+            return self._installation_tokens.setdefault(
+                installation_id,
+                InstallationTokenSupplier(
+                    self._jwt_supplier,
+                    installation_id,
+                    self.__requestor,
+                ),
+            )
+
+    def installation_token(self, installation_id: int) -> TokenInfo:
+        """
+        A short-hand to retrieve a new installation token for the given *installation_id*.
+        """
+
+        return self.get_installation_token_supplier(installation_id)()
+
+    def installation_client(
+        self,
+        installation_id: int,
+        settings: t.Union[GithubClientSettings, t.Dict[str, t.Any], None] = None,
+    ) -> "github.Github":
+        """
+        Returns a PyGithub client for your GitHub application to act in the scope of the given *installation_id*.
+
+        Note that the client's token will expire after 10 minutes and you will have to create a new client or update the
+        client's token with the value returned by #jwt. It is recommended that you create a new client for each atomic
+        operation you perform.
+
+        This requires you to install `PyGithub>=1.58`.
+        """
+
+        if isinstance(settings, dict):
+            settings = GithubClientSettings(**settings)
+        elif settings is None:
+            settings = GithubClientSettings()
+
+        token = self.installation_token(installation_id).value
+        settings = self._get_base_github_client_settings().update(settings)
+        return settings.make_client(login_or_token=token)

github_bot_api-0.6.0/src/github_bot_api/app_test.py

@@ -0,0 +1,16 @@
+from unittest.mock import patch
+
+from github_bot_api.app import GithubApp
+from github_bot_api.token import TokenInfo
+
+
+def test_simple_app():
+    """
+    Regression test for PyGithub 1.58+ where such code failed on:
+
+        AttributeError: module 'github.MainClass' has no attribute 'DEFAULT_TIMEOUT'
+    """
+    token = TokenInfo(1, "Bearer", "token")
+    with patch("github_bot_api.token.InstallationTokenSupplier._new_token", return_value=token):
+        app = GithubApp("UA/0.0.0", 42, "private_key")
+        app.installation_client(1)

github_bot_api-0.6.0/src/github_bot_api/event.py

@@ -0,0 +1,95 @@
+"""
+Abstraction of a GitHub Webhook event.
+
+Reference: https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/webhook-events-and-payloads
+"""
+
+import json
+import logging
+import typing as t
+from dataclasses import dataclass
+
+from .signature import check_signature
+from .utils.mime import get_mime_components
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Event:
+    """
+    Represents a GitHub webhook event.
+    """
+
+    name: str
+    """ The name of the event. Could be `pull_request`, for example."""
+
+    delivery_id: str
+    """The delivery ID of the event."""
+
+    signature: t.Optional[str]
+    """The signature of the event. Will only be set if a Webhook-secret is configured on the
+    client side (e.g. in [`Webhook.secret`][github_bot_api.webhook.Webhook] / if the *webhook_secret* parameter is
+    passed to [`accept_event()`][github_bot_api.event.accept_event])."""
+
+    user_agent: str
+    """The user agent invoking the webhook."""
+
+    payload: t.Dict[str, t.Any]
+    """The event payload."""
+
+
+def accept_event(
+    headers: t.Mapping[str, str],
+    raw_body: bytes,
+    webhook_secret: t.Optional[str] = None,
+) -> Event:
+    """
+    Converts thee HTTP *headers* and the *raw_body* to an #Event object.
+
+    Args:
+        headers: The HTTP headers. Must have `X-Github-Event`, `X-Github-Delivery`, `User-Agent`, `Content-Type`.
+                 May have `X-Hub-Signature` or `X-Hub-Signature-256`.
+        raw_body: The raw request body for the event. This is converted into a JSON payload.
+        webhook_secret: If specified, the `X-Hub-Signature` or `X-Hub-Signature-256` headers are used to verify
+                        the signature of the payload. If not specified, the client does not validate the signature.
+    """
+
+    event_name = headers.get("X-GitHub-Event")
+    delivery_id = headers.get("X-GitHub-Delivery")
+    signature_1 = headers.get("X-Hub-Signature")
+    signature_256 = headers.get("X-Hub-Signature-256")
+    user_agent = headers.get("User-Agent")
+    content_type = headers.get("Content-Type")
+
+    if not event_name or not delivery_id or not user_agent or not content_type:
+        raise InvalidRequest("missing required headers")
+    if webhook_secret is not None and not signature_1 and not signature_256:
+        raise InvalidRequest("webhook secret is configured but no signature header was received")
+
+    mime_type, parameters = get_mime_components(content_type)
+    if mime_type != "application/json":
+        raise InvalidRequest(f"expected Content-Type: application/json, got {content_type}")
+    encoding = dict(parameters).get("encoding", "UTF-8")
+
+    if webhook_secret is not None:
+        if signature_256:
+            check_signature(signature_256, raw_body, webhook_secret.encode("ascii"), algo="sha256")
+        elif signature_1:
+            check_signature(signature_1, raw_body, webhook_secret.encode("ascii"), algo="sha1")
+        else:
+            raise RuntimeError
+
+    return Event(
+        event_name,
+        delivery_id,
+        signature_256 or signature_1,
+        user_agent,
+        json.loads(raw_body.decode(encoding)),
+    )
+
+
+class InvalidRequest(Exception):
+    """
+    Raised when an invalid request is passed to #accept_event().
+    """

github_bot_api-0.6.0/src/github_bot_api/flask.py

@@ -0,0 +1,61 @@
+"""
+Flask binding for handling GitHub webhook events.
+
+Note that you need to install the `flask` module separately.
+
+# Example
+
+```python
+from github_bot_api import Event, Webhook
+from github_bot_api.flask import create_flask_app
+
+def on_any_event(event: Event) -> bool:
+  print(event)
+  return True
+
+webhook = Webhook(secret=None)
+webhook.listen('*', on_any_event)
+
+import os; os.environ['FLASK_ENV'] = 'development'
+flask_app = create_flask_app(__name__, webhook)
+flask_app.run()
+```
+"""
+
+import typing as t
+
+import flask
+
+from .event import accept_event
+from .webhook import Webhook
+
+
+def create_event_handler(webhook: Webhook) -> t.Callable[[], t.Tuple[t.Text, int, t.Dict[str, str]]]:
+    """
+    Creates an event handler flask view that interprets the received HTTP request as a GitHub application
+    event and dispatches it via #webhook.dispatch().
+    """
+
+    def event_handler():
+        event = accept_event(
+            t.cast(t.Mapping[str, str], flask.request.headers), flask.request.get_data(), webhook.secret
+        )
+        webhook.dispatch(event)
+        return "", 202, {}
+
+    return event_handler
+
+
+def create_flask_app(
+    name: str,
+    webhook: Webhook,
+    path: str = "/event-handler",
+) -> flask.Flask:
+    """
+    Creates a new #flask.Flask application with a `POST` event handler under the given *path* (defaulting
+    to `/event-handler`). This is a useful shorthand to attach your #Webhook to an HTTP server.
+    """
+
+    flask_app = flask.Flask(name)
+    flask_app.route(path, methods=["POST"])(create_event_handler(webhook))
+    return flask_app

github_bot_api-0.6.0/src/github_bot_api/signature.py

@@ -0,0 +1,47 @@
+"""
+Helper to check the signature of a GitHub event request.
+"""
+
+import hmac
+
+
+def compute_signature(payload: bytes, secret: bytes, algo: str = "sha256") -> str:
+    """
+    Computes the HMAC signature of *payload* given the specified *secret* and the given hashing *algo*.
+
+    # Parmeters
+    payload: The payload for which the signature should be computed.
+    secret: The secret string that is used in conjunction to generate the signature.
+    algo: The hash algorithm to use, must be `sha1` or `sha256`.
+    """
+
+    if algo in {"sha1", "sha256"}:
+        return f"{algo}={hmac.new(secret, payload, algo).hexdigest()}"
+    raise ValueError(f"algo must be {{sha1, sha256}}, got {algo!r}")
+
+
+def check_signature(sig: str, payload: bytes, secret: bytes, algo: str = "sha256") -> None:
+    """
+    Compares the provided signature *sig* with the computed signature of the *payload* and
+    raises a #SignatureMismatchException if they do not match. This function uses constant-time
+    string comparison to prevent timing analysis.
+    """
+
+    computed = compute_signature(payload, secret, algo)
+    if not hmac.compare_digest(sig, computed):
+        raise SignatureMismatchException(sig, computed)
+
+
+class SignatureMismatchException(Exception):
+    """
+    Raised if a signature can not be verified with #check_signature().
+    """
+
+    _MSG = "The provided signature does not match the computed signature of the payload."
+
+    def __init__(self, provided: str, computed: str) -> None:
+        self.provided = provided
+        self.computed = computed
+
+    def __str__(self) -> str:
+        return f"{self._MSG}\n  provided: {self.provided}\n  computed: {self.computed}"

github_bot_api-0.6.0/src/github_bot_api/tests/test_import.py

@@ -0,0 +1,2 @@
+def test_import():
+    import github_bot_api  # noqa: F401