development.md

Development guide

Set up the environment

The project uses pyproject.toml, uv.lock, and Python 3.13 or newer. From the repository root, create or refresh the environment only when .venv is missing or stale:

uv sync --locked

Run tools directly from the project environment:

.venv/bin/definedcli --help
.venv/bin/pytest

Run tests

Run the complete suite:

.venv/bin/pytest

Run all static checks:

.venv/bin/ruff check .
.venv/bin/ruff format --check .
.venv/bin/pyright

Apply Ruff's safe automatic fixes and formatter while developing:

.venv/bin/ruff check --fix .
.venv/bin/ruff format .

The Quality GitHub Actions workflow runs the same lint, formatting, type, and test checks for every pull request and every push to main.

Run one test module while iterating:

.venv/bin/pytest tests/cli/test_workflows.py

The test suite and static checks do not require a real API key.

Try the local CLI

The virtual environment exposes the current checkout directly:

.venv/bin/definedcli --version
.venv/bin/definedcli hosts create --help

Commands that call authenticated endpoints require DEFINED_API_KEY. The downloads listing can be used without one:

.venv/bin/definedcli downloads list

Repository layout

src/defined_client/
├── client.py       HTTP session, configuration, and error mapping
├── resources.py    Low-level endpoint wrappers
├── services/       Safe updates, lookups, and pagination helpers
└── cli/            Click command groups and output handling
tests/
├── cli/             CLI contract and end-to-end workflow tests
└── client/          HTTP, resource, and service-layer tests
spec/openapi.yaml    Defined Networking OpenAPI description

Reusable CLI fakes and fixtures live beside the CLI tests in tests/cli/.

When adding an endpoint, keep its low-level behavior in a resource object. Add a service method only when the operation composes requests or provides a safer workflow. CLI commands should preserve the standard API envelope in JSON mode, write errors only to stderr, and keep credentials out of diagnostics.

Build the package

uv build

The resulting distributions are written to dist/.