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.
@@ -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,5 @@
1
+ include LICENSE
2
+ include README.md
3
+ include CHANGELOG.md
4
+ include CLAUDE.md
5
+ recursive-include tests *.py
@@ -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"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,8 @@
1
+ from importlib.metadata import PackageNotFoundError, version as _version
2
+
3
+ try:
4
+ __version__ = _version('dhis2-fetch-core')
5
+ except PackageNotFoundError: # imported from a source tree that was never installed
6
+ __version__ = '0.0.0+unknown'
7
+
8
+ __all__ = []
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,5 @@
1
+ requests
2
+
3
+ [dev]
4
+ pytest>=7
5
+ responses>=0.23
@@ -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'