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

*attribute*

```python
Resolve
```

Re-exported from: `ocx_sdk._client`

Which `$OCX_HOME` symlink a package-tier call resolves through.

`'candidate'` is the installed version's own link, `'current'` the selected
one. Omitting it leaves the choice to ocx, which is the usual answer.

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

## ocx_sdk.PackageRef

*class* · *dataclass*

```python
class PackageRef
```

Re-exported from: `ocx_sdk._types`

A package identifier carried verbatim from ocx, never parsed.

ocx owns the identifier grammar. The SDK stores the string it was given
and hands it back unchanged, so a ref that came out of one result flows
into the next call's argv byte-for-byte.

Identity is the identifier alone. `metadata` is decoration carried along
from whichever JSON row produced the ref, so two refs to the same package
from different commands must not compare unequal. The mapping is copied
and made read-only at construction (and is therefore not picklable).

> **Example**
>
> >>> ref = PackageRef("ocx.sh/astral-sh/uv:0.9.7")
> >>> str(ref)
> 'ocx.sh/astral-sh/uv:0.9.7'

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

### ocx_sdk.PackageRef.identifier

*attribute* · *instance attribute*

```python
identifier: str
```

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

### ocx_sdk.PackageRef.metadata

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

```python
metadata: Mapping[str, object] = _NO_METADATA
```

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

## ocx_sdk.PathVar

*class* · *dataclass*

```python
class PathVar
```

Re-exported from: `ocx_sdk._types`

An `[env]` value prepended to a PATH-like variable, deduplicated.

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

### ocx_sdk.PathVar.value

*attribute* · *instance attribute*

```python
value: str
```

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