# 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.ExitCode

*class*

```python
class ExitCode(IntEnum)
```

Bases: `IntEnum`

Re-exported from: `ocx_sdk._errors`

Exit codes ocx assigns to error categories (`sysexits.h` plus ocx's own).

`TEMP_FAIL` is the retry signal — ocx maps 429/5xx/network timeouts onto
it, while `UNAVAILABLE` marks a failure that retrying cannot fix.

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

### ocx_sdk.ExitCode.UNAVAILABLE

*attribute* · *class attribute* · *instance attribute*

```python
UNAVAILABLE = 69
```

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

### ocx_sdk.ExitCode.UNSUPPORTED_KEY_BACKEND

*attribute* · *class attribute* · *instance attribute*

```python
UNSUPPORTED_KEY_BACKEND = 85
```

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

### ocx_sdk.ExitCode.USAGE

*attribute* · *class attribute* · *instance attribute*

```python
USAGE = 64
```

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

## ocx_sdk.ForgeCapabilityUnavailableError

*class*

```python
class ForgeCapabilityUnavailableError(OcxProcessError)
```

Bases: `ocx_sdk._errors.OcxProcessError`

Re-exported from: `ocx_sdk._errors`

A forge was reached and refused a write for want of a capability (exit 86).

Raised by `announce`/`claim` under `--transport git` when job-token push
is disabled on the index project or the publishing project is missing
from its allowlist. Distinct from 69 (the forge could not be reached at
all) and from 80 (the credential is valid here — the refusal is not on it).

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

## ocx_sdk.IoError

*class*

```python
class IoError(OcxProcessError)
```

Bases: `ocx_sdk._errors.OcxProcessError`

Re-exported from: `ocx_sdk._errors`

A filesystem or network I/O operation failed (exit 74).

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

## ocx_sdk.NotFoundError

*class*

```python
class NotFoundError(OcxProcessError)
```

Bases: `ocx_sdk._errors.OcxProcessError`

Re-exported from: `ocx_sdk._errors`

A package, registry, or reference does not exist (exit 79).

Covers both things ocx can fail to find: the identifier a call named, and
the project file a `--project` pointed at.

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

## ocx_sdk.OcxError

*class*

```python
class OcxError(Exception)
```

Bases: `Exception`

Re-exported from: `ocx_sdk._errors`

Base class for every error raised by ocx-sdk.

Subclasses set `_hint`: the next step a caller can actually take. It is
appended to the message of every error in the hierarchy.

Errors cross process boundaries intact — a `ProcessPoolExecutor` worker or
a pytest-xdist node has to be able to hand one back.

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