cordra-client

Lean Python client for the Cordra APIs.

Distribution name: cordra-client · Import name: cordra_client · Python: ≥ 3.12 · License: MIT

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:

  from cordra_client import Cordra, Payload, CordraError
  

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

Install

From PyPI (preferred). Pin a version, not a branch:

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)

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 is recommended:

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:

uv sync

With venv + pip

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

requirements.txt style

cordra-client[doip]==0.3.0

Or, for a local checkout:

-e .[doip]

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

Quick check

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

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

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:

uv run python -m unittest tests.test_shapes

Smoke tests (live Cordra)

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.

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