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:

Every write takes dry_run, which the instance validates and stores nothing for. It defaults to off, as DHIS2's own flag does, and every example that writes turns it on.

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

The tutorial's pictures are taken from a throwaway dg dev with the pack installed. catalog is the Blocks and Examples screens and needs no DHIS2; walk runs the tutorial's own documents against the public play demo, reads and dry runs only. Both when neither is named:

uv run --with dirigent-cli --with playwright python scripts/docs_shots.py [catalog|walk]

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 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. No document carries a credential: each names the connection it uses under requires.connections, and the instance holds it. The native and composed shelves name the dhis2 connection dhis2-play, and the generic-HTTP and validation shelves the http connection dhis2-play-http. Create them once against the public play demo; dg connection create asks how to sign in, and the demo takes the login it publishes on its own sign-in page:

dg connection create dhis2 dhis2-play --set base_url=https://play.dhis2.org/2.43 --set timeout=2m
dg connection create http dhis2-play-http --set base_url=https://play.dhis2.org/2.43 \
    --set follow_redirects_with_auth=true --set timeout=2m
dg run examples/dhis2/dhis2-system-report.yaml

The seven documents tagged starter are the flows dg pipeline new copies into a project.

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.