ocx-mirror-sdk

Python SDK for authoring ocx-mirror generator scripts.

ocx-mirror is OCX's tool for ingesting upstream tool releases (e.g. CPython, Bun, shellcheck) and republishing them as OCI artifacts. When upstream releases live somewhere ocx-mirror cannot crawl directly, a small Python generator emits a url_index JSON document. This SDK provides the typed building blocks for those generators.

📖 Full documentation: https://docs.ocx.sh/sdk/mirror/

Install

Published on PyPI. In a PEP 723 inline-metadata script (recommended for one-file generators):

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.13"
# dependencies = ["ocx-mirror-sdk~=0.6.0"]
# ///

from ocx_mirror_sdk import IndexBuilder, github

Or in a project:

uv add ocx-mirror-sdk

Pre-1.0, minor releases may break — ~= pins the patch series. Git-tag and wheel-asset installs remain available; see the install guide.

Quickstart

from ocx_mirror_sdk import IndexBuilder, github

# Fetch releases (REST default; switch to GraphQL on big repos)
releases = github.list_releases("shellcheck/shellcheck")

# Or explicitly:
releases = github.list_releases("indygreg/python-build-standalone", backend=github.Backend.GRAPHQL)

# Build a url_index document
builder = IndexBuilder()
for r in releases:
    if r.prerelease or r.draft:
        continue
    builder.add_version(
        r.tag_name.lstrip("v"),
        assets={a.name: a.browser_download_url for a in r.assets},
    )
builder.emit()  # writes JSON to stdout

Releases hosted on GitLab use the sibling gitlab namespace — same Release objects, same IndexBuilder:

from ocx_mirror_sdk import gitlab

# gitlab.com (default); pass host="https://gitlab.example.com" for self-hosted
releases = gitlab.list_releases("gitlab-org/gitlab-runner")

More worked examples live under examples/ and at https://docs.ocx.sh/sdk/mirror/recipes/.

Public API

Error hierarchy

Catch OcxMirrorError to recover from any SDK failure, or pick a subclass:

Original lower-layer exceptions are preserved on __cause__.

Schema

The url_index format is owned by the ocx-mirror Rust binary. Its JSON Schema is published at https://ocx.sh/schemas/url-index/v1.json. This SDK ships a generated _schema.py (under src/ocx_mirror_sdk/) regenerated via task codegen.

Development

This repo dogfoods OCX. Install OCX once:

curl -sSL https://setup.ocx.sh | sh

Then everything runs through ocx run:

ocx run -- task verify     # format + lint + types + tests
ocx run -- task test
ocx run -- task codegen    # regenerate _schema.py from the published schema
ocx run -- task docs:serve # live-preview the docs site at localhost:8000

OCX bootstraps task and uv; uv pulls Python linters (ruff, pyright) from [project.optional-dependencies] dev, and docs tooling from [project.optional-dependencies] docs.

Stability

Pre-1.0. Breaking changes ship without migration shims. When the upstream url_index schema bumps to /v2.json, this SDK ships a new major version.

Coverage

task verify enforces ≥80% line + branch coverage on src/ocx_mirror_sdk (generated _schema.py excluded). Run task cov:html and open htmlcov/index.html to inspect uncovered lines locally. The threshold lives in [tool.coverage.report] fail_under in pyproject.toml.

License

Apache-2.0 — see LICENSE.