github-events 0.1.0__py3-none-any.whl

github_events/fastapi.py

@@ -0,0 +1,56 @@
+"""FastAPI integration: mount one endpoint that verifies and dispatches deliveries.
+
+    from fastapi import FastAPI
+    from github_events import WebhookDispatcher
+
+    hook = WebhookDispatcher(secret="...")
+    app = FastAPI()
+    app.include_router(hook.as_fastapi_router(path="/webhooks/github"))
+
+Responses: 204 on success (handled or not — unknown events are acknowledged so
+GitHub doesn't retry), 400 for a missing event header or malformed JSON, 401
+for a bad signature, 422 when a present field has the wrong type.
+"""
+
+from __future__ import annotations
+
+import json
+
+try:
+    from fastapi import APIRouter, HTTPException, Request, Response
+except ImportError as e:  # pragma: no cover
+    raise ImportError(
+        "github_events.fastapi requires fastapi — install github-events[fastapi]"
+    ) from e
+
+from pydantic import ValidationError  # fastapi always brings pydantic
+
+from github_events.dispatch import SignatureVerificationError, WebhookDispatcher
+
+__all__ = ["create_router"]
+
+
+def create_router(dispatcher: WebhookDispatcher, *, path: str = "/") -> APIRouter:
+    """An APIRouter whose single POST endpoint feeds deliveries to `dispatcher`."""
+    router = APIRouter()
+
+    @router.post(path, status_code=204)
+    async def receive_github_event(request: Request) -> Response:
+        event = request.headers.get("x-github-event")
+        if event is None:
+            raise HTTPException(400, "missing X-GitHub-Event header")
+        try:
+            await dispatcher.dispatch(
+                event,
+                await request.body(),
+                signature_256=request.headers.get("x-hub-signature-256"),
+            )
+        except SignatureVerificationError as e:
+            raise HTTPException(401, str(e)) from e
+        except json.JSONDecodeError as e:
+            raise HTTPException(400, f"invalid JSON body: {e}") from e
+        except ValidationError as e:
+            raise HTTPException(422, e.errors()) from e
+        return Response(status_code=204)
+
+    return router

github_events/validation.py

@@ -0,0 +1,70 @@
+"""Optional pydantic validation of webhook payloads (github-events[pydantic]).
+
+Validation is deliberately lenient — GitHub evolves payloads constantly, and
+GitHub Enterprise Server deliveries lag the api.github.com schema:
+
+- Fields the schema doesn't know are ignored, and the payload returned here is
+  the exact dict GitHub sent — validation never mutates or drops keys.
+- Missing fields are tolerated: the schema's `required` lists reflect current
+  api.github.com, not every delivery (recorded examples and GHES omit fields).
+- `null` for a non-nullable field is tolerated (schema nullability drift).
+- A field present with a non-null value of the wrong type fails: ValidationError.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from typing import Any
+
+try:
+    from pydantic import TypeAdapter, ValidationError
+except ImportError as e:  # pragma: no cover
+    raise ImportError(
+        "github_events.validation requires pydantic — install github-events[pydantic]"
+    ) from e
+
+from github_events._registry import ACTION_EVENTS, ACTION_TYPES, EVENT_TYPES
+
+__all__ = ["ValidationError", "get_adapter", "payload_type_for", "validate_payload"]
+
+
+@cache
+def get_adapter(payload_type: Any) -> TypeAdapter[Any]:
+    """One lazily-built TypeAdapter per payload type (they're expensive to build)."""
+    return TypeAdapter(payload_type)
+
+
+def payload_type_for(event: str, action: str | None) -> Any | None:
+    """The payload type to validate against, or None to pass the payload through.
+
+    Unknown events — and known events with an action GitHub added after these
+    types were generated — get no validation rather than a rejection.
+    """
+    if action is not None:
+        if (t := ACTION_TYPES.get((event, action))) is not None:
+            return t
+        if event in ACTION_EVENTS:
+            return None
+    return EVENT_TYPES.get(event)
+
+
+def validate_payload(event: str, action: str | None, data: Any) -> Any:
+    """Check `data` against the payload type for (event, action); return `data`.
+
+    Raises pydantic.ValidationError only when a present, non-null field has the
+    wrong type. Missing fields, unknown fields and unexpected nulls never fail
+    validation (see module docstring).
+    """
+    if (t := payload_type_for(event, action)) is None:
+        return data
+    try:
+        get_adapter(t).validate_python(data)
+    except ValidationError as e:
+        hard = [
+            err
+            for err in e.errors()
+            if err["type"] != "missing" and err.get("input") is not None
+        ]
+        if hard:
+            raise
+    return data

github_events-0.1.0.dist-info/METADATA

@@ -0,0 +1,37 @@
+Metadata-Version: 2.3
+Name: github-events
+Version: 0.1.0
+Summary: TypedDicts for every GitHub webhook event, with optional pydantic validation and FastAPI dispatch
+Requires-Dist: typing-extensions>=4.12
+Requires-Dist: fastapi>=0.110 ; extra == 'fastapi'
+Requires-Dist: pydantic>=2.0 ; extra == 'fastapi'
+Requires-Dist: pydantic>=2.0 ; extra == 'pydantic'
+Requires-Python: >=3.11
+Provides-Extra: fastapi
+Provides-Extra: pydantic
+Description-Content-Type: text/markdown
+
+# github-events
+
+Typed GitHub webhook payloads, HMAC signature verification, and event dispatch.
+
+```sh
+pip install github-events
+# Optional payload validation and FastAPI integration:
+pip install 'github-events[fastapi]'
+```
+
+```python
+import os
+from github_events import WebhookDispatcher
+
+hooks = WebhookDispatcher(secret=os.environ["GITHUB_WEBHOOK_SECRET"])
+
+@hooks.on("push")
+async def on_push(payload):
+    print(payload["ref"])
+```
+
+Pass the raw request body and GitHub webhook headers to the dispatcher, or mount
+its `as_fastapi_router()` in your FastAPI application. The base package depends only on `typing-extensions`. The `pydantic` extra adds validation; the `fastapi` extra
+adds the HTTP integration and validation dependencies.

github_events-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+github_events/__init__.py,sha256=6NJYlFk0b6SuY5VyRILO6DLVCzfAVQ_oNqbP4N42mgU,1314
+github_events/_models.py,sha256=CuMOZ2PcamNBynzbGSyNsW5NkUx72O0KcWPbI96cG3E,217679
+github_events/_registry.py,sha256=D_3C7KnmeriBUGKMjCzGZ3Ao86PIIhKPN29NT3mOkuQ,22542
+github_events/dispatch.py,sha256=PdYx7YGixy8soWuE7HTxFNfxRFGp6rt0JeJvLvgKWDE,5594
+github_events/dispatch.pyi,sha256=Y0qvBNdvQcuBgGEG_9AXYmHtXOEGYyFuqa6exdRZg24,49625
+github_events/fastapi.py,sha256=1Q61IwXk9a-KYr4spYEZmrUnEWBNwlTpkHcbRG8WBDA,2019
+github_events/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+github_events/validation.py,sha256=3A8-wIOTFVvjNyFQjV7CzrmtP3ITnPRR9fA4boTp1mg,2611
+github_events-0.1.0.dist-info/WHEEL,sha256=Q9FtwzuR2QE37l-JIkuyklGnJJiCBHKnsPVQ9vzCMzQ,81
+github_events-0.1.0.dist-info/METADATA,sha256=WejitsdMWbXR0oJsY9drmtEGGqbqNlnZov2lNzVHZRo,1212
+github_events-0.1.0.dist-info/RECORD,,

github_events-0.1.0.dist-info/WHEEL

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