ocx-sdk

Typed Python handles over ocx — the OCI-registry-backed binary package manager. Bootstrap ocx anywhere Python runs, drive its toolchains, author and publish packages against it — all through methods that mirror ocx's own commands one for one, wrapping the CLI rather than reimplementing it.

# illustrative: /srv/build stands in for a real project directory, and
# bootstrap.ensure() needs network access — swap in your own path to run
# this for real, or follow the tutorial linked below.
from ocx_sdk import Ocx, bootstrap

ocx = Ocx(exe=bootstrap.ensure())    # download, verify, cache a pinned binary
project = ocx.project("/srv/build")  # /srv/build holds ocx.toml
project.pull()                       # materialize the declared toolchain
result = project.exec(["task", "verify"])

📖 Docs: https://ocx.sh/integrations/python/ — start with Run your first pinned tool.

Install

Requires Python 3.12+.

uv add ocx-sdk

Why

• Zero runtime dependencies. Stdlib only — nothing else lands in your environment.
• Fully typed. py.typed ships in the wheel; every public method's signature and result are pinned, checked, and covered.
• 100% test coverage, use-case first — coverage is a floor here, not a headline.
• A wrapper, not a reimplementation. ocx owns identifier resolution and checksum verification; the SDK carries identifiers byte-for-byte and parses only what ocx already validated.

Where to go next

• Run your first pinned tool — a five-minute tutorial.
• Reproduce a toolchain in CI — pin ocx, pull the lock, fail on drift.
• Test against a pinned tool in pytest.
• Bootstrap — pinning, corporate mirrors, hardened environments.
• API reference — every public symbol.
• Changelog.

Development

This repo dogfoods OCX. Install OCX once, then run everything through it:

curl -sSL https://setup.ocx.sh | sh
ocx exec -- task verify      # format check + lint + types + tests + coverage
ocx exec -- task docs:serve  # live-preview the docs site at localhost:4321

OCX bootstraps task, uv, node, pnpm and git-cliff; uv pulls ruff + pyright from [project.optional-dependencies] dev, and pnpm builds the docs site. See Contributing for the full guide, including how the doc examples on this page are tested.

Stability

Pre-1.0. Breaking changes ship without migration shims — no deprecation warnings, no compatibility layers. Pin an exact version.

License

Apache-2.0 — see LICENSE.