dirigent-dhis2

Documentation: https://winterop-com.github.io/dirigent-dhis2/. New to dirigent and DHIS2 together? The tutorial is one read, one schema gate and one rehearsed write against the public play demo, end to end.

The DHIS2 adapter pack for dirigent. It contributes the dhis2 connection kind, three JSON Schema formats (dhis2-uid, dhis2-period and dhis2-code), and the blocks that speak DHIS2's asynchronous jobs, import summaries, completeness registrations, metadata, tracker and analytics reads as first-class steps, rather than composing them out of raw HTTP:

Where a block takes DHIS2's own query terms, either shape does: fields, filter and order each accept one string, spelled as the API spells it -- id,name,valueType, level:eq:2, name:asc -- or a list, which the pack comma-joins or repeats as the resource wants.

Every block classifies its failures the dhis2w-client way: an instance whose version the client does not speak is refused rather than retried, and a transport failure is transient.

An instance discovers the pack by installing it: the dirigent.plugins.v1 entry point in pyproject.toml is the whole registration.

Install

Install the pack into the dirigent image:

uv pip install dirigent-dhis2

or add it to a project:

uv add dirigent-dhis2

or beside a tool-installed dg, or once without installing anything:

uv tool install dirigent-cli --with dirigent-dhis2
uvx --from dirigent-cli --with dirigent-dhis2 dg dev

The command is in dirigent-cli, so uvx always takes --from dirigent-cli. The pack pins its dirigent packages at its own version, so a pinned install names the same release for both.

Develop

uv sync --locked
uv run ruff format --check . && uv run ruff check .
uv run mypy && uv run pyright
uv run pytest
NO_MKDOCS_2_WARNING=1 uv run mkdocs build --strict

That block is what CI runs on every push and pull request. The variable silences Material's notice about MkDocs 2.0. The lock file is committed and CI syncs against it, so a pack build is reproducible; the ecosystem's nightly integration is what proves the pack still composes with every other pack in one catalog.

The tutorial is published as a page and as paper. The PDF is printed from the built site with headless Chromium, lands in site/, and is never committed. The pages workflow prints it on every push to main, from the site it has just built; locally it is both steps:

uv run --with playwright playwright install chromium
uv run --with playwright python scripts/docs_pdf.py

tests/ exercises every block against a mocked DHIS2 instance, and tests/test_examples.py validates the example documents against the pack's own catalog. Every document runs standalone, carrying the connection it uses.

Examples

The shelves are installed with the pack: dirigent_dhis2 contributes them through the examples() hook, so an instance with the pack installed lists them with

dg examples list --plugin dhis2
dg examples list --plugin dhis2 --starter

They live in src/dirigent_dhis2/shelves/, and the root examples/ is a symlink to it so dg run --local examples/... reads from a checkout.

One file per operation, grouped by how it is built:

Each shelf's README lists its files one line each. Every document carries the connection it uses, coded dhis2-demo, so it runs standalone; a server refuses a carried connection, so what an instance applies is a copy that names it instead. The seven documents tagged starter are the flows dg pipeline new makes that copy from, dropping the connections: block and naming dhis2-demo under requires.connections.

Licence

Copyright (c) 2026 Morten Olav Hansen. All rights reserved. See LICENSE.

The source is published for reference only: no licence to use, copy, modify or distribute it is granted, and any use beyond reading requires written permission.