monalisten 0.1.0__py3-none-any.whl

monalisten/__init__.py

@@ -0,0 +1,4 @@
+from . import types
+from ._core import Monalisten
+
+__all__ = ("Monalisten", "types")

monalisten/_core.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import asyncio
+import warnings
+from collections import defaultdict
+from itertools import chain
+from typing import TYPE_CHECKING, Any, Literal, TypeVar, cast
+
+import httpx
+from githubkit import webhooks
+from githubkit.versions.v2022_11_28.webhooks import VALID_EVENT_NAMES
+from httpx_sse import ServerSentEvent, aconnect_sse
+from pydantic import ValidationError
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from githubkit.versions.v2022_11_28.webhooks import EventNameType, WebhookEvent
+    from typing_extensions import TypeAlias
+
+H = TypeVar("H", bound="WebhookEvent")
+Hook: TypeAlias = "Callable[[H], Awaitable[None]]"
+HookTrigger: TypeAlias = 'Literal[EventNameType, "*"]'
+
+GUID_HEADER = "x-github-delivery"
+EVENT_HEADER = "x-github-event"
+SIG_HEADER = "x-hub-signature-256"
+
+
+class MonalistenError(Exception):
+    """Exception for errors encountered by the Monalisten client."""
+
+
+class Monalisten:
+    """
+    A Monalisten client streaming events from `source`, optionally secured by the secret
+    `token`. For details on `log_auth_warnings`, see the "Warnings & authentication
+    behavior" section of the documentation.
+    """
+
+    def __init__(
+        self, source: str, *, token: str | None = None, log_auth_warnings: bool = False
+    ) -> None:
+        self._source = source
+        self._token = token
+        self._log = log_auth_warnings
+        self._hooks = defaultdict[HookTrigger, list[Hook]](list)
+
+    def _passes_auth(self, event_data: dict[str, Any]) -> bool:
+        if not self._token:
+            if SIG_HEADER in event_data:
+                self._warn(
+                    event_data, f"Received {SIG_HEADER} header, but no token was set"
+                )
+            return True
+
+        if not (signature := event_data.get(SIG_HEADER)):
+            self._warn(event_data, f"Missing {SIG_HEADER} header")
+            return False
+
+        if webhooks.verify(self._token, event_data["body"], signature):
+            return True
+
+        self._warn(event_data, f"{SIG_HEADER} header does not match set token")
+        return False
+
+    def _warn(self, event_data: dict[str, Any], message: str) -> None:
+        if not self._log:
+            return
+        name = event_data.get(EVENT_HEADER, "unknown")
+        guid = event_data.get(GUID_HEADER, "unknown")
+        warnings.warn(f"Event {name} ({guid}): {message}", stacklevel=3)
+
+    def on(self, event: HookTrigger) -> Callable[[Hook[H]], Hook[H]]:
+        """Register the decorated function as a hook for the `event` event."""
+        if event not in VALID_EVENT_NAMES and event != "*":
+            msg = f"Invalid event name: {event!r}"
+            raise MonalistenError(msg)
+
+        def wrapper(hook: Hook[H]) -> Hook[H]:
+            self._hooks[event].append(hook)
+            return hook
+
+        return wrapper
+
+    async def _handle_event(self, event: ServerSentEvent) -> None:
+        if event.data == "{}":
+            return
+        data = event.json()
+
+        if not self._passes_auth(data):
+            return
+
+        if not (event_name := data.get(EVENT_HEADER)):
+            msg = f"received data is missing the {EVENT_HEADER} header"
+            raise MonalistenError(msg)
+
+        if not (body := data.get("body")):
+            msg = "received data doesn't contain a body"
+            raise MonalistenError(msg)
+
+        try:
+            webhook_event = cast("WebhookEvent", webhooks.parse_obj(event_name, body))
+        except ValidationError as pydantic_exc:
+            msg = "the received payload could not be parsed as an event"
+            raise MonalistenError(msg) from pydantic_exc
+
+        coros = (
+            hook(webhook_event)
+            for hook in chain.from_iterable(
+                self._hooks.get(hook_kind, []) for hook_kind in (event_name, "*")
+            )
+        )
+        await asyncio.gather(*coros)
+
+    async def listen(self) -> None:
+        """Start an internal HTTP client and stream events from `source`."""
+        async with (
+            httpx.AsyncClient(timeout=None) as client,
+            aconnect_sse(client, "GET", self._source) as sse,
+        ):
+            async for event in sse.aiter_sse():
+                await self._handle_event(event)

monalisten/types.py

@@ -0,0 +1,157 @@
+from githubkit.versions.v2022_11_28.webhooks import (
+    BranchProtectionConfigurationEvent,
+    BranchProtectionRuleEvent,
+    CheckRunEvent,
+    CheckSuiteEvent,
+    CodeScanningAlertEvent,
+    CommitCommentEvent,
+    CreateEvent,
+    CustomPropertyEvent,
+    CustomPropertyValuesEvent,
+    DeleteEvent,
+    DependabotAlertEvent,
+    DeployKeyEvent,
+    DeploymentEvent,
+    DeploymentProtectionRuleEvent,
+    DeploymentReviewEvent,
+    DeploymentStatusEvent,
+    DiscussionCommentEvent,
+    DiscussionEvent,
+    ForkEvent,
+    GithubAppAuthorizationEvent,
+    GollumEvent,
+    InstallationEvent,
+    InstallationRepositoriesEvent,
+    InstallationTargetEvent,
+    IssueCommentEvent,
+    IssueDependenciesEvent,
+    IssuesEvent,
+    LabelEvent,
+    MarketplacePurchaseEvent,
+    MemberEvent,
+    MembershipEvent,
+    MergeGroupEvent,
+    MetaEvent,
+    MilestoneEvent,
+    OrganizationEvent,
+    OrgBlockEvent,
+    PackageEvent,
+    PageBuildEvent,
+    PersonalAccessTokenRequestEvent,
+    PingEvent,
+    ProjectCardEvent,
+    ProjectColumnEvent,
+    ProjectEvent,
+    ProjectsV2Event,
+    ProjectsV2ItemEvent,
+    ProjectsV2StatusUpdateEvent,
+    PublicEvent,
+    PullRequestEvent,
+    PullRequestReviewCommentEvent,
+    PullRequestReviewEvent,
+    PullRequestReviewThreadEvent,
+    PushEvent,
+    RegistryPackageEvent,
+    ReleaseEvent,
+    RepositoryAdvisoryEvent,
+    RepositoryDispatchEvent,
+    RepositoryEvent,
+    RepositoryImportEvent,
+    RepositoryRulesetEvent,
+    RepositoryVulnerabilityAlertEvent,
+    SecretScanningAlertEvent,
+    SecretScanningAlertLocationEvent,
+    SecretScanningScanEvent,
+    SecurityAdvisoryEvent,
+    SecurityAndAnalysisEvent,
+    SponsorshipEvent,
+    StarEvent,
+    StatusEvent,
+    SubIssuesEvent,
+    TeamAddEvent,
+    TeamEvent,
+    WatchEvent,
+    WebhookEvent,
+    WorkflowDispatchEvent,
+    WorkflowJobEvent,
+    WorkflowRunEvent,
+)
+
+__all__ = (
+    "BranchProtectionConfigurationEvent",
+    "BranchProtectionRuleEvent",
+    "CheckRunEvent",
+    "CheckSuiteEvent",
+    "CodeScanningAlertEvent",
+    "CommitCommentEvent",
+    "CreateEvent",
+    "CustomPropertyEvent",
+    "CustomPropertyValuesEvent",
+    "DeleteEvent",
+    "DependabotAlertEvent",
+    "DeployKeyEvent",
+    "DeploymentEvent",
+    "DeploymentProtectionRuleEvent",
+    "DeploymentReviewEvent",
+    "DeploymentStatusEvent",
+    "DiscussionCommentEvent",
+    "DiscussionEvent",
+    "ForkEvent",
+    "GithubAppAuthorizationEvent",
+    "GollumEvent",
+    "InstallationEvent",
+    "InstallationRepositoriesEvent",
+    "InstallationTargetEvent",
+    "IssueCommentEvent",
+    "IssueDependenciesEvent",
+    "IssuesEvent",
+    "LabelEvent",
+    "MarketplacePurchaseEvent",
+    "MemberEvent",
+    "MembershipEvent",
+    "MergeGroupEvent",
+    "MetaEvent",
+    "MilestoneEvent",
+    "OrgBlockEvent",
+    "OrganizationEvent",
+    "PackageEvent",
+    "PageBuildEvent",
+    "PersonalAccessTokenRequestEvent",
+    "PingEvent",
+    "ProjectCardEvent",
+    "ProjectColumnEvent",
+    "ProjectEvent",
+    "ProjectsV2Event",
+    "ProjectsV2ItemEvent",
+    "ProjectsV2StatusUpdateEvent",
+    "PublicEvent",
+    "PullRequestEvent",
+    "PullRequestReviewCommentEvent",
+    "PullRequestReviewEvent",
+    "PullRequestReviewThreadEvent",
+    "PushEvent",
+    "RegistryPackageEvent",
+    "ReleaseEvent",
+    "RepositoryAdvisoryEvent",
+    "RepositoryDispatchEvent",
+    "RepositoryEvent",
+    "RepositoryImportEvent",
+    "RepositoryRulesetEvent",
+    "RepositoryVulnerabilityAlertEvent",
+    "SecretScanningAlertEvent",
+    "SecretScanningAlertLocationEvent",
+    "SecretScanningScanEvent",
+    "SecurityAdvisoryEvent",
+    "SecurityAndAnalysisEvent",
+    "SponsorshipEvent",
+    "StarEvent",
+    "StatusEvent",
+    "SubIssuesEvent",
+    "TeamAddEvent",
+    "TeamEvent",
+    "WatchEvent",
+    "WebhookEvent",
+    "WorkflowDispatchEvent",
+    "WorkflowJobEvent",
+    "WorkflowRunEvent",
+)

monalisten-0.1.0.dist-info/METADATA

@@ -0,0 +1,247 @@
+Metadata-Version: 2.3
+Name: monalisten
+Version: 0.1.0
+Summary: Monalisten is an async library for handling GitHub webhook events in an easy way
+Author: trag1c
+Author-email: trag1c <dev@jakubr.me>
+Requires-Dist: githubkit~=0.13
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: httpx-sse>=0.4.1
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+# Monalisten
+
+Monalisten is a Python 3.9+ asynchronous library that helps you handle webhook
+events received from GitHub in an easy way. It is built on top of the amazing
+[`githubkit`][githubkit] and [`httpx`][httpx] libraries and relies on [SSE]
+(with [`httpx-sse`][httpx-sse]) to stream events without exposing any endpoints.
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Foreword on how this works](#foreword-on-how-this-works)
+  - [Basic example](#basic-example)
+  - [One event, multiple hooks](#one-event-multiple-hooks)
+  - [One hook, multiple events](#one-hook-multiple-events)
+  - [Wildcard hooks](#wildcard-hooks)
+  - [Warnings & authentication behavior](#warnings--authentication-behavior)
+  - [API reference](#api-reference)
+  - [GitHub event type reference](#github-event-type-reference)
+  - [`monalisten.types` reference](#monalistentypes-reference)
+- [License](#license)
+
+## Installation
+
+`monalisten` is available on PyPI and can be installed with any package manager:
+
+```sh
+pip install monalisten
+# or
+poetry add monalisten
+# or
+uv add monalisten
+```
+
+You can also install it from source:
+
+```sh
+pip install git+https://github.com/trag1c/monalisten.git
+```
+
+
+## Usage
+
+### Foreword on how this works
+
+GitHub webhooks can only send event data to publicly accessible HTTP endpoints.
+If your environment is behind a firewall, or a NAT, or you simply don't want to
+set up a server, you can use a relay service, like [smee.io]. It generates a
+unique relay URL to which GitHub sends requests to, and the relay then streams
+them to your local client via SSE. Monalisten connects to the relay's SSE URL
+and receives events as they arrive without any direct incoming connection to
+your machine.
+
+> [!warning]
+> Relay URLs are essentially private endpoints. Anyone who knows your relay URL
+> can send forged events. To mitigate this, configure a **webhook secret** in
+> your GitHub repository or organization webhook settings. Pass the same secret
+> to Monalisten through the `token` parameter. Now, Monalisten will validate
+> incoming payloads and discard invalid ones.
+
+
+### Basic example
+
+```py
+import asyncio
+
+from monalisten import Monalisten
+from monalisten.types import PushEvent
+
+client = Monalisten("https://smee.io/aBCDef1gHijKLM2N", token="foobar")
+
+
+@client.on("push")
+async def log_push(event: PushEvent) -> None:
+    actor = event.sender.login if event.sender else "Someone"
+    print(f"{actor} pushed to the repo!")
+
+
+asyncio.run(client.listen())
+```
+
+Monalisten heavily relies on the [`githubkit`][githubkit] SDK for parsing and
+verifying payloads. The `monalisten.types` module (meant for type annotations)
+is actually a re-export of the `githubkit.versions.v2022_11_28.webhooks` module!
+
+
+### One event, multiple hooks
+
+You can decorate several functions with the same event passed to
+`Monalisten.on`, and both of them will be registered:
+
+```py
+@client.on("pull_request")
+async def log_opened_pr(event: PullRequestEvent) -> None:
+    if event.action != "opened":
+        return
+    print(f"New PR: #{event.number}")
+
+@client.on("pull_request")
+async def log_pr_action(event: PullRequestEvent) -> None:
+    print(f"Something happened to PR #{event.number}!")
+```
+
+When an event type has several hooks attached, they're all run concurrently.
+
+
+### One hook, multiple events
+
+You can decorate the same function with `Monalisten.on` several times:
+
+```py
+@client.on("pull_request")
+@client.on("push")
+async def log_things(event: PullRequestEvent | PushEvent) -> None:
+    if "PullRequest" in type(event).__name__:
+        print("Something happened to a PR!")
+    else:
+        print("Someone pushed!")
+```
+
+
+### Wildcard hooks
+
+You can define a hook to be triggered for ALL events by setting the event name
+to `*`:
+
+```py
+@client.on("*")
+async def log(event: WebhookEvent) -> None:
+    print(f"Something definitely happened... a {type(event).__name__} perhaps")
+```
+
+
+### Warnings & authentication behavior
+
+During its authentication step, Monalisten can issue warnings for unexpected
+state if you pass `log_auth_warnings=True` when creating a client.
+
+Monalisten will issue warnings in the following cases:
+
+* the client sets a token, but:
+  * the received event doesn't have a signature header
+  * the received event's signature cannot be validated with the client's token
+
+  (the event is not processed in both cases)
+
+* the client doesn't set a token, but the received event has a signature header
+  (the event is still processed)
+
+
+### API reference
+
+#### `Monalisten`
+
+```py
+class Monalisten:
+    def __init__(
+        self,
+        source: str,
+        *,
+        token: str | None = None,
+        log_auth_warnings: bool = False,
+    ) -> None: ...
+```
+
+Creates a Monalisten client streaming events from `source`, optionally secured
+by the secret `token`. For details on `log_auth_warnings`, see the
+[Warnings & authentication behavior](#warnings--authentication-behavior)
+section.
+
+
+#### `Monalisten.listen`
+
+```py
+class Monalisten:
+    async def listen(self) -> None: ...
+```
+
+Instantiates an internal HTTP client and starts streaming events from `source`.
+
+
+#### `Monalisten.on`
+
+```py
+class Monalisten:
+    def on(self, event: HookTrigger) -> Callable[[Hook[H]], Hook[H]]: ...
+```
+
+Meant to be used as a decorator. Registers the decorated function as a hook for
+the `event` event. Raises an error if an invalid event name is provided.
+`HookTrigger` is either a [GitHub event name](#github-event-type-reference) or
+the [wildcard hook `"*"`](#wildcard-hooks).
+
+In technical terms, this returns a function that registers the function passed
+in as a Monalisten hook.
+
+
+#### `MonalistenError`
+
+```py
+class MonalistenError(Exception): ...
+```
+
+An exception for errors encountered by the Monalisten client (e.g. invalid event
+name or missing payload data).
+
+
+### GitHub event name reference
+
+For a list of event names that can be passed to `Monalisten.on`, see GitHub's
+documentation page on [Webhook events and payloads][gh-events].
+
+
+### `monalisten.types` reference
+
+For a list of type names that can be used as event annotations, see the
+[src/monalisten/types.py][githubkit-types] file, or, if you use one,
+rely on your LSP's autocomplete!
+
+
+## License
+`monalisten` is licensed under the [MIT License].  
+© [trag1c], 2025
+
+
+[githubkit]: https://github.com/yanyongyu/githubkit
+[httpx]: https://github.com/encode/httpx
+[SSE]: https://en.wikipedia.org/wiki/Server-sent_events
+[httpx-sse]: https://github.com/florimondmanca/httpx-sse
+[smee.io]: https://smee.io/
+[gh-events]: https://docs.github.com/en/webhooks/webhook-events-and-payloads
+[githubkit-types]: https://github.com/trag1c/monalisten/blob/main/src/monalisten/types.py
+[MIT License]: https://opensource.org/license/mit
+[trag1c]: https://github.com/trag1c

monalisten-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+monalisten/__init__.py,sha256=ea74084a7fd2b97b8f0cdad32b224b965bbd4b641d19a2650a549fe0b421d527,85
+monalisten/_core.py,sha256=3896066dcafbf7c21758e5daa00798f764ad5e3042ee94850a37ef461c0382c7,4255
+monalisten/py.typed,sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855,0
+monalisten/types.py,sha256=eec9b53d101eb5caf5dac5d5459911bc2e1ea52f7d02c308986629c8c606393e,3877
+monalisten-0.1.0.dist-info/WHEEL,sha256=a51d7af6bb8356f1000fb3d205aba975eca53e14c9e011c620094d822eb4863c,79
+monalisten-0.1.0.dist-info/METADATA,sha256=44842f59ab8b93d3bcec07badbc3866c3a5548a8478bba501627711be72c08e6,7414
+monalisten-0.1.0.dist-info/RECORD,,

monalisten-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.8.10
+Root-Is-Purelib: true
+Tag: py3-none-any