# ocx_sdk

*module*

Python SDK for [OCX](https://github.com/ocx-sh/ocx).

`ocx-sdk` drives the ocx binary rather than reimplementing it: ocx owns
resolution, verification, and the identifier grammar, and this package gives
you typed, CWD-independent handles over the commands it exposes.

```python
from ocx_sdk import Ocx, bootstrap

ocx = Ocx(exe=bootstrap.ensure())
project = ocx.project("/srv/build")
project.pull()
project.exec(["task", "verify"])
```

**This module is the API.** Everything listed in `__all__` is the stable
surface; every other module is underscored and package-private, and the one
public submodule is `ocx_sdk.bootstrap`. Reaching into an underscored path
means the next release may move it without notice — pre-1.0, breaking
changes ship without shims.

Start at `Ocx` for the runtime API and `bootstrap.ensure` for provisioning.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/__init__.py#L1-L1)

## ocx_sdk.SignatureFormat

*attribute*

```python
SignatureFormat
```

Re-exported from: `ocx_sdk._types`

ocx `--signature-format` values. A `Literal` because nothing but argv consumes it.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_types.py#L42-L42)

## ocx_sdk.TESTED_OCX_VERSION

*attribute* · *module attribute*

```python
TESTED_OCX_VERSION: Final = '0.6.2'
```

Re-exported from: `ocx_sdk._types`

The ocx version this SDK's contract tests run against.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_types.py#L30-L30)

## ocx_sdk.Transport

*attribute*

```python
Transport
```

Re-exported from: `ocx_sdk._client`

ocx `--transport` values — how a forge write is made. `git` is GitLab-only.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_client.py#L163-L163)

## ocx_sdk.UNSET

*attribute* · *module attribute*

```python
UNSET: Final = _Unset.TOKEN
```

Re-exported from: `ocx_sdk._client`

The default for every per-call `retry=`/`timeout=`, meaning "not given".

Public so that a wrapper around this SDK can pass a caller's override
straight through without having to invent its own three-state sentinel:
`def deploy(*, retry: MaybeRetry = UNSET): ocx.package.push(..., retry=retry)`.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_client.py#L186-L186)

## ocx_sdk.ensure

*function*

```python
def ensure(version: str | None = None, *, channel: Channel = Channel.STABLE, dist: _dist.DistSource | None = None, mirror_url: str | None = None, ca_bundle: str | None = None, min_version: str | None = None, cache_dir: Path | None = None, env: HostEnv | None = None, trust_cache: bool = False, retry: RetryPolicy | None = None, timeout: float | None = None) -> Path
```

Re-exported from: `ocx_sdk._bootstrap`

Provision a verified ocx binary and return its path.

Idempotent and offline-friendly: a cache hit that still hashes correctly
needs no network at all. Every knob resolves explicit argument first, then
the matching `OCX_INSTALL_*` variable from `env`, then the default.

**Parameters**

- `version` (`str | None`) (default: `None`) — Exact version to install. `None` takes the channel's latest, then `OCX_INSTALL_VERSION`.
- `channel` (`Channel`) (default: `Channel.STABLE`) — Channel consulted when `version` is `None`. No variable — the setup script has none either.
- `dist` (`_dist.DistSource | None`) (default: `None`) — Where the manifest comes from. `None` builds the default source, which honors `OCX_INSTALL_DIST_URL`; an explicitly constructed source does not.
- `mirror_url` (`str | None`) (default: `None`) — Base URL that replaces the artifact host, as `<mirror_url>/<tag>/<filename>`, falling back to `OCX_INSTALL_MIRROR_URL`. The manifest digest is still enforced — a mirror relocates bytes, it never revalidates them.
- `ca_bundle` (`str | None`) (default: `None`) — PEM file trusted for every download, replacing the system trust store, falling back to `OCX_INSTALL_CA_BUNDLE`. For a TLS-intercepting proxy; the digest checks are unaffected.
- `min_version` (`str | None`) (default: `None`) — Operator floor. A resolved version below it fails loudly instead of installing something older than the caller allows.
- `cache_dir` (`Path | None`) (default: `None`) — Cache root. `None` uses the per-user cache directory.
- `env` (`HostEnv | None`) (default: `None`) — Environment snapshot. `None` reads the ambient one.
- `trust_cache` (`bool`) (default: `False`) — Skip the digest re-check on a cache hit. Orthogonal to `OCX_INSTALL_FORCE`, which reinstalls even on a cache hit and has no argument of its own.
- `retry` (`RetryPolicy | None`) (default: `None`) — Policy for transient transport failures; `None` tries once.
- `timeout` (`float | None`) (default: `None`) — Per-attempt network budget in seconds.

**Returns**

- (`Path`) — Path to the installed binary, mode `0o700`.

**Raises**

- `BootstrapError` — The cache root is untrusted, or the resolved version is
below `min_version`.
- `DistManifestError` — The manifest is unusable, or its archive is.
- `UnsupportedPlatformError` — No release matches this platform.
- `ChecksumMismatchError` — Downloaded bytes do not match the manifest.
Never retried — the bytes are wrong, not late.
- `DownloadError` — The manifest or artifact could not be fetched, or the
CA bundle could not be loaded.

[View source](https://github.com/ocx-sh/ocx-sdk-python/blob/main/src/ocx_sdk/_bootstrap.py#L147-L242)