dhis2-fetch-core 0.0.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- dhis2_fetch_core-0.0.1/CHANGELOG.md +9 -0
- dhis2_fetch_core-0.0.1/CLAUDE.md +111 -0
- dhis2_fetch_core-0.0.1/LICENSE +21 -0
- dhis2_fetch_core-0.0.1/MANIFEST.in +5 -0
- dhis2_fetch_core-0.0.1/PKG-INFO +119 -0
- dhis2_fetch_core-0.0.1/README.md +88 -0
- dhis2_fetch_core-0.0.1/pyproject.toml +48 -0
- dhis2_fetch_core-0.0.1/setup.cfg +4 -0
- dhis2_fetch_core-0.0.1/src/dhis2_fetch_core/__init__.py +8 -0
- dhis2_fetch_core-0.0.1/src/dhis2_fetch_core/py.typed +0 -0
- dhis2_fetch_core-0.0.1/src/dhis2_fetch_core.egg-info/PKG-INFO +119 -0
- dhis2_fetch_core-0.0.1/src/dhis2_fetch_core.egg-info/SOURCES.txt +17 -0
- dhis2_fetch_core-0.0.1/src/dhis2_fetch_core.egg-info/dependency_links.txt +1 -0
- dhis2_fetch_core-0.0.1/src/dhis2_fetch_core.egg-info/requires.txt +5 -0
- dhis2_fetch_core-0.0.1/src/dhis2_fetch_core.egg-info/top_level.txt +1 -0
- dhis2_fetch_core-0.0.1/tests/test_ascii_messages.py +16 -0
- dhis2_fetch_core-0.0.1/tests/test_core_rules.py +74 -0
- dhis2_fetch_core-0.0.1/tests/test_docstrings.py +38 -0
- dhis2_fetch_core-0.0.1/tests/test_version.py +16 -0
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
Notable changes to `dhis2-fetch-core`. Versions follow [semantic versioning](https://semver.org): while
|
|
4
|
+
the major version is 0, a minor bump may change the API.
|
|
5
|
+
|
|
6
|
+
## Unreleased
|
|
7
|
+
|
|
8
|
+
- Repository skeleton: packaging, the core rules and the tests that enforce them, and the test and
|
|
9
|
+
publish workflows. No public API yet.
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# dhis2-fetch-core — project instructions
|
|
2
|
+
|
|
3
|
+
The read-only DHIS2 Web API core shared by two front ends: dhis2-fetch (pandas DataFrames for analysts)
|
|
4
|
+
and the DHIS2 Analytics MCP (tools for an AI assistant). The core holds how DHIS2 behaves; each front end
|
|
5
|
+
decides how results are shown.
|
|
6
|
+
|
|
7
|
+
## Invariants — do not break these
|
|
8
|
+
|
|
9
|
+
- **Read-only.** The package makes exactly one kind of HTTP call, a GET, at a single call site in
|
|
10
|
+
`connection.py`. There is no POST/PUT/PATCH/DELETE anywhere and there must not be. Both front ends
|
|
11
|
+
state this guarantee to people pointing them at production health information systems.
|
|
12
|
+
- **No side effects.** No `print`, no `input()`, no file writes, no environment variables. The front end
|
|
13
|
+
passes every setting in. A hook (`on_request`) hands each request's details back, and the front end
|
|
14
|
+
decides whether to log them.
|
|
15
|
+
- **Plain data.** No pandas or numpy. Functions return dicts and lists and raise typed exceptions. The
|
|
16
|
+
MCP ships as a bundle and must not grow by a data-frame library.
|
|
17
|
+
- **Thread-safe per connection.** The MCP calls one connection from several threads at once. A
|
|
18
|
+
`requests` session is not safe across threads, so a connection keeps one per thread, and its limits
|
|
19
|
+
(requests in flight, the pause after repeated failures) sit behind a lock.
|
|
20
|
+
- **Estimate before fetching.** Any bulk pull (analytics, data values, events) can be sized before it
|
|
21
|
+
runs. The core reports cells, requests and approximate size. Thresholds and what happens at them
|
|
22
|
+
belong to the front end.
|
|
23
|
+
- **Defaults are parameters.** The two front ends want different things: the MCP the fewest requests and
|
|
24
|
+
an error when a server is paused, dhis2-fetch small requests that resume well and a wait. Where they
|
|
25
|
+
differ, the core takes a parameter and neither default is baked in.
|
|
26
|
+
- **Nothing implies institutional backing.** No employer names, work email addresses, or anything
|
|
27
|
+
suggesting an official DHIS2 tool, in code, docs or package metadata.
|
|
28
|
+
- **No credentials or real instance URLs in the repo.** Examples and smoke tests use the public DHIS2
|
|
29
|
+
demo and take everything else from arguments.
|
|
30
|
+
|
|
31
|
+
`tests/test_core_rules.py` fails when code breaks the first three. Fix the code, not the test.
|
|
32
|
+
|
|
33
|
+
## Code style
|
|
34
|
+
|
|
35
|
+
dhis2-fetch's rules, so code moves between the two without rewriting.
|
|
36
|
+
|
|
37
|
+
**Every public function starts its docstring with a one-line summary** in plain wording that says what
|
|
38
|
+
it gives you, not how it works.
|
|
39
|
+
|
|
40
|
+
**Everything in `__all__` also documents every parameter**, in `Args:` / `Returns:` sections:
|
|
41
|
+
`name (type): what it does`, saying `optional` and the default where there is one. No reStructuredText,
|
|
42
|
+
no type jargon (`list of str`, not `Optional[List[str]]`). `tests/test_docstrings.py` fails if a
|
|
43
|
+
parameter is added without being documented. Internal functions keep the one-line summary only.
|
|
44
|
+
|
|
45
|
+
**Comments stay minimal**: no multi-line comment blocks, and a single short `# inline comment` only where
|
|
46
|
+
the why is not obvious. A longer note on how DHIS2 behaves goes in the list below, with a one-line
|
|
47
|
+
comment at the code that handles it.
|
|
48
|
+
|
|
49
|
+
**Messages are plain ASCII** (`tests/test_ascii_messages.py`): a plain Windows terminal shows other
|
|
50
|
+
characters as replacement marks.
|
|
51
|
+
|
|
52
|
+
The code must run on Python 3.9: no `match`, no `X | Y` in annotations that are evaluated, no
|
|
53
|
+
`tomllib`.
|
|
54
|
+
|
|
55
|
+
## How DHIS2 behaves
|
|
56
|
+
|
|
57
|
+
Notes carried over from the two projects. Each was learned against a real instance or the DHIS2 source,
|
|
58
|
+
and each belongs next to the code that handles it once that code is here.
|
|
59
|
+
|
|
60
|
+
- **E7131 is an analytics query timeout**, not a bad request: it is transient and worth one retry, since
|
|
61
|
+
DHIS2 often finishes and caches the query. E7144 means the analytics tables are missing, so no
|
|
62
|
+
analytics request can succeed until they are built. E7113 and E7114 are category option combo errors.
|
|
63
|
+
- **Tracker events moved.** `/api/tracker/events` exists from 2.38, and the old `/api/events` was
|
|
64
|
+
removed in 2.42. The two name their parameters and fields differently (`occurredAt` against
|
|
65
|
+
`eventDate`, `occurredAfter` against `startDate`).
|
|
66
|
+
- **The org unit mode parameter depends on the version**: `ouMode` up to 2.40, `orgUnitMode` from 2.41.
|
|
67
|
+
2.41 rejects a request that carries both.
|
|
68
|
+
- **Event UID lists depend on the version**: `event` with semicolons on 2.40 and the old API, `events`
|
|
69
|
+
with commas from 2.41. The result list is under `instances` on 2.40 and `events` from 2.41.
|
|
70
|
+
- **`program` is required for tracker events from 2.43.**
|
|
71
|
+
- **Old parameter names sent to the tracker endpoint still return 200**, with a pager that has no
|
|
72
|
+
`pageCount`, which silently cuts a download to its first page.
|
|
73
|
+
- **`dataValueSets` moves a single-valued field to the top of the response.** Ask for one period or one
|
|
74
|
+
org unit and that field is absent from every row.
|
|
75
|
+
- **A malformed UID returns 405, not 404**, on newer versions.
|
|
76
|
+
- **Week periods are unpadded**: `2021W1`, not `2021W01`.
|
|
77
|
+
- **A chart's `/api/visualizations/{uid}/data.json` returns a PNG.** Only a pivot table gives its
|
|
78
|
+
numbers there, so chart data is fetched through analytics from the saved layout.
|
|
79
|
+
- **Year-over-year charts** run each series year with `relativePeriodDate` set to today's month and day
|
|
80
|
+
in that year, as the Data Visualizer app does.
|
|
81
|
+
- **Personal access tokens** exist from 2.37 and are on by default from 2.38. The header is
|
|
82
|
+
`Authorization: ApiToken <token>`.
|
|
83
|
+
- **`requests` drops credentials when a redirect changes host**, which the public demo's short address
|
|
84
|
+
does. Use the address it redirects to.
|
|
85
|
+
|
|
86
|
+
## Layout
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
src/dhis2_fetch_core/
|
|
90
|
+
__init__.py exports the public API (empty until 0.1)
|
|
91
|
+
tests/
|
|
92
|
+
test_core_rules.py test_docstrings.py test_ascii_messages.py test_version.py
|
|
93
|
+
.github/workflows/
|
|
94
|
+
tests.yml Python 3.9 to 3.14 on Linux, both ends of the range on Windows
|
|
95
|
+
publish.yml builds and uploads to PyPI when a vX.Y.Z tag is pushed
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Modules planned, each arriving with its code and tests: `connection`, `errors`, `versions`, `analytics`,
|
|
99
|
+
`visualizations`, `events`, `metadata`, `datavalues`, `periods`.
|
|
100
|
+
|
|
101
|
+
## Working with the front ends
|
|
102
|
+
|
|
103
|
+
- Code is copied in from a front end, not moved. The front end keeps its copy until it has switched to
|
|
104
|
+
the core, so a change to copied code is made here first.
|
|
105
|
+
- dhis2-fetch depends on a range of core versions; the MCP pins one exact version per release.
|
|
106
|
+
- Before a release, run both front ends' test suites against the core from a local clone
|
|
107
|
+
(`pip install -e ../dhis2-fetch-core` in each).
|
|
108
|
+
|
|
109
|
+
## Status
|
|
110
|
+
|
|
111
|
+
`0.0.1`: skeleton, nothing published. A version number can never be reused on PyPI.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 dhis2-fetch-core contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: dhis2-fetch-core
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: Read-only core for DHIS2 Web API clients: connection, error codes, version differences and query builders
|
|
5
|
+
Author: Elijah Filip, Valérian Turbé
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/elifilip/dhis2-fetch-core
|
|
8
|
+
Project-URL: Repository, https://github.com/elifilip/dhis2-fetch-core
|
|
9
|
+
Project-URL: Issues, https://github.com/elifilip/dhis2-fetch-core/issues
|
|
10
|
+
Keywords: dhis2,health,hmis,api
|
|
11
|
+
Classifier: Development Status :: 1 - Planning
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: Healthcare Industry
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.9
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Requires-Dist: requests
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
29
|
+
Requires-Dist: responses>=0.23; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# dhis2-fetch-core
|
|
33
|
+
|
|
34
|
+
A small read-only Python library that holds what a DHIS2 Web API client has to know: how to connect
|
|
35
|
+
without overloading a server, what DHIS2's error codes mean, how the API differs between DHIS2 versions,
|
|
36
|
+
and how to build and batch queries.
|
|
37
|
+
|
|
38
|
+
It exists so that two projects stop keeping separate copies of that knowledge:
|
|
39
|
+
|
|
40
|
+
- [dhis2-fetch](https://pypi.org/project/dhis2-fetch/), which returns pandas DataFrames to analysts in
|
|
41
|
+
notebooks, scripts and pipelines.
|
|
42
|
+
- [DHIS2 Analytics MCP](https://github.com/elifilip/dhis2-analytics-mcp), which lets people ask an AI
|
|
43
|
+
assistant questions about a DHIS2 instance.
|
|
44
|
+
|
|
45
|
+
Each keeps its own front end and depends on this package. The core decides nothing about how results are
|
|
46
|
+
shown.
|
|
47
|
+
|
|
48
|
+
## Status
|
|
49
|
+
|
|
50
|
+
**Skeleton only.** Version `0.0.1` contains the packaging, the rules below and the tests that enforce
|
|
51
|
+
them. There is no public API yet. Code arrives in stages, copied from the two projects with its tests:
|
|
52
|
+
|
|
53
|
+
| Release | What it adds |
|
|
54
|
+
| --- | --- |
|
|
55
|
+
| 0.1 | Functions that build requests and read errors but send nothing: error codes, version differences, dimension helpers, the batch planner, saved-layout queries, periods |
|
|
56
|
+
| 0.2 | The connection: login, the single GET, retries, limits that protect the server, a hook per request |
|
|
57
|
+
| 0.3 | Shared fetch loops, size estimates before a pull, a resumable job store |
|
|
58
|
+
|
|
59
|
+
Do not depend on it before 0.1.
|
|
60
|
+
|
|
61
|
+
## Rules
|
|
62
|
+
|
|
63
|
+
The core is useful to both projects only if it never does anything a front end would have to undo.
|
|
64
|
+
|
|
65
|
+
- **Read-only.** It sends GET requests and nothing else, from one place (`connection.py`).
|
|
66
|
+
- **No side effects.** No printing, no prompts, no file writes, no environment variables. The front end
|
|
67
|
+
passes everything in, and a hook hands each request's details back.
|
|
68
|
+
- **Plain data.** No pandas or numpy. Functions return dicts and lists and raise typed exceptions.
|
|
69
|
+
- **Thread-safe per connection.** One connection may be called from several threads at once.
|
|
70
|
+
- **Estimate before fetching.** Any bulk pull can be sized before it runs. The core reports the size; the
|
|
71
|
+
front end decides what is too much.
|
|
72
|
+
- **Documented.** Every public function documents its parameters, and messages are plain ASCII.
|
|
73
|
+
- **Neutral identity.** No employer names, real instance URLs or credentials in the repository.
|
|
74
|
+
|
|
75
|
+
`tests/test_core_rules.py`, `tests/test_docstrings.py` and `tests/test_ascii_messages.py` check the rules
|
|
76
|
+
that can be checked.
|
|
77
|
+
|
|
78
|
+
## Decisions
|
|
79
|
+
|
|
80
|
+
| Decision | Choice |
|
|
81
|
+
| --- | --- |
|
|
82
|
+
| Name | `dhis2-fetch-core` on PyPI, imported as `dhis2_fetch_core` |
|
|
83
|
+
| Licence | MIT |
|
|
84
|
+
| HTTP library | requests |
|
|
85
|
+
| Python | 3.9 and later, tested through 3.14 |
|
|
86
|
+
| DHIS2 | Tested from 2.40; older versions on a best-effort basis |
|
|
87
|
+
| Code style | dhis2-fetch's rules (see `CLAUDE.md`) |
|
|
88
|
+
|
|
89
|
+
## Development
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
pip install -e ".[dev]"
|
|
93
|
+
pytest -q
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
To work on the core and a front end together, install the core from your local clone into the front
|
|
97
|
+
end's environment:
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
pip install -e ../dhis2-fetch-core
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
A change to how DHIS2 is called goes into the core first, then each front end raises the version it
|
|
104
|
+
depends on. dhis2-fetch pins a range and the MCP pins an exact version.
|
|
105
|
+
|
|
106
|
+
## Releasing
|
|
107
|
+
|
|
108
|
+
1. Set the new `version` in `pyproject.toml` and move the CHANGELOG's entries under it.
|
|
109
|
+
2. Commit, then tag that commit `vX.Y.Z` and push the tag.
|
|
110
|
+
3. The `publish` workflow checks the tag against `pyproject.toml`, runs the tests, builds and uploads to
|
|
111
|
+
PyPI.
|
|
112
|
+
|
|
113
|
+
The upload uses PyPI's trusted publishing, which has to be set up once on PyPI for this repository and
|
|
114
|
+
the `publish.yml` workflow. A version number can never be reused on PyPI.
|
|
115
|
+
|
|
116
|
+
## Licence and affiliation
|
|
117
|
+
|
|
118
|
+
MIT. This is an independent, unofficial project. It is not affiliated with or endorsed by the DHIS2
|
|
119
|
+
project.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# dhis2-fetch-core
|
|
2
|
+
|
|
3
|
+
A small read-only Python library that holds what a DHIS2 Web API client has to know: how to connect
|
|
4
|
+
without overloading a server, what DHIS2's error codes mean, how the API differs between DHIS2 versions,
|
|
5
|
+
and how to build and batch queries.
|
|
6
|
+
|
|
7
|
+
It exists so that two projects stop keeping separate copies of that knowledge:
|
|
8
|
+
|
|
9
|
+
- [dhis2-fetch](https://pypi.org/project/dhis2-fetch/), which returns pandas DataFrames to analysts in
|
|
10
|
+
notebooks, scripts and pipelines.
|
|
11
|
+
- [DHIS2 Analytics MCP](https://github.com/elifilip/dhis2-analytics-mcp), which lets people ask an AI
|
|
12
|
+
assistant questions about a DHIS2 instance.
|
|
13
|
+
|
|
14
|
+
Each keeps its own front end and depends on this package. The core decides nothing about how results are
|
|
15
|
+
shown.
|
|
16
|
+
|
|
17
|
+
## Status
|
|
18
|
+
|
|
19
|
+
**Skeleton only.** Version `0.0.1` contains the packaging, the rules below and the tests that enforce
|
|
20
|
+
them. There is no public API yet. Code arrives in stages, copied from the two projects with its tests:
|
|
21
|
+
|
|
22
|
+
| Release | What it adds |
|
|
23
|
+
| --- | --- |
|
|
24
|
+
| 0.1 | Functions that build requests and read errors but send nothing: error codes, version differences, dimension helpers, the batch planner, saved-layout queries, periods |
|
|
25
|
+
| 0.2 | The connection: login, the single GET, retries, limits that protect the server, a hook per request |
|
|
26
|
+
| 0.3 | Shared fetch loops, size estimates before a pull, a resumable job store |
|
|
27
|
+
|
|
28
|
+
Do not depend on it before 0.1.
|
|
29
|
+
|
|
30
|
+
## Rules
|
|
31
|
+
|
|
32
|
+
The core is useful to both projects only if it never does anything a front end would have to undo.
|
|
33
|
+
|
|
34
|
+
- **Read-only.** It sends GET requests and nothing else, from one place (`connection.py`).
|
|
35
|
+
- **No side effects.** No printing, no prompts, no file writes, no environment variables. The front end
|
|
36
|
+
passes everything in, and a hook hands each request's details back.
|
|
37
|
+
- **Plain data.** No pandas or numpy. Functions return dicts and lists and raise typed exceptions.
|
|
38
|
+
- **Thread-safe per connection.** One connection may be called from several threads at once.
|
|
39
|
+
- **Estimate before fetching.** Any bulk pull can be sized before it runs. The core reports the size; the
|
|
40
|
+
front end decides what is too much.
|
|
41
|
+
- **Documented.** Every public function documents its parameters, and messages are plain ASCII.
|
|
42
|
+
- **Neutral identity.** No employer names, real instance URLs or credentials in the repository.
|
|
43
|
+
|
|
44
|
+
`tests/test_core_rules.py`, `tests/test_docstrings.py` and `tests/test_ascii_messages.py` check the rules
|
|
45
|
+
that can be checked.
|
|
46
|
+
|
|
47
|
+
## Decisions
|
|
48
|
+
|
|
49
|
+
| Decision | Choice |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| Name | `dhis2-fetch-core` on PyPI, imported as `dhis2_fetch_core` |
|
|
52
|
+
| Licence | MIT |
|
|
53
|
+
| HTTP library | requests |
|
|
54
|
+
| Python | 3.9 and later, tested through 3.14 |
|
|
55
|
+
| DHIS2 | Tested from 2.40; older versions on a best-effort basis |
|
|
56
|
+
| Code style | dhis2-fetch's rules (see `CLAUDE.md`) |
|
|
57
|
+
|
|
58
|
+
## Development
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
pip install -e ".[dev]"
|
|
62
|
+
pytest -q
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
To work on the core and a front end together, install the core from your local clone into the front
|
|
66
|
+
end's environment:
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
pip install -e ../dhis2-fetch-core
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
A change to how DHIS2 is called goes into the core first, then each front end raises the version it
|
|
73
|
+
depends on. dhis2-fetch pins a range and the MCP pins an exact version.
|
|
74
|
+
|
|
75
|
+
## Releasing
|
|
76
|
+
|
|
77
|
+
1. Set the new `version` in `pyproject.toml` and move the CHANGELOG's entries under it.
|
|
78
|
+
2. Commit, then tag that commit `vX.Y.Z` and push the tag.
|
|
79
|
+
3. The `publish` workflow checks the tag against `pyproject.toml`, runs the tests, builds and uploads to
|
|
80
|
+
PyPI.
|
|
81
|
+
|
|
82
|
+
The upload uses PyPI's trusted publishing, which has to be set up once on PyPI for this repository and
|
|
83
|
+
the `publish.yml` workflow. A version number can never be reused on PyPI.
|
|
84
|
+
|
|
85
|
+
## Licence and affiliation
|
|
86
|
+
|
|
87
|
+
MIT. This is an independent, unofficial project. It is not affiliated with or endorsed by the DHIS2
|
|
88
|
+
project.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "dhis2-fetch-core"
|
|
7
|
+
version = "0.0.1"
|
|
8
|
+
description = "Read-only core for DHIS2 Web API clients: connection, error codes, version differences and query builders"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
authors = [{name = "Elijah Filip"}, {name = "Valérian Turbé"}]
|
|
11
|
+
license = "MIT"
|
|
12
|
+
license-files = ["LICENSE"]
|
|
13
|
+
requires-python = ">=3.9"
|
|
14
|
+
keywords = ["dhis2", "health", "hmis", "api"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 1 - Planning",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Intended Audience :: Healthcare Industry",
|
|
19
|
+
"Operating System :: OS Independent",
|
|
20
|
+
"Programming Language :: Python :: 3",
|
|
21
|
+
"Programming Language :: Python :: 3.9",
|
|
22
|
+
"Programming Language :: Python :: 3.10",
|
|
23
|
+
"Programming Language :: Python :: 3.11",
|
|
24
|
+
"Programming Language :: Python :: 3.12",
|
|
25
|
+
"Programming Language :: Python :: 3.13",
|
|
26
|
+
"Programming Language :: Python :: 3.14",
|
|
27
|
+
"Typing :: Typed",
|
|
28
|
+
]
|
|
29
|
+
dependencies = [
|
|
30
|
+
"requests",
|
|
31
|
+
]
|
|
32
|
+
|
|
33
|
+
[project.urls]
|
|
34
|
+
Homepage = "https://github.com/elifilip/dhis2-fetch-core"
|
|
35
|
+
Repository = "https://github.com/elifilip/dhis2-fetch-core"
|
|
36
|
+
Issues = "https://github.com/elifilip/dhis2-fetch-core/issues"
|
|
37
|
+
|
|
38
|
+
[project.optional-dependencies]
|
|
39
|
+
dev = ["pytest>=7", "responses>=0.23"]
|
|
40
|
+
|
|
41
|
+
[tool.pytest.ini_options]
|
|
42
|
+
testpaths = ["tests"]
|
|
43
|
+
|
|
44
|
+
[tool.setuptools.packages.find]
|
|
45
|
+
where = ["src"]
|
|
46
|
+
|
|
47
|
+
[tool.setuptools.package-data]
|
|
48
|
+
dhis2_fetch_core = ["py.typed"]
|
|
File without changes
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: dhis2-fetch-core
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Summary: Read-only core for DHIS2 Web API clients: connection, error codes, version differences and query builders
|
|
5
|
+
Author: Elijah Filip, Valérian Turbé
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/elifilip/dhis2-fetch-core
|
|
8
|
+
Project-URL: Repository, https://github.com/elifilip/dhis2-fetch-core
|
|
9
|
+
Project-URL: Issues, https://github.com/elifilip/dhis2-fetch-core/issues
|
|
10
|
+
Keywords: dhis2,health,hmis,api
|
|
11
|
+
Classifier: Development Status :: 1 - Planning
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: Healthcare Industry
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
22
|
+
Classifier: Typing :: Typed
|
|
23
|
+
Requires-Python: >=3.9
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Requires-Dist: requests
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: pytest>=7; extra == "dev"
|
|
29
|
+
Requires-Dist: responses>=0.23; extra == "dev"
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
# dhis2-fetch-core
|
|
33
|
+
|
|
34
|
+
A small read-only Python library that holds what a DHIS2 Web API client has to know: how to connect
|
|
35
|
+
without overloading a server, what DHIS2's error codes mean, how the API differs between DHIS2 versions,
|
|
36
|
+
and how to build and batch queries.
|
|
37
|
+
|
|
38
|
+
It exists so that two projects stop keeping separate copies of that knowledge:
|
|
39
|
+
|
|
40
|
+
- [dhis2-fetch](https://pypi.org/project/dhis2-fetch/), which returns pandas DataFrames to analysts in
|
|
41
|
+
notebooks, scripts and pipelines.
|
|
42
|
+
- [DHIS2 Analytics MCP](https://github.com/elifilip/dhis2-analytics-mcp), which lets people ask an AI
|
|
43
|
+
assistant questions about a DHIS2 instance.
|
|
44
|
+
|
|
45
|
+
Each keeps its own front end and depends on this package. The core decides nothing about how results are
|
|
46
|
+
shown.
|
|
47
|
+
|
|
48
|
+
## Status
|
|
49
|
+
|
|
50
|
+
**Skeleton only.** Version `0.0.1` contains the packaging, the rules below and the tests that enforce
|
|
51
|
+
them. There is no public API yet. Code arrives in stages, copied from the two projects with its tests:
|
|
52
|
+
|
|
53
|
+
| Release | What it adds |
|
|
54
|
+
| --- | --- |
|
|
55
|
+
| 0.1 | Functions that build requests and read errors but send nothing: error codes, version differences, dimension helpers, the batch planner, saved-layout queries, periods |
|
|
56
|
+
| 0.2 | The connection: login, the single GET, retries, limits that protect the server, a hook per request |
|
|
57
|
+
| 0.3 | Shared fetch loops, size estimates before a pull, a resumable job store |
|
|
58
|
+
|
|
59
|
+
Do not depend on it before 0.1.
|
|
60
|
+
|
|
61
|
+
## Rules
|
|
62
|
+
|
|
63
|
+
The core is useful to both projects only if it never does anything a front end would have to undo.
|
|
64
|
+
|
|
65
|
+
- **Read-only.** It sends GET requests and nothing else, from one place (`connection.py`).
|
|
66
|
+
- **No side effects.** No printing, no prompts, no file writes, no environment variables. The front end
|
|
67
|
+
passes everything in, and a hook hands each request's details back.
|
|
68
|
+
- **Plain data.** No pandas or numpy. Functions return dicts and lists and raise typed exceptions.
|
|
69
|
+
- **Thread-safe per connection.** One connection may be called from several threads at once.
|
|
70
|
+
- **Estimate before fetching.** Any bulk pull can be sized before it runs. The core reports the size; the
|
|
71
|
+
front end decides what is too much.
|
|
72
|
+
- **Documented.** Every public function documents its parameters, and messages are plain ASCII.
|
|
73
|
+
- **Neutral identity.** No employer names, real instance URLs or credentials in the repository.
|
|
74
|
+
|
|
75
|
+
`tests/test_core_rules.py`, `tests/test_docstrings.py` and `tests/test_ascii_messages.py` check the rules
|
|
76
|
+
that can be checked.
|
|
77
|
+
|
|
78
|
+
## Decisions
|
|
79
|
+
|
|
80
|
+
| Decision | Choice |
|
|
81
|
+
| --- | --- |
|
|
82
|
+
| Name | `dhis2-fetch-core` on PyPI, imported as `dhis2_fetch_core` |
|
|
83
|
+
| Licence | MIT |
|
|
84
|
+
| HTTP library | requests |
|
|
85
|
+
| Python | 3.9 and later, tested through 3.14 |
|
|
86
|
+
| DHIS2 | Tested from 2.40; older versions on a best-effort basis |
|
|
87
|
+
| Code style | dhis2-fetch's rules (see `CLAUDE.md`) |
|
|
88
|
+
|
|
89
|
+
## Development
|
|
90
|
+
|
|
91
|
+
```
|
|
92
|
+
pip install -e ".[dev]"
|
|
93
|
+
pytest -q
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
To work on the core and a front end together, install the core from your local clone into the front
|
|
97
|
+
end's environment:
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
pip install -e ../dhis2-fetch-core
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
A change to how DHIS2 is called goes into the core first, then each front end raises the version it
|
|
104
|
+
depends on. dhis2-fetch pins a range and the MCP pins an exact version.
|
|
105
|
+
|
|
106
|
+
## Releasing
|
|
107
|
+
|
|
108
|
+
1. Set the new `version` in `pyproject.toml` and move the CHANGELOG's entries under it.
|
|
109
|
+
2. Commit, then tag that commit `vX.Y.Z` and push the tag.
|
|
110
|
+
3. The `publish` workflow checks the tag against `pyproject.toml`, runs the tests, builds and uploads to
|
|
111
|
+
PyPI.
|
|
112
|
+
|
|
113
|
+
The upload uses PyPI's trusted publishing, which has to be set up once on PyPI for this repository and
|
|
114
|
+
the `publish.yml` workflow. A version number can never be reused on PyPI.
|
|
115
|
+
|
|
116
|
+
## Licence and affiliation
|
|
117
|
+
|
|
118
|
+
MIT. This is an independent, unofficial project. It is not affiliated with or endorsed by the DHIS2
|
|
119
|
+
project.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
CHANGELOG.md
|
|
2
|
+
CLAUDE.md
|
|
3
|
+
LICENSE
|
|
4
|
+
MANIFEST.in
|
|
5
|
+
README.md
|
|
6
|
+
pyproject.toml
|
|
7
|
+
src/dhis2_fetch_core/__init__.py
|
|
8
|
+
src/dhis2_fetch_core/py.typed
|
|
9
|
+
src/dhis2_fetch_core.egg-info/PKG-INFO
|
|
10
|
+
src/dhis2_fetch_core.egg-info/SOURCES.txt
|
|
11
|
+
src/dhis2_fetch_core.egg-info/dependency_links.txt
|
|
12
|
+
src/dhis2_fetch_core.egg-info/requires.txt
|
|
13
|
+
src/dhis2_fetch_core.egg-info/top_level.txt
|
|
14
|
+
tests/test_ascii_messages.py
|
|
15
|
+
tests/test_core_rules.py
|
|
16
|
+
tests/test_docstrings.py
|
|
17
|
+
tests/test_version.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
dhis2_fetch_core
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import pathlib
|
|
2
|
+
|
|
3
|
+
import dhis2_fetch_core
|
|
4
|
+
|
|
5
|
+
PACKAGE = pathlib.Path(dhis2_fetch_core.__file__).parent
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def test_messages_are_plain_ascii():
|
|
9
|
+
# a plain Windows terminal shows characters such as an em dash as a replacement mark
|
|
10
|
+
files = sorted(PACKAGE.rglob('*.py'))
|
|
11
|
+
assert files
|
|
12
|
+
offenders = [f'{path.name}:{n}: {line.strip()[:80]}'
|
|
13
|
+
for path in files
|
|
14
|
+
for n, line in enumerate(path.read_text(encoding='utf-8').splitlines(), 1)
|
|
15
|
+
if not line.lstrip().startswith('#') and not line.isascii()]
|
|
16
|
+
assert not offenders, '\n'.join(offenders)
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import ast
|
|
2
|
+
import pathlib
|
|
3
|
+
|
|
4
|
+
import dhis2_fetch_core
|
|
5
|
+
|
|
6
|
+
PACKAGE = pathlib.Path(dhis2_fetch_core.__file__).parent
|
|
7
|
+
SOURCES = {path: ast.parse(path.read_text(encoding='utf-8')) for path in sorted(PACKAGE.rglob('*.py'))}
|
|
8
|
+
|
|
9
|
+
HTTP_MODULE = 'connection.py'
|
|
10
|
+
HTTP_LIBRARIES = {'requests', 'urllib3', 'httpx', 'aiohttp', 'http.client', 'urllib.request'}
|
|
11
|
+
WRITING_CALLS = {'post', 'put', 'patch', 'delete', 'request'}
|
|
12
|
+
WRITING_METHODS = {'POST', 'PUT', 'PATCH', 'DELETE'}
|
|
13
|
+
SIDE_EFFECT_CALLS = {'print', 'input', 'open'}
|
|
14
|
+
DATA_LIBRARIES = {'pandas', 'numpy'}
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _nodes(kind):
|
|
18
|
+
for path, tree in SOURCES.items():
|
|
19
|
+
for node in ast.walk(tree):
|
|
20
|
+
if isinstance(node, kind):
|
|
21
|
+
yield path, node
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def _imports():
|
|
25
|
+
for path, node in _nodes((ast.Import, ast.ImportFrom)):
|
|
26
|
+
names = [node.module or ''] if isinstance(node, ast.ImportFrom) else [alias.name for alias in node.names]
|
|
27
|
+
for name in names:
|
|
28
|
+
yield path, node, name
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _is(name, libraries):
|
|
32
|
+
return any(name == lib or name.startswith(lib + '.') for lib in libraries)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def _where(path, node):
|
|
36
|
+
return f'{path.name}:{node.lineno}'
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def test_the_package_source_is_found():
|
|
40
|
+
assert any(path.name == '__init__.py' for path in SOURCES)
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def test_only_the_connection_module_talks_http():
|
|
44
|
+
offenders = [_where(path, node) for path, node, name in _imports()
|
|
45
|
+
if _is(name, HTTP_LIBRARIES) and path.name != HTTP_MODULE]
|
|
46
|
+
assert not offenders, f'only {HTTP_MODULE} may import an HTTP library: {offenders}'
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
def test_no_http_method_that_writes():
|
|
50
|
+
# a call such as queue.put() trips this too: rename it, the rule is worth more than the name
|
|
51
|
+
calls = [_where(path, node) for path, node in _nodes(ast.Call)
|
|
52
|
+
if isinstance(node.func, ast.Attribute) and node.func.attr in WRITING_CALLS]
|
|
53
|
+
words = [_where(path, node) for path, node in _nodes(ast.Constant)
|
|
54
|
+
if isinstance(node.value, str) and node.value.upper() in WRITING_METHODS]
|
|
55
|
+
assert not calls + words, f'the core is read-only (GET), but see {calls + words}'
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def test_no_printing_prompting_or_opening_files():
|
|
59
|
+
offenders = [_where(path, node) for path, node in _nodes(ast.Call)
|
|
60
|
+
if isinstance(node.func, ast.Name) and node.func.id in SIDE_EFFECT_CALLS]
|
|
61
|
+
assert not offenders, f'front ends print, prompt and write files, the core does not: {offenders}'
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def test_no_environment_variables():
|
|
65
|
+
attributes = [_where(path, node) for path, node in _nodes(ast.Attribute)
|
|
66
|
+
if node.attr in {'environ', 'getenv'}]
|
|
67
|
+
imported = [_where(path, node) for path, node in _nodes(ast.ImportFrom)
|
|
68
|
+
if node.module == 'os' and {alias.name for alias in node.names} & {'environ', 'getenv'}]
|
|
69
|
+
assert not attributes + imported, f'settings are passed in by the front end: {attributes + imported}'
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def test_no_pandas_or_numpy():
|
|
73
|
+
offenders = [_where(path, node) for path, node, name in _imports() if _is(name, DATA_LIBRARIES)]
|
|
74
|
+
assert not offenders, f'the core returns dicts and lists: {offenders}'
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import inspect
|
|
2
|
+
|
|
3
|
+
import pytest
|
|
4
|
+
|
|
5
|
+
import dhis2_fetch_core
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def _public_callables():
|
|
9
|
+
for name in dhis2_fetch_core.__all__:
|
|
10
|
+
obj = getattr(dhis2_fetch_core, name)
|
|
11
|
+
if inspect.isclass(obj):
|
|
12
|
+
if not issubclass(obj, Exception):
|
|
13
|
+
yield f'{name}.__init__', obj.__init__
|
|
14
|
+
elif callable(obj):
|
|
15
|
+
yield name, obj
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
PUBLIC = list(_public_callables())
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def test_everything_in_all_exists():
|
|
22
|
+
missing = [name for name in dhis2_fetch_core.__all__ if not hasattr(dhis2_fetch_core, name)]
|
|
23
|
+
assert not missing
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@pytest.mark.parametrize('name,fn', PUBLIC, ids=[n for n, _ in PUBLIC])
|
|
27
|
+
def test_every_public_function_starts_with_a_one_line_summary(name, fn):
|
|
28
|
+
doc = inspect.getdoc(fn)
|
|
29
|
+
assert doc, f'{name} has no docstring'
|
|
30
|
+
assert doc.splitlines()[0].strip().endswith('.'), f'{name}: the first line should be a whole sentence'
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
@pytest.mark.parametrize('name,fn', PUBLIC, ids=[n for n, _ in PUBLIC])
|
|
34
|
+
def test_every_parameter_is_documented_with_its_type(name, fn):
|
|
35
|
+
doc = inspect.getdoc(fn) or ''
|
|
36
|
+
params = [p for p in inspect.signature(fn).parameters if p != 'self']
|
|
37
|
+
missing = [p for p in params if f'{p} (' not in doc]
|
|
38
|
+
assert not missing, f'{name} does not document {missing} as "name (type): ..."'
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
from importlib.metadata import version
|
|
2
|
+
|
|
3
|
+
import dhis2_fetch_core
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
def test_version_is_exposed():
|
|
7
|
+
assert isinstance(dhis2_fetch_core.__version__, str)
|
|
8
|
+
assert dhis2_fetch_core.__version__
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def test_version_matches_installed_metadata():
|
|
12
|
+
assert dhis2_fetch_core.__version__ == version('dhis2-fetch-core')
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def test_version_is_not_the_uninstalled_fallback():
|
|
16
|
+
assert dhis2_fetch_core.__version__ != '0.0.0+unknown'
|