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

*attribute* · *instance attribute*

```python
author: ClaimOwner | None
```

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

### ocx_sdk.ClaimReport.author_identity_source

*attribute* · *instance attribute*

```python
author_identity_source: str | None
```

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

### ocx_sdk.ClaimReport.credential_kind

*attribute* · *instance attribute*

```python
credential_kind: str
```

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

### ocx_sdk.ClaimReport.forge

*attribute* · *instance attribute*

```python
forge: str
```

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

### ocx_sdk.ClaimReport.owner_identity_source

*attribute* · *instance attribute*

```python
owner_identity_source: str
```

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

### ocx_sdk.ClaimReport.owners

*attribute* · *instance attribute*

```python
owners: tuple[ClaimOwner, ...]
```

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

### ocx_sdk.ClaimReport.package

*attribute* · *instance attribute*

```python
package: str
```

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

### ocx_sdk.ClaimReport.pull_request_url

*attribute* · *instance attribute*

```python
pull_request_url: str | None
```

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

### ocx_sdk.ClaimReport.push_credential_kind

*attribute* · *instance attribute*

```python
push_credential_kind: str | None
```

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

### ocx_sdk.ClaimReport.status

*attribute* · *instance attribute*

```python
status: str
```

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

### ocx_sdk.ClaimReport.transport

*attribute* · *instance attribute*

```python
transport: str
```

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

### ocx_sdk.ClaimReport.from_json

*method* · *classmethod*

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

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

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