platform-pkg

Shared Python infrastructure for platform services. Infrastructure only: no service business logic, domain models, or generated protobuf code.

Package: platform-pkg; import namespace: platform_pkg. Symbols exported from platform_pkg form the stable transport-neutral API; integration modules remain feature-specific and may evolve between minor releases.

Included

• Pydantic environment settings matching go-pkg variable conventions
• structlog JSON/console logging
• async SQLAlchemy/PostgreSQL transaction manager, Alembic runner, probes, and isolated test schemas
• Redis, NATS, and S3 client construction
• gRPC health, reflection, error mapping, and graceful serving
• FastAPI app factory with health probes, error mapping, request IDs, and graceful serving
• private telemetry listener with liveness, readiness probes, and Prometheus metrics
• OpenTelemetry OTLP tracing and FastAPI instrumentation
• Redis-backed idempotency orchestration and gRPC interceptor
• PostgreSQL transactional outbox and NATS JetStream relay
• bounded retries, timeouts, dependency probes, and component shutdown
• outbox failure replay, retention cleanup, and relay metrics
• asyncio component lifecycle and periodic worker loops
• request metadata and test-flag propagation across HTTP, gRPC, and NATS
• outbound HTTP and gRPC clients with metadata and bounded HTTP retries
• SMTP, Kubernetes (optional), and Vault (optional) clients
• offset/cursor pagination, app build metadata, and S3 bucket helpers
• HTTP and gRPC idempotency integrations
• isolated PostgreSQL and Docker Compose integration-test helpers
• pytest, Ruff, mypy, uv, devenv, and Docker Compose infrastructure

Package map

• platform_pkg.client: technology-specific client construction
• platform_pkg.transport.http: HTTP client, server, and idempotency middleware
• platform_pkg.transport.grpc: gRPC client, server, and idempotency interceptors
• platform_pkg.idempotency: transport-neutral orchestration and Redis adapter
• platform_pkg.outbox: PostgreSQL outbox, NATS publisher, schema, and metrics
• platform_pkg.observability: tracing and metrics
• platform_pkg.runtime: signal-aware lifecycle, telemetry, workers, migrations, and integration-test helpers
• top-level modules: small transport-neutral APIs such as config, errors, metadata, pagination, resilience, and logging

Development

uv sync
uv run pytest
uv run ruff check .
uv run mypy
uv build --no-sources
uvx twine check dist/*
uvx check-wheel-contents dist/*.whl

Inside devenv, run help for project commands. test-integration starts PostgreSQL, Redis, NATS, and MinIO. See docs/http.md for HTTP and metrics setup, docs/resilience.md for retry, shutdown, and outbox operations, docs/postgres.md for database conventions, docs/outbox.md for reliable event delivery, and docs/idempotency.md for duplicate command handling.

Reusable devenv profiles

Python microservices can reuse shared environment variables and commands through the remote microservice profile:

inputs:
  py-pkg:
    url: git+ssh://forgejo@ssh.hayshin.dev/platform/py-pkg.git?ref=main
    flake: false

imports:
  - py-pkg/devenv/microservice.nix

Profiles under devenv/ have distinct roles:

• base.nix: Python toolchain, infrastructure variables, common checks, and hooks
• package.nix: package-development profile used by this repository
• microservice.nix: service variables plus protobuf SDK, migration, and run commands

SDK-enabled services set PROTO_PYTHON_SOURCE_PACKAGE, PROTO_PYTHON_IMPORT_PACKAGE, PROTO_PYTHON_OUTPUT, and PROTO_GENERATED_PATHS. Shared commands generate Python and Go bindings, lint Buf contracts, detect drift, and validate nested SDK packages without copying shell scripts into each service.

Service repositories should only override identity or exceptional project-specific values in their local devenv.nix. The base profile exports PY_PKG_DOCKER_COMPOSE, allowing service Compose files to extend PostgreSQL, Redis, NATS, and MinIO definitions from this repository.

Service dependency

[project]
dependencies = ["platform-pkg"]

[tool.uv.sources]
platform-pkg = { git = "ssh://forgejo@ssh.hayshin.dev/platform/py-pkg.git", tag = "v0.1.0" }

Prefer tagged releases. Keep service-specific settings in a subclass of platform_pkg.config.Settings. Install only required integrations through grpc, http, kubernetes, nats, observability, postgres, redis, s3, and vault extras. Development and full-stack services can use platform-pkg[all].

Releases

Package versions derive from Git tags through Hatch VCS. Squash-merged PR titles must use Conventional Commits. After each push to main, Forgejo Actions examines squash commits since the latest release and creates the next stable semantic-version tag automatically:

• fix: and perf: increment patch version
• feat: increments minor version
• type!: or a BREAKING CHANGE: footer increments major version
• other commit types do not create a release

The version workflow never writes to protected main; it tags the merged commit, builds and validates distributions, confirms wheel version matches the tag, and creates a Forgejo release containing the wheel and source archive. Forgejo suppresses recursive workflow events created by its automatic token, so these release steps run in the same workflow. Consumers install directly from the tagged Git repository; no package registry or publishing credential is required. Restrict v* tag creation to the Forgejo Actions identity.

CI validates the lockfile, formatting, linting, types, tests, distribution metadata, and wheel contents. Lower dependency bounds state the oldest supported versions; upper bounds are added only for known incompatibilities.

Status

Initial broad infrastructure baseline. Client factories, transport-neutral ports, HTTP serving, and operational metrics are stable starting points.