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

*class* · *dataclass*

```python
class CopyReport
```

Re-exported from: `ocx_sdk._results`

`ocx package copy` (C-015).

**Payload is bare** (D11) — `from_json` reads the JSON root directly,
no envelope to unwrap. Non-empty `sidecar_conflicts` means exit 65 and
therefore raises; because the payload is bare, `partial_report(err)`
returns the same document this `from_json` parses, so the conflict list
is readable from the failure itself.

All eleven fields verified always present against `package_copy.rs:97-124`
— no `skip_serializing_if` anywhere on this struct, `description`
included (upstream comment: "serializes as `null`, so the key is always
there to branch on"). No D7 reordering needed: this is upstream's own
field order, verbatim.

**Attributes**

- `source` (`str`) — The identifier that was copied.
- `target` (`str`) — Where it was copied to.
- `status` (`str`) — What happened, e.g. `"copied"`, or `"planned"` under `dry_run=True`.
- `platforms` (`tuple[CopiedPlatformRow, ...]`) — One row per platform manifest carried over.
- `cascade_tags_written` (`tuple[str, ...]`) — Cascading tags updated at the target.
- `keep_tags_written` (`tuple[str, ...]`) — `__ocx.keep.sha256-<hex>` tags written at the target, one per platform manifest.
- `referrers_copied` (`int`) — Referrer-API attachments carried over.
- `sidecars_copied` (`int`) — Sidecar-tag attachments carried over.
- `sidecar_conflicts` (`tuple[str, ...]`) — Sidecar tags that already existed at the target with different content. Non-empty means the call raised.
- `blobs` (`BlobSummary`) — Blob transfer counts.
- `description` (`str | None`) — A `DescriptionOutcome` value — `"copied"`, `"absent"`, or `"skipped-dry-run"` — **not** the description text itself. Always present (`null` when there is nothing to report), not absent-when-unset.

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

### ocx_sdk.CopyReport.sidecar_conflicts

*attribute* · *instance attribute*

```python
sidecar_conflicts: tuple[str, ...]
```

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

### ocx_sdk.CopyReport.sidecars_copied

*attribute* · *instance attribute*

```python
sidecars_copied: int
```

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

### ocx_sdk.CopyReport.source

*attribute* · *instance attribute*

```python
source: str
```

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

### ocx_sdk.CopyReport.status

*attribute* · *instance attribute*

```python
status: str
```

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

### ocx_sdk.CopyReport.target

*attribute* · *instance attribute*

```python
target: str
```

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

### ocx_sdk.CopyReport.from_json

*method* · *classmethod*

```python
def from_json(raw: str) -> CopyReport
```

Parse `ocx --format json package copy` output.

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