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

*class* · *dataclass*

```python
class ClaimReport
```

Re-exported from: `ocx_sdk._results`

`ocx package claim` — the index entry a claim rendered (C-060).

**Payload is bare** (D11), seventeen keys, every one always on the wire.
A package that is already claimed never produces this: ocx exits 65 with
an error envelope instead, which `error_envelope(err)` recovers.

**Attributes**

- `package` (`str`) — The claimed `<namespace>/<package>`, as given.
- `name` (`str`) — The logical name written into the root.
- `status` (`str`) — `"updated"` or `"unchanged"` — against the open claim branch, not the committed root, so a `--out` run is always `"updated"`.
- `forge` (`str`) — `"github"` or `"gitlab"`.
- `transport` (`str`) — `"api"` or `"git"`.
- `credential_kind` (`str`) — `"job-token"`, `"token"` or `"none"`.
- `push_credential_kind` (`str | None`) — `"job-token"`, `"token"`, `"git-helper"`, or `None` under the `api` transport.
- `author` (`ClaimOwner | None`) — The identity that authored the request, or `None` when neither the token nor the CI environment named one. **Not attested** — see `author_identity_source`.
- `author_identity_source` (`str | None`) — `"resolved"` when the forge's own answer about the credential produced `author`, `"ci-environment"` when an ordinary environment read did; `None` exactly when `author` is.
- `owners` (`tuple[ClaimOwner, ...]`) — The recorded owners, in order.
- `owner_identity_source` (`str`) — `"resolved"`, `"asserted"` or `"ci-environment"`.
- `branch` (`str`) — The claim branch.
- `pull_request_url` (`str | None`) — The request's URL, when one was opened.
- `pull_request_number` (`int | None`) — Its number, likewise.
- `fork` (`str | None`) — The fork the request came from, when `--fork` was given.
- `written_paths` (`tuple[str, ...]`) — Files written under `--out`; empty otherwise.
- `capability_checks` (`tuple[CapabilityCheck, ...]`) — The forge probes, in `CapabilityName` order.

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

### ocx_sdk.ClaimReport.branch

*attribute* · *instance attribute*

```python
branch: str
```

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

### ocx_sdk.ClaimReport.capability_checks

*attribute* · *instance attribute*

```python
capability_checks: tuple[CapabilityCheck, ...]
```

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

### ocx_sdk.ClaimReport.fork

*attribute* · *instance attribute*

```python
fork: str | None
```

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

### ocx_sdk.ClaimReport.name

*attribute* · *instance attribute*

```python
name: str
```

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

### ocx_sdk.ClaimReport.pull_request_number

*attribute* · *instance attribute*

```python
pull_request_number: int | None
```

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

### ocx_sdk.ClaimReport.written_paths

*attribute* · *instance attribute*

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

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