policyengine-observability 0.2.0__tar.gz

policyengine_observability-0.2.0/.github/bump_version.py

@@ -0,0 +1,134 @@
+"""Infer semver bump from Towncrier fragment types and update version."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+SEMVER_PATTERN = re.compile(r"^(\d+)\.(\d+)\.(\d+)$")
+
+
+def parse_version(version: str) -> tuple[int, int, int]:
+    match = SEMVER_PATTERN.match(version)
+    if not match:
+        raise ValueError(f"Invalid semver: {version}")
+    return tuple(int(part) for part in match.groups())
+
+
+def get_pyproject_version(pyproject_path: Path) -> str:
+    text = pyproject_path.read_text()
+    match = re.search(r'^version\s*=\s*"(\d+\.\d+\.\d+)"', text, re.MULTILINE)
+    if not match:
+        print("Could not find version in pyproject.toml", file=sys.stderr)
+        sys.exit(1)
+    return match.group(1)
+
+
+def get_changelog_versions(changelog_path: Path) -> list[str]:
+    if not changelog_path.exists():
+        return []
+    return re.findall(
+        r"^## \[(\d+\.\d+\.\d+)\]",
+        changelog_path.read_text(),
+        re.MULTILINE,
+    )
+
+
+def get_git_tag_versions(repo_root: Path) -> list[str]:
+    try:
+        result = subprocess.run(
+            ["git", "tag"],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return []
+
+    versions = []
+    for tag in result.stdout.splitlines():
+        normalized = tag.removeprefix("v").strip()
+        if SEMVER_PATTERN.match(normalized):
+            versions.append(normalized)
+    return versions
+
+
+def get_current_version(
+    pyproject_path: Path,
+    changelog_path: Path,
+    repo_root: Path,
+) -> str:
+    candidates = [get_pyproject_version(pyproject_path)]
+    candidates.extend(get_changelog_versions(changelog_path))
+    candidates.extend(get_git_tag_versions(repo_root))
+    return max(candidates, key=parse_version)
+
+
+def infer_bump(changelog_dir: Path) -> str:
+    fragments = [
+        path
+        for path in changelog_dir.iterdir()
+        if path.is_file() and path.name != ".gitkeep"
+    ]
+    if not fragments:
+        print("No changelog fragments found", file=sys.stderr)
+        sys.exit(1)
+
+    categories = {path.suffix.lstrip(".") for path in fragments}
+    for path in fragments:
+        parts = path.stem.split(".")
+        if len(parts) >= 2:
+            categories.add(parts[-1])
+
+    if "breaking" in categories:
+        return "major"
+    if "added" in categories or "removed" in categories:
+        return "minor"
+    return "patch"
+
+
+def bump_version(version: str, bump: str) -> str:
+    major, minor, patch = (int(part) for part in version.split("."))
+    if bump == "major":
+        return f"{major + 1}.0.0"
+    if bump == "minor":
+        return f"{major}.{minor + 1}.0"
+    return f"{major}.{minor}.{patch + 1}"
+
+
+def update_file(path: Path, new_version: str) -> None:
+    text = path.read_text()
+    updated, replacements = re.subn(
+        r'(^version\s*=\s*")(\d+\.\d+\.\d+)(")',
+        rf"\g<1>{new_version}\g<3>",
+        text,
+        count=1,
+        flags=re.MULTILINE,
+    )
+    if replacements == 0:
+        print(f"Could not update version in {path}", file=sys.stderr)
+        sys.exit(1)
+    if updated != text:
+        path.write_text(updated)
+        print(f"  Updated {path}")
+
+
+def main() -> None:
+    root = Path(__file__).resolve().parent.parent
+    pyproject = root / "pyproject.toml"
+    changelog = root / "CHANGELOG.md"
+    changelog_dir = root / "changelog.d"
+
+    current = get_current_version(pyproject, changelog, root)
+    bump = infer_bump(changelog_dir)
+    new = bump_version(current, bump)
+
+    print(f"Version: {current} -> {new} ({bump})")
+    update_file(pyproject, new)
+
+
+if __name__ == "__main__":
+    main()

policyengine_observability-0.2.0/.github/check-changelog.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+BASE_REF="${1:-origin/main}"
+
+towncrier check --compare-with "$BASE_REF"

policyengine_observability-0.2.0/.github/fetch_version.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+def fetch_version(pyproject_path: Path) -> str:
+    text = pyproject_path.read_text()
+    match = re.search(r'^version\s*=\s*"(\d+\.\d+\.\d+)"', text, re.MULTILINE)
+    if not match:
+        print("Could not find version in pyproject.toml", file=sys.stderr)
+        sys.exit(1)
+    return match.group(1)
+
+
+def main() -> None:
+    root = Path(__file__).resolve().parent.parent
+    print(fetch_version(root / "pyproject.toml"))
+
+
+if __name__ == "__main__":
+    main()

policyengine_observability-0.2.0/.github/get-changelog-diff.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if git describe --tags --abbrev=0 --first-parent >/dev/null 2>&1; then
+  LAST_TAGGED_COMMIT="$(git describe --tags --abbrev=0 --first-parent)"
+  git --no-pager diff "$LAST_TAGGED_COMMIT" -- CHANGELOG.md
+else
+  git --no-pager diff HEAD -- CHANGELOG.md
+fi

policyengine_observability-0.2.0/.github/publish-git-tag.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+VERSION="$(python .github/fetch_version.py)"
+
+if git rev-parse --verify --quiet "refs/tags/${VERSION}" >/dev/null; then
+  echo "Tag ${VERSION} already exists locally."
+  exit 0
+fi
+
+git tag "${VERSION}"
+git push origin "${VERSION}"

policyengine_observability-0.2.0/.github/workflows/pr.yml

@@ -0,0 +1,69 @@
+name: Pull request
+
+on:
+  pull_request:
+    paths:
+      - "policyengine_observability/**"
+      - "tests/**"
+      - ".github/**"
+      - "changelog.d/**"
+      - "pyproject.toml"
+      - "uv.lock"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  check-changelog:
+    name: Check changelog fragment
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Check for changelog fragment
+        run: uv run --extra dev bash .github/check-changelog.sh "origin/${{ github.base_ref }}"
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Run ruff format check
+        run: uv run --extra dev ruff format --check .
+      - name: Run ruff check
+        run: uv run --extra dev ruff check .
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Run tests with coverage
+        run: uv run --extra dev --extra all coverage run -m pytest
+      - name: Enforce coverage
+        run: uv run --extra dev --extra all coverage report
+      - name: Write coverage XML
+        run: uv run --extra dev --extra all coverage xml

policyengine_observability-0.2.0/.github/workflows/push.yml

@@ -0,0 +1,158 @@
+name: Push
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: observability-release
+
+env:
+  VERSION_COMMIT_MESSAGE: Update observability package version
+
+jobs:
+  check-changelog:
+    name: Check changelog fragment
+    if: github.event.head_commit.message != 'Update observability package version'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Check for changelog fragment
+        env:
+          BASE_REF: ${{ github.event.before }}
+        run: |
+          BASE_REF="${BASE_REF:-HEAD^}"
+          uv run --extra dev bash .github/check-changelog.sh "$BASE_REF"
+
+  lint:
+    name: Lint
+    if: github.event.head_commit.message != 'Update observability package version'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Run ruff format check
+        run: uv run --extra dev ruff format --check .
+      - name: Run ruff check
+        run: uv run --extra dev ruff check .
+
+  test:
+    name: Test
+    if: github.event.head_commit.message != 'Update observability package version'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Run tests with coverage
+        run: uv run --extra dev --extra all coverage run -m pytest
+      - name: Enforce coverage
+        run: uv run --extra dev --extra all coverage report
+      - name: Write coverage XML
+        run: uv run --extra dev --extra all coverage xml
+
+  versioning:
+    name: Update versioning
+    needs:
+      - check-changelog
+      - lint
+      - test
+    if: github.event.head_commit.message != 'Update observability package version'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Generate GitHub App token
+        id: app-token
+        uses: actions/create-github-app-token@v3
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+      - name: Checkout repo
+        uses: actions/checkout@v6
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          fetch-depth: 0
+      - name: Fetch tags
+        run: git fetch --tags --force
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Build changelog
+        run: |
+          uv run --extra dev python .github/bump_version.py
+          uv run --extra dev towncrier build --yes --version "$(uv run python .github/fetch_version.py)"
+      - name: Preview changelog update
+        run: bash .github/get-changelog-diff.sh
+      - name: Update changelog and package version
+        uses: EndBug/add-and-commit@v10
+        with:
+          add: "."
+          message: ${{ env.VERSION_COMMIT_MESSAGE }}
+          github_token: ${{ steps.app-token.outputs.token }}
+          fetch: false
+
+  publish:
+    name: Publish
+    if: github.event.head_commit.message == 'Update observability package version'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write
+      id-token: write
+    env:
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Publish git tag
+        run: bash .github/publish-git-tag.sh
+      - name: Build package
+        run: uv build
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+      - name: Create GitHub release
+        run: |
+          VERSION="$(uv run python .github/fetch_version.py)"
+          gh release create "$VERSION" \
+            --title "v$VERSION" \
+            --notes "See CHANGELOG.md for details." \
+            --latest

policyengine_observability-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+__pycache__/
+*.py[cod]
+.DS_Store

policyengine_observability-0.2.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+## [0.2.0] - 2026-06-22
+
+### Added
+
+- Add pull request and push CI/CD workflows with changelog, lint, coverage, versioning, tagging, and PyPI publishing gates.
+
+
+# Changelog
+

policyengine_observability-0.2.0/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: policyengine-observability
+Version: 0.2.0
+Summary: Shared PolicyEngine observability runtime for logs, timings, metrics, and OpenTelemetry.
+Author-email: PolicyEngine <hello@policyengine.org>
+Requires-Python: >=3.12
+Provides-Extra: all
+Requires-Dist: fastapi; extra == 'all'
+Requires-Dist: flask>=2.2; extra == 'all'
+Requires-Dist: httpx; extra == 'all'
+Requires-Dist: opentelemetry-api; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc; extra == 'all'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-fastapi; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-httpx; extra == 'all'
+Requires-Dist: opentelemetry-sdk; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: coverage; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: towncrier>=24.8.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi; extra == 'fastapi'
+Requires-Dist: opentelemetry-instrumentation-fastapi; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.2; extra == 'flask'
+Provides-Extra: httpx
+Requires-Dist: httpx; extra == 'httpx'
+Requires-Dist: opentelemetry-instrumentation-httpx; extra == 'httpx'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api; extra == 'otel'
+Requires-Dist: opentelemetry-sdk; extra == 'otel'
+Provides-Extra: otlp-grpc
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc; extra == 'otlp-grpc'
+Provides-Extra: otlp-http
+Requires-Dist: opentelemetry-exporter-otlp-proto-http; extra == 'otlp-http'
+Description-Content-Type: text/markdown
+
+# policyengine-observability
+
+Shared PolicyEngine observability runtime for fail-open local timings,
+structured logs, OpenTelemetry traces, and OpenTelemetry metrics.
+
+The package intentionally keeps framework support in adapters:
+
+- `policyengine_observability.adapters.flask`
+- `policyengine_observability.adapters.fastapi`
+- `policyengine_observability.integrations.httpx`
+
+OpenTelemetry imports are lazy. Timing and structured logging can run without
+an OTel backend; exporting traces/metrics is opt-in through configuration.

policyengine_observability-0.2.0/README.md

@@ -0,0 +1,13 @@
+# policyengine-observability
+
+Shared PolicyEngine observability runtime for fail-open local timings,
+structured logs, OpenTelemetry traces, and OpenTelemetry metrics.
+
+The package intentionally keeps framework support in adapters:
+
+- `policyengine_observability.adapters.flask`
+- `policyengine_observability.adapters.fastapi`
+- `policyengine_observability.integrations.httpx`
+
+OpenTelemetry imports are lazy. Timing and structured logging can run without
+an OTel backend; exporting traces/metrics is opt-in through configuration.

policyengine_observability-0.2.0/policyengine_observability/__init__.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .config import ObservabilityConfig
+from .context import OperationObservabilityContext, RequestObservabilityContext
+from .runtime import (
+    OBSERVABILITY_INTERNAL_DISPATCH_HEADER,
+    REQUEST_ID_HEADER,
+    TRACEPARENT_HEADER,
+    ObservabilityRuntime,
+    observability_runtime,
+    set_observability_runtime,
+)
+from .segments import UNKNOWN_SEGMENT, coerce_segment_name
+
+
+def current_context() -> RequestObservabilityContext | None:
+    return observability_runtime().current_context()
+
+
+def current_operation() -> OperationObservabilityContext | None:
+    return observability_runtime().current_operation()
+
+
+def set_attribute(key: str, value: Any) -> None:
+    observability_runtime().set_attribute(key, value)
+
+
+def record_error(
+    exc: BaseException,
+    *,
+    handled: bool,
+    status_code: int | None = None,
+    include_stack: bool = True,
+) -> None:
+    observability_runtime().record_error(
+        exc,
+        handled=handled,
+        status_code=status_code,
+        include_stack=include_stack,
+    )
+
+
+def record_event(event: str, **fields: Any) -> None:
+    observability_runtime().record_event(event, **fields)
+
+
+def traceparent_header() -> str | None:
+    return observability_runtime().traceparent_header()
+
+
+def capture_context():
+    return observability_runtime().capture_context()
+
+
+def mark(key: str, ms: float) -> None:
+    observability_runtime().mark(key, ms)
+
+
+def mark_ttft(key: str = "ttft_ms") -> None:
+    observability_runtime().mark_ttft(key)
+
+
+def start_scope(
+    timings: dict[str, float],
+    *,
+    name: str = "operation",
+    parent_context: Any = None,
+    **attrs: Any,
+):
+    return observability_runtime().start_scope(
+        timings,
+        name=name,
+        parent_context=parent_context,
+        **attrs,
+    )
+
+
+def annotate(handle=None, **attrs: Any) -> None:
+    observability_runtime().annotate(handle, **attrs)
+
+
+def end_scope(handle, error: BaseException | None = None) -> None:
+    observability_runtime().end_scope(handle, error)
+
+
+def instrument_fastapi(app: Any) -> None:
+    observability_runtime().instrument_fastapi(app)
+
+
+def instrument_httpx() -> None:
+    observability_runtime().instrument_httpx()
+
+
+def shutdown_observability() -> None:
+    observability_runtime().shutdown()
+
+
+def shutdown_tracing() -> None:
+    shutdown_observability()
+
+
+def operation(name: str, *, flavor: str | None = None, **attrs: Any):
+    return observability_runtime().operation(name, flavor=flavor, **attrs)
+
+
+def entrypoint(
+    name: str | None = None,
+    *,
+    flavor: str | None = None,
+    **attrs: Any,
+):
+    return observability_runtime().entrypoint(
+        name,
+        flavor=flavor,
+        **attrs,
+    )
+
+
+def segment(name: Any, **attrs: Any):
+    return observability_runtime().segment(name, **attrs)
+
+
+def asegment(name: Any, **attrs: Any):
+    return observability_runtime().asegment(name, **attrs)
+
+
+def collect_timings(name: str = "operation", **attrs: Any):
+    return observability_runtime().collect_timings(name, **attrs)
+
+
+__all__ = [
+    "OBSERVABILITY_INTERNAL_DISPATCH_HEADER",
+    "REQUEST_ID_HEADER",
+    "TRACEPARENT_HEADER",
+    "UNKNOWN_SEGMENT",
+    "OperationObservabilityContext",
+    "ObservabilityConfig",
+    "ObservabilityRuntime",
+    "RequestObservabilityContext",
+    "annotate",
+    "asegment",
+    "capture_context",
+    "coerce_segment_name",
+    "collect_timings",
+    "current_context",
+    "current_operation",
+    "end_scope",
+    "entrypoint",
+    "instrument_fastapi",
+    "instrument_httpx",
+    "mark",
+    "mark_ttft",
+    "observability_runtime",
+    "operation",
+    "record_error",
+    "record_event",
+    "segment",
+    "set_attribute",
+    "set_observability_runtime",
+    "shutdown_observability",
+    "shutdown_tracing",
+    "start_scope",
+    "traceparent_header",
+]

policyengine_observability-0.2.0/policyengine_observability/adapters/__init__.py

@@ -0,0 +1 @@
+"""Framework adapters for policyengine-observability."""