DHIS2 Utils¶
Python tooling for DHIS2. A uv workspace with an async client library, a Typer CLI, a FastMCP server, a Playwright browser helper, a code generator, and a shared plugin runtime.
Where to start¶
- New to the repo? Skim the Walkthrough, set up a local DHIS2, then pick a guide.
- Writing Python that talks to DHIS2? Read the Python library tutorial. Every block is runnable.
- Using the CLI? Connecting to DHIS2 covers Basic / PAT / OAuth2 setup with profiles.
- Looking for the architecture? Start at Overview, then Typed schemas + Codegen.
- Browsing by symbol? The API reference auto-renders every
dhis2w-clientmodule's docstrings.
Packages¶
| Package | Role | Published |
|---|---|---|
dhis2w-client |
Async DHIS2 API client with pluggable auth and pydantic models | publishable |
dhis2w-core |
Profile discovery, plugin registry, first-party plugins | private |
dhis2w-cli |
Typer console script dhis2 (mounts plugins from dhis2w-core) |
private |
dhis2w-mcp |
FastMCP server dhis2w-mcp (mounts the same plugins) |
private |
dhis2w-browser |
Playwright helpers (PAT creation, future UI automation) | private |
dhis2w-codegen |
Version-aware client generator | private |
Plus infra/, a docker-compose stack for running a local DHIS2 instance with pre-seeded PATs and an OAuth2 client.
Capability matrix¶
243 MCP tools across 13 plugin groups; 16 top-level CLI domains. Every MCP tool accepts an optional profile: str | None kwarg so an agent can target any configured profile per call; every CLI command has a matching MCP tool (and vice versa) sharing one typed service call.
| Domain | CLI | MCP tools | Docs |
|---|---|---|---|
| Profile (list / verify / show / default / add / remove / rename, login / logout / bootstrap) | dhis2 profile |
4 | Profiles |
| System (whoami, info) | dhis2 system |
2 | System module |
Metadata — core surface (list / get / patch / search / usage / export / import / diff / diff-profiles / merge) |
dhis2 metadata |
139 | Metadata plugin |
| Metadata — authoring triples (org-units, data-elements, indicators, program-indicators, category-options + legend-sets + options + attribute + program-rule + sql-view + viz + dashboard + map) | dhis2 metadata <sub-app> |
— (part of metadata count above) | Organisation units / Data elements / Indicators / Program indicators / Category options / Legend sets |
Data (aggregate dataValueSets + dataValues, tracker entities / enrollments / events / relationships / push) |
dhis2 data aggregate + dhis2 data tracker |
15 | Aggregate plugin / Tracker plugin |
| Analytics (aggregate / event / enrollment / outlier / tracked-entity queries) | dhis2 analytics |
5 | Analytics plugin |
Route (/api/routes integration proxies) |
dhis2 route |
7 | Auth schemes |
| Maintenance (tasks, cache, cleanup, data integrity, validation, predictors) | dhis2 maintenance |
15 | Maintenance plugin |
| Files (documents + file resources) | dhis2 files |
5 | Files plugin |
Messaging (/api/messageConversations + ticket-workflow fields) |
dhis2 messaging |
11 | Messaging plugin |
| User admin (users, user-groups, user-roles, sharing) | dhis2 user + dhis2 user-group + dhis2 user-role |
16 | User plugin / User groups + roles |
| Customize (login page / logos / CSS / system settings) | dhis2 dev customize |
7 | Customize plugin |
Apps (/api/apps + /api/appHub + snapshot/restore) |
dhis2 apps |
13 | Apps API |
| Doctor (BUGS tripwires + integrity checks + metadata health) | dhis2 doctor |
4 | Doctor plugin |
| Dev (codegen, uid, pat, oauth2 client, sample fixtures) | dhis2 dev |
— (dev-only) | Codegen |
| Browser automation (Playwright-driven PAT mint, screenshots, OIDC login) | dhis2 browser |
— (runs out-of-process) | Browser automation |
Day-to-day workflows (make install, make lint, make test, make docs-serve) are documented in the repo root README.md.