Skip to main content

Python SDK Example

This example is useful when your repo is a library instead of a standalone service and the hardest part of the context is behavioral compatibility. It shows how the integrations model can describe a package that is consumed elsewhere, where parity expectations, wire protocol details, and interop checks matter as much as the module layout.

Why this profile is a good starting point​

  • It treats the repo as an SDK with downstream consumers, not as an isolated application.
  • It makes Go/Python parity expectations explicit, which is the kind of hidden constraint that often gets lost in thin repo summaries.
  • It shows how to encode protocol-sensitive docs and verification paths without bloating the example with unrelated service runtime detail.

Profile at a glance​

  • Repo: triggers-sdk-python
  • Repo path: {profile.facts.repo.path}
  • Repo kind: {profile.facts.repo.kind}
  • Language: {profile.facts.repo.language}
  • Draft status: {profile.facts.meta.draftStatus}
  • Summary: Python SDK for the Triggers orchestrator with explicit Go parity expectations.

Provenance​

  • Source repo path: {profile.provenance.sourceRepoPath}
  • Snapshot date: {profile.provenance.snapshotDate}
  • Owner or steward: {profile.provenance.ownerOrSteward}
  • Provenance note: Derived from the repo README, pyproject metadata, Makefile targets, and docs present in the repo snapshot.

What the facts emphasize​

Library entry points and package surface​

The entry points focus on package roots, tests, and examples rather than process supervisors or binary commands:

- triggers/__init__.py
- pyproject.toml
- triggers
- tests
- examples
- Library package consumed by service repos

Commands and parity-sensitive verification​

The command set is intentionally library-shaped:

  • Setup: {profile.facts.commands.setup.join(" | ")}
  • Dev: {profile.facts.commands.dev.join(" | ")}
  • Test: {profile.facts.commands.test.join(" | ")}
  • Build: {profile.facts.commands.build.join(" | ")}

The most important guidance is not just "run tests." It is "protect compatibility":

- Run unit, golden, and parity-sensitive checks.
- Pause before introducing Go/Python parity drift.

Integration surface and must-read docs​

The integrationSurface block describes a repo whose outputs are runtime behavior and interop guarantees:

  • Inputs: Trigger manifests, message bus events, service callbacks
  • Outputs: Python runtime behavior, interop fixtures, wire-compatible services
  • Dependencies: Python 3.11+, NATS, optional Kafka and Redis extras

The source docs list is part of the example, not filler:

- Doc: docs/architecture.md (Architecture)
- Doc: docs/wire-protocol.md (Wire protocol)
- Runbook: docs/SPEC-go-parity-verification.md (Go parity verification)

Generated artifact preview​

This preview uses the shared example renderer rather than a bespoke SDK-specific template. That is the main lesson of the page: once the facts and provenance are captured accurately, the same renderer path can produce an artifact pack that still reflects SDK-specific constraints.

triggers-sdk-python example artifacts

Generated from the shared renderer path for momentum-online/triggers-sdk-python.

Canonical repo facts

REPO_FACTS.json

json via generic-v1

{
  "meta": {
    "schemaVersion": "1",
    "artifactVersion": "1",
    "generatorVersion": "integrations-v1",
    "draftStatus": "draft",
    "unknowns": [
      "ownerOrSteward: unknown (not explicitly stated in repo docs)",
      "ownership ownerOrSteward is unknown",
      "lifecycle.lastReviewed"
    ]
  },
  "repo": {
    "key": "triggers-sdk-python",
    "name": "triggers-sdk-python",
    "path": "momentum-online/triggers-sdk-python",
    "language": "python",
    "kind": "sdk",
    "summary": "Python SDK for the Triggers orchestrator with explicit Go parity expectations."
  },
  "entryPoints": {
    "files": [
      "triggers/__init__.py",
      "pyproject.toml"
    ],
    "directories": [
      "triggers",
      "tests",
      "examples"
    ],
    "runtime": [
      "Library package consumed by service repos"
    ]
  },
  "commands": {
    "setup": [
      "make setup"
    ],
    "dev": [
      "source .venv/bin/activate"
    ],
    "test": [
      "make test",
      "make test-interop"
    ],
    "build": [
      "python -m build"
    ]
  },
  "integrationSurface": {
    "inputs": [
      "Trigger manifests",
      "message bus events",
      "service callbacks"
    ],
    "outputs": [
      "Python runtime behavior",
      "interop fixtures",
      "wire-compatible services"
    ],
    "dependencies": [
      "Python 3.11+",
      "NATS",
      "optional Kafka and Redis extras"
    ]
  },
  "sourceDocs": {
    "docs": [
      {
        "title": "Architecture",
        "path": "docs/architecture.md"
      },
      {
        "title": "Wire protocol",
        "path": "docs/wire-protocol.md"
      }
    ],
    "runbooks": [
      {
        "title": "Go parity verification",
        "path": "docs/SPEC-go-parity-verification.md"
      }
    ]
  },
  "lifecycle": {
    "stage": "pre-release",
    "ownerOrSteward": "unknown",
    "lastReviewed": "unknown"
  },
  "ownership": {
    "stopAndAsk": [
      "Before changing public SDK behavior or wire compatibility."
    ],
    "verification": [
      "Run unit, golden, and parity-sensitive checks."
    ],
    "riskyAreas": [
      "Wire protocol, parity with Go, and runtime coercion paths."
    ],
    "safeEditZones": [
      "Docs and additive examples."
    ]
  },
  "agentBehavior": {
    "stopAndAsk": [
      "Pause before introducing Go/Python parity drift."
    ],
    "verification": [
      "Verify with repo checks and wire-focused tests."
    ],
    "riskyAreas": [
      "Protocol, manifest, and runtime compatibility boundaries."
    ],
    "safeEditZones": [
      "Docs, examples, and clearly isolated helpers."
    ]
  }
}