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

*attribute* · *instance attribute*

```python
blobs: BlobSummary
```

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

### ocx_sdk.CopyReport.cascade_tags_written

*attribute* · *instance attribute*

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

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

### ocx_sdk.CopyReport.description

*attribute* · *instance attribute*

```python
description: str | None
```

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

### ocx_sdk.CopyReport.keep_tags_written

*attribute* · *instance attribute*

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

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

### ocx_sdk.CopyReport.platforms

*attribute* · *instance attribute*

```python
platforms: tuple[CopiedPlatformRow, ...]
```

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

### ocx_sdk.CopyReport.referrers_copied

*attribute* · *instance attribute*

```python
referrers_copied: int
```

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