Metadata-Version: 2.4
Name: c-two
Version: 0.4.9
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX
Classifier: Operating System :: MacOS
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Distributed Computing
License-File: LICENSE
Summary: C-Two is a resource-RPC framework that enables resource-oriented classes to be remotely invoked across different processes or machines.
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# C-Two Python SDK

This directory contains the Python package for C-Two.

## Development

Run development commands from the repository root.

Prerequisites:

- Python 3.10 or newer
- Python 3.12 for standard local development
- Python 3.14.3t when testing free-threading support
- Rust toolchain
- `uv`

Install dependencies and build the Python native extension. This also compiles
the required Rust core crates; no separate Rust prebuild step is needed:

```bash
uv sync
```

Rebuild the native extension after changing Rust code:

```bash
uv sync --reinstall-package c-two
```

Relay-dependent tests and examples require the standalone `c3` binary. From a
source checkout, build and link it before running relay flows:

```bash
python tools/dev/c3_tool.py --build --link
```

The Python SDK does not embed or start a relay server. Start the standalone
Rust relay with `c3 relay`, Docker Compose, or orchestration such as
Kubernetes, then point Python code at its relay anchor with
`C2_RELAY_ANCHOR_ADDRESS` or `cc.set_relay_anchor()`. The anchor is used for
registration and name resolution. Remote HTTP calls still use the resolved
route's `relay_url` directly, and local direct IPC is selected only for a
loopback/local anchor.
Relay-aware clients preflight routes before the first call and re-resolve
structured stale-route responses; set `C2_RELAY_ROUTE_MAX_ATTEMPTS` to tune the
maximum route acquisition attempts (default `3`, valid range `1..=32`, `0` is
treated as `1`). Ambiguous data-plane failures are not replayed.

Run the Python SDK tests:

```bash
C2_RELAY_ANCHOR_ADDRESS= uv run pytest sdk/python/tests -q --timeout=30
```

Run Rust core checks when validating shared native runtime changes:

```bash
cargo test --manifest-path core/Cargo.toml --workspace
```

For CLI build, link, and test commands, see [`../../cli/README.md`](../../cli/README.md).

## Examples

Python examples live under `../../examples/python/`:

```bash
uv sync --group examples
uv run python examples/python/local.py
```

Relay examples also need a running standalone relay, for example:

```bash
python tools/dev/c3_tool.py --build --link
c3 relay --bind 127.0.0.1:8080
```

## Benchmarks

Python-specific benchmarks live in `benchmarks/`:

```bash
C2_RELAY_ANCHOR_ADDRESS= uv run python sdk/python/benchmarks/segment_size_benchmark.py
```

