Metadata-Version: 2.5
Name: cordra-client
Version: 0.3.0
Summary: Lean Python client for Cordra REST and DoIP APIs
Project-URL: Homepage, https://github.com/KIKIRPA/cordra-client
Project-URL: Documentation, https://github.com/KIKIRPA/cordra-client/blob/main/DOCUMENTATION.md
Project-URL: Repository, https://github.com/KIKIRPA/cordra-client
Project-URL: Issues, https://github.com/KIKIRPA/cordra-client/issues
Project-URL: Changelog, https://github.com/KIKIRPA/cordra-client/blob/main/CHANGELOG.md
Author: Royal Institute for Cultural Heritage (KIKIRPA)
License-Expression: MIT
License-File: LICENSE
Keywords: client,cordra,digital-objects,doip,rest
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.12
Requires-Dist: requests
Requires-Dist: requests-toolbelt
Provides-Extra: doip
Requires-Dist: cnri-doip-client; extra == 'doip'
Description-Content-Type: text/markdown

# cordra-client

Lean Python client for the [Cordra](https://www.cordra.org/) APIs.

**Distribution name:** `cordra-client` · **Import name:** `cordra_client` ·
**Python:** ≥ 3.12 · **License:** [MIT](LICENSE)

## Purpose and goals

- Talk to Cordra over **REST** (legacy HTTP API) or **DoIP** (native TCP or
  DoIP-over-HTTP) behind one `protocol=` switch.
- Expose a **single Digital Object (DoIP) shape** to callers so application
  code can flip transports without rewriting field access.
- Stay **close to the wire**: no harvest logic, settings loaders, or other
  application helpers—only thin peelers (`full`, `Payload`).
- Keep the public surface small:

  ```python
  from cordra_client import Cordra, Payload, CordraError
  ```

Full API reference (every method, inputs/outputs, REST↔DoIP mapping, examples):
**[DOCUMENTATION.md](DOCUMENTATION.md)**.

## Install

From [PyPI](https://pypi.org/project/cordra-client/) (preferred). Pin a version,
not a branch:

```bash
pip install "cordra-client[doip]==0.3.0"
```

Omit `[doip]` for REST-only (`pip install cordra-client==0.3.0`).

### As a git dependency (alternative)

```text
cordra-client[doip] @ git+https://github.com/KIKIRPA/cordra-client.git@v0.3.0
```

SSH equivalent: `git+ssh://git@github.com/KIKIRPA/cordra-client.git@v0.3.0`.

### With uv (this repository / editable)

[uv](https://docs.astral.sh/uv/) is recommended:

```bash
uv sync --all-extras
```

That creates `.venv/` if needed and installs the project editable with the
`doip` extra (`cnri_doip_client`). Run tools via `uv run …`.

REST-only:

```bash
uv sync
```

### With venv + pip

```bash
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[doip]"    # or: pip install -e .
```

### requirements.txt style

```text
cordra-client[doip]==0.3.0
```

Or, for a local checkout:

```text
-e .[doip]
```

Runtime dependencies (also declared in `pyproject.toml`): `requests`,
`requests-toolbelt`; optional `cnri_doip_client` for DoIP.

## Quick check

```bash
uv run python -c "from cordra_client import Cordra, Payload, CordraError"
```

Minimal usage (see [DOCUMENTATION.md](DOCUMENTATION.md) for the full contract):

```python
from cordra_client import Cordra

with Cordra(
    url="https://cordra.example:8443",
    username="admin",
    password="…",
    verify=False,
    protocol="rest",  # or "doip" (+ doip_port / doip_base_uri)
) as client:
    obj = client.create({"name": "example"}, "MyType", full=True)
    # obj["id"], obj["attributes"]["content"]
```

## Tests

### Offline unit tests (no Cordra)

Digital Object shape helpers:

```bash
uv run python -m unittest tests.test_shapes
```

### Smoke tests (live Cordra)

[`tests/smoke_cordra_client.py`](tests/smoke_cordra_client.py) registers a
temporary `LibSmokeTests` type, exercises CRUD/payload/auth flows on the
selected transports, asserts the Digital Object shape, then cleans up.

Defaults: `127.0.0.1` (HTTPS `8443`, DoIP `9000`), user `admin`. Pass `--host`
(and ports) to point at another Cordra.

```bash
# interactive (prompts for password)
uv run tests/smoke_cordra_client.py

# non-interactive
uv run tests/smoke_cordra_client.py --password "$CORDRA_PASSWORD"

# subset of modes
uv run tests/smoke_cordra_client.py \
  --password "$CORDRA_PASSWORD" \
  --modes rest-password,doip-password
```

Modes: `rest-password`, `rest-token`, `doip-password`, `doip-token`,
`doip-http-password`, `doip-http-token`. Use `--help` for host/port/TLS flags.

## Releases

1. Bump `version` in `pyproject.toml`
2. Update `CHANGELOG.md`
3. Commit and tag `vX.Y.Z`, then push the tag
4. GitHub Actions runs tests, builds the sdist/wheel, and publishes to PyPI
   (trusted publishing, environment `pypi`)

One-time PyPI setup (before the first tag): create a **Trusted Publisher** for
project `cordra-client`, owner `KIKIRPA`, repository `cordra-client`, workflow
`publish.yml`, environment `pypi`. Do not upload with a password or API token.
