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 see the quickstart below for the full explanation.
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.run(["task", "verify"])

📖 Docs: https://ocx-sh.github.io/ocx-sdk-python/ — start at the quickstart.

Install

Not published yet. On the first vX.Y.Z tag, the release pipeline builds and publishes to PyPI — until then the badges below will read "not found":

Requires Python 3.12+.

uv add ocx-sdk

pip install 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

• Quickstart — the canonical CI journey in one worked example.
• 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 run -- task verify      # format check + lint + types + tests + coverage
ocx run -- task docs:serve  # live-preview the docs site at localhost:8000

OCX bootstraps task, uv, and git-cliff; uv pulls ruff + pyright from [project.optional-dependencies] dev and the MkDocs stack from docs. 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.