Skip to content

ocx-mirror-sdk

Pre-1.0 — API may change between minor versions

Breaking changes ship without migration shims. Pin to a tag, watch the release notes.

Python SDK for authoring ocx-mirror generator scripts.

ocx-mirror is OCX's tool for ingesting upstream tool releases 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.

At a glance

  • Getting started

    Install via PEP 723 or [tool.uv.sources], write a 25-line generator, run it locally.

  • Guide

    REST vs GraphQL, caching, error handling, troubleshooting GITHUB_TOKEN and rate limits.

  • Recipes

    Fully runnable examples — shellcheck (REST), python-build-standalone (GraphQL), URL extraction.

  • API reference

    Auto-generated from docstrings. Every public symbol, its signature, parameters, exceptions, and examples.

Public API at a glance

from ocx_mirror_sdk import (
    IndexBuilder, github, extract_urls,
    Asset, Release, FileCache, configure,
    OcxMirrorError, HttpStatusError, ApiResponseError,
)

releases = github.list_releases("shellcheck/shellcheck")
# Or, on a big repo:
releases = github.list_releases("astral-sh/python-build-standalone", backend=github.Backend.GRAPHQL)

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()

See also