xippios-eurostat 0.1.0__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.
Files changed (64) hide show
  1. xippios_eurostat-0.1.0/.gitignore +23 -0
  2. xippios_eurostat-0.1.0/CHANGELOG.md +137 -0
  3. xippios_eurostat-0.1.0/LICENSE +201 -0
  4. xippios_eurostat-0.1.0/PKG-INFO +245 -0
  5. xippios_eurostat-0.1.0/README.md +216 -0
  6. xippios_eurostat-0.1.0/docs/handover.md +184 -0
  7. xippios_eurostat-0.1.0/docs/upstream/FETCHED.md +150 -0
  8. xippios_eurostat-0.1.0/docs/upstream/api/async.wadl +41 -0
  9. xippios_eurostat-0.1.0/docs/upstream/api/catalogue.wadl +453 -0
  10. xippios_eurostat-0.1.0/docs/upstream/api/sdmx-rest.wadl +1442 -0
  11. xippios_eurostat-0.1.0/docs/upstream/api/sdmx-rest.yaml +1904 -0
  12. xippios_eurostat-0.1.0/docs/upstream/api/statistics-rest.wadl +130 -0
  13. xippios_eurostat-0.1.0/docs/upstream/samples/apro_mk_cola-json-stat.json +1 -0
  14. xippios_eurostat-0.1.0/docs/upstream/samples/apro_mk_cola-sdmx-csv.csv +21 -0
  15. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/api-statistics.md +113 -0
  16. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/asynchronous-api.md +251 -0
  17. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/catalogue-api/dcat.md +14 -0
  18. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/catalogue-api/toc.md +53 -0
  19. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/catalogue-api.md +8 -0
  20. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/prefixed-datasets.md +11 -0
  21. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/sdmx2-1/data-query.md +260 -0
  22. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/sdmx2-1/structure-queries.md +163 -0
  23. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/sdmx2-1.md +10 -0
  24. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines.md +16 -0
  25. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-faq/tsv-format.md +196 -0
  26. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-faq.md +110 -0
  27. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-getting-started/api.md +205 -0
  28. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-getting-started/catalogue-api.md +107 -0
  29. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-getting-started/sdmx2.1.md +652 -0
  30. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-getting-started.md +104 -0
  31. xippios_eurostat-0.1.0/docs/upstream/user-guide/api-introduction.md +199 -0
  32. xippios_eurostat-0.1.0/pyproject.toml +104 -0
  33. xippios_eurostat-0.1.0/src/xippios/eurostat/__init__.py +27 -0
  34. xippios_eurostat-0.1.0/src/xippios/eurostat/_client.py +163 -0
  35. xippios_eurostat-0.1.0/src/xippios/eurostat/_version.py +10 -0
  36. xippios_eurostat-0.1.0/src/xippios/eurostat/api/__init__.py +14 -0
  37. xippios_eurostat-0.1.0/src/xippios/eurostat/api/catalogue.py +39 -0
  38. xippios_eurostat-0.1.0/src/xippios/eurostat/api/sdmx.py +196 -0
  39. xippios_eurostat-0.1.0/src/xippios/eurostat/api/statistics.py +111 -0
  40. xippios_eurostat-0.1.0/src/xippios/eurostat/enums.py +3 -0
  41. xippios_eurostat-0.1.0/src/xippios/eurostat/errors.py +153 -0
  42. xippios_eurostat-0.1.0/src/xippios/eurostat/http.py +18 -0
  43. xippios_eurostat-0.1.0/src/xippios/eurostat/mcp.py +33 -0
  44. xippios_eurostat-0.1.0/src/xippios/eurostat/models.py +458 -0
  45. xippios_eurostat-0.1.0/src/xippios/eurostat/params.py +191 -0
  46. xippios_eurostat-0.1.0/src/xippios/eurostat/parse/__init__.py +11 -0
  47. xippios_eurostat-0.1.0/src/xippios/eurostat/parse/sdmx_csv.py +173 -0
  48. xippios_eurostat-0.1.0/src/xippios/eurostat/py.typed +0 -0
  49. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/README.md +59 -0
  50. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/crops.json +2907 -0
  51. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/dairyprod.json +671 -0
  52. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/farmtype.json +459 -0
  53. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/freq.json +55 -0
  54. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/geo.json +17175 -0
  55. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/leg_form.json +119 -0
  56. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/lists.json +135 -0
  57. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/milkitem.json +75 -0
  58. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/so_eur.json +279 -0
  59. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/statinfo.json +443 -0
  60. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/strucpro.json +103 -0
  61. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/toc.json +114132 -0
  62. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/uaarea.json +91 -0
  63. xippios_eurostat-0.1.0/src/xippios/eurostat/reference/unit.json +3099 -0
  64. xippios_eurostat-0.1.0/src/xippios/eurostat/tasks.py +781 -0
@@ -0,0 +1,23 @@
1
+ # environments and caches
2
+ .venv/
3
+ __pycache__/
4
+ *.py[cod]
5
+ .mypy_cache/
6
+ .ruff_cache/
7
+ .pytest_cache/
8
+ .hypothesis/
9
+
10
+ # build artefacts
11
+ dist/
12
+ build/
13
+ *.egg-info/
14
+
15
+ # local secrets are never files, but belt and braces
16
+ .env
17
+ .env.*
18
+ .envrc
19
+ .envrc.*
20
+
21
+ # editors
22
+ .idea/
23
+ .vscode/
@@ -0,0 +1,137 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
+ [Semantic Versioning](https://semver.org/) (pre-1.0: breaking changes bump the minor).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.1.0] - 2026-10-28
10
+
11
+ First release, on xippios-core 0.3.0 from PyPI (`~=0.3.0`), sdk-template v0.3.0 and
12
+ conventions 1.21, its floor. It wraps Eurostat's dissemination API, which needs no key:
13
+ the Statistics API's JSON-stat cubes through `get_data` and the three slices
14
+ `get_series`, `get_latest_period` and `get_cross_section`; Eurostat's table of contents
15
+ and twelve SDMX codelists, packaged with this version as fetched on 2026-10-27 and read
16
+ without a request through `list_datasets` and `list_codes`; and the bulk task
17
+ `download_dataset`, in Python only, with no MCP tool and no route, which streams an
18
+ SDMX-CSV file to disk for `parse.parse_sdmx_csv` to read. The other six tasks are MCP
19
+ tools and HTTP routes. The client keeps a self-imposed pace of 30 requests per minute,
20
+ since Eurostat documents no rate in numbers, and caches its answers of HTTP 200 for five
21
+ minutes. Comext and Prodcom datasets, polling an asynchronous answer, which is refused
22
+ with how to narrow the query, and codelists beyond the twelve are not part of it.
23
+ Nothing was published before, so the entries under Changed record steps on the way to
24
+ this release.
25
+
26
+ ### Added
27
+
28
+ - Scaffold from [sdk-template](https://github.com/xippios/sdk-template): configured
29
+ client for Eurostat dissemination API, empty task layer, MCP server and FastAPI router
30
+ wired to it, test harness with core's family check, CI, the nightly live tests and
31
+ the release train, in which a release PR's merge tags and publishes.
32
+ - Upstream documentation snapshot of 2026-10-27 in `docs/upstream/`: 17 pages of
33
+ Eurostat's user guide "Data access via API" as Markdown, the WADL files of the
34
+ Statistics, SDMX 2.1, Catalogue and asynchronous APIs and the consolidated OpenAPI
35
+ document verbatim, and one JSON-stat and one SDMX-CSV answer as structural samples;
36
+ written by `scripts/refresh_upstream.py` (standard library only, no key), whose
37
+ `FETCHED.md` records each file's URL, fetch time, size and sha256, the pages not
38
+ fetched and why, and Eurostat's licence and reuse lines, its exceptions to commercial
39
+ reuse, its clause on modified reuse with the snapshot's disclaimer, and its citation
40
+ form.
41
+ - `get_data(dataset, filters=None, *, lang=Lang.EN, since_time_period=None,
42
+ until_time_period=None, last_time_period=None, geo_level=None)`: one Statistics API
43
+ request (`getData`, `statistics/1.0/data/{datasetCode}`) answered as a `Cube`, the
44
+ JSON-stat 2.0 dataset member by member, with `Cube.observations()` reading out the
45
+ cells that have a value or a status, each an `Observation` with its codes and labels;
46
+ `meta.published_at` is the cube's `updated`, with `meta.published_at_naive` set should
47
+ Eurostat print it without a zone (never seen; ADR-0022 rule 2), and `meta.vintage` its
48
+ text as printed. The StrEnums `Lang` and `GeoLevel` type `lang` and `geo_level`; more
49
+ than one time parameter, other than `since_time_period` with `until_time_period`, is
50
+ refused before sending. The MCP tool `eurostat_get_data` and the route
51
+ `POST /eurostat/get_data`.
52
+ - `classify` for the Statistics API's refusals (`errors.py`): an unknown dataset, and an
53
+ HTTP 400 whose faults are all 100 ("No results found"), are `NotFoundError`; any other
54
+ HTTP 400 `error`, as an array or as one object, is `InvalidRequestError` with
55
+ Eurostat's label; the asynchronous answer is `InvalidRequestError` saying to send the
56
+ request again later or to narrow it, and an HTTP 413 `InvalidRequestError` naming how
57
+ to narrow it. An unknown code is an empty cube, not an error.
58
+ - `get_series(dataset, filters, *, since=None, until=None, lang=Lang.EN)`,
59
+ `get_latest_period(dataset, filters=None, *, lang=Lang.EN)` and
60
+ `get_cross_section(dataset, period, filters=None, *, lang=Lang.EN)`: the task-shaped
61
+ slices, each one `getData` request through `get_data` (`sinceTimePeriod` and
62
+ `untilTimePeriod`, `lastTimePeriod=1`, `time=<period>`) answered as a list of
63
+ `Observation` with `get_data`'s `meta`. `get_series` refuses, after the request, an
64
+ answer that spans more than one series, naming the dimensions to pin and their codes;
65
+ each slice refuses a `time` filter before sending, and `get_cross_section` an empty
66
+ `period`; a code that matches nothing gives an empty list. The MCP tools
67
+ `eurostat_get_series`, `eurostat_get_latest_period` and `eurostat_get_cross_section`,
68
+ each with a result cap of its own in `MCP_CAPS` (the family's 200 rows or 64 KB, with
69
+ a note on how to see the rest), and the routes `POST /eurostat/get_series`,
70
+ `/eurostat/get_latest_period` and `/eurostat/get_cross_section`.
71
+ - `list_datasets(search=None)` and `list_codes(codelist, search=None)`: packaged answers
72
+ (ADR-0022) without a request. `list_datasets` reads the Catalogue API's table of
73
+ contents (`catalogue/toc/xml`, 10,375 leaves on 2026-10-27), each leaf a `Dataset`
74
+ with its code, type (`LeafType`), English title, the folders above it as `path`,
75
+ `lastUpdate`, `lastModified`, `dataStart`, `dataEnd` and `values` as printed;
76
+ `meta.vintage` is the TOC's `creationDate` as printed and `meta.published_at` its
77
+ time without a zone, `published_at_naive` set. `list_codes` reads one of the twelve
78
+ codelists of the dimensions of apro_cpnh1, apro_mk_cola and ef_m_farmleg (FREQ, GEO,
79
+ UNIT, CROPS, STRUCPRO, MILKITEM, DAIRYPROD, STATINFO, LEG_FORM, FARMTYPE, SO_EUR,
80
+ UAAREA; `sdmx/2.1/codelist/ESTAT/<ID>`, latest version, English labels), each code a
81
+ `Code`; the name is case-insensitive, an unknown one raises `UnknownCode` naming the
82
+ closest; `meta.vintage` is the codelist's version and `meta.published_at` its
83
+ `LAST_UPDATED`. `search` keeps the records whose code or title (label) contains the
84
+ text, ignoring case. `meta.retrieved_at` is the list's fetch time. The MCP tools
85
+ `eurostat_list_datasets` (the family's cap) and `eurostat_list_codes` (1,000 rows
86
+ within the family's 64 KB), each with a note naming `search`, and the routes
87
+ `GET /eurostat/list_datasets` and `/eurostat/list_codes`.
88
+ - `scripts/refresh_reference.py` fetches the table of contents (downloaded whole to a
89
+ temporary file with core's `download`, which streams the body to disk, then read from
90
+ that file a megabyte at a time with the standard library's ElementTree pull parser;
91
+ the script is the only code that parses XML, the package parses none) and the twelve
92
+ codelists as JSON-stat through the new endpoint wrappers `api.catalogue.getTocXml`
93
+ and `api.sdmx.codeListQuery`. It writes `reference/toc.json` and one
94
+ `reference/<codelist>.json` each with `PackagedList.write`, and `reference/lists.json`,
95
+ a derived index in plain JSON (`fetched` and `lists`) that holds upstream's release
96
+ identifiers of every list; `--samples` cuts the parser tests' samples under
97
+ `tests/fixtures/files/` from the same run. Thirteen keyless requests.
98
+ - `download_dataset(dataset, key="", *, since=None, until=None,
99
+ last_n_observations=None, dest)`, the bulk task: one SDMX 2.1 data query through the
100
+ new wrapper `api.sdmx.dataQuery` (`sdmx/2.1/data/{flowRef}/{key}`, `format=SDMX-CSV`,
101
+ `compressed=true`), streamed to `dest` with core's `download` and returned as
102
+ `Result[Downloaded]`; `key` is Eurostat's series key as given, `since`, `until` and
103
+ `last_n_observations` its `startPeriod`, `endPeriod` and `lastNObservations`.
104
+ `meta.vintage` is the first row's `LAST UPDATE` as printed and `meta.published_at` its
105
+ time, day first, without a zone, `published_at_naive` set. Named in `BULK_TASKS`, so
106
+ Python only: no MCP tool and no route.
107
+ - `parse.parse_sdmx_csv(path)`: an SDMX-CSV file, gzip-compressed or plain, read row by
108
+ row (plain through core's `decode_csv`), each row an `SdmxCsvRow` with `dataflow`,
109
+ `last_update`, the `dimensions` in column order, `time_period`, `obs_value` as a
110
+ `Decimal`, `obs_flag`, `conf_status` and any other `attributes`.
111
+ - `classify` refuses a 2xx answer to an SDMX data query whose `Content-Type` is not
112
+ SDMX-CSV's, such as the XML envelope that queues an asynchronous answer, with
113
+ `InvalidRequestError` naming how to narrow the query.
114
+
115
+ ### Changed
116
+
117
+ - `xippios-core` 0.3.0 from PyPI (`core_version` 0.3.0: `~=0.3.0` and its `mcp`, `http`
118
+ and `testing` extras likewise), with no git pin, while the template was still v0.2.2;
119
+ template v0.3.0 came in an adoption of its own, the last entry below. Core 0.3.0 keeps
120
+ the SDMX series `key` of this keyless source as data, not as a credential (ADR-0019,
121
+ decision 6), and brings `AsyncClient.download`, `decode_text` and `decode_csv` for
122
+ bulk files (ADR-0019, decisions 1 and 2); `pydantic-settings`, which core no longer
123
+ depends on, and `python-dotenv` with it leave `uv.lock`.
124
+ - `scripts/refresh_reference.py` renders `enums.py` with one `render_enums` call, value
125
+ lists and id lists in one module, each list with its own fetch date, and formats it
126
+ with `ruff format` and `ruff check --fix`, since core 0.3.0 removed `render_str_enums`
127
+ and `render_int_enums` (ADR-0008, amendment 2026-10-27): the port of core 0.3.0's
128
+ Hand-apply entry; `scripts/` is the package's, so template v0.3.0 reaches it only
129
+ through its Hand-apply list. `enums.py` is re-rendered by the script's first run, the
130
+ renderer's empty module, since Eurostat's packaged lists are tables and none is an
131
+ enum; the reference README and `/refresh-reference-data` name the new call.
132
+ - The client caches answers of HTTP 200 in core's `MemoryCache`, five minutes each, up
133
+ to core's `cache_max_bytes` of 8 MiB a body, so a larger cube is fetched again
134
+ (ADR-0019 decision 3); `getData` reads its answer with core 0.3.0's
135
+ `AsyncClient.get_answer`, so `get_data`'s `meta.retrieved_at` on a cache hit is the
136
+ time the answer was stored (conventions §4, ADR-0015 decision 5).
137
+ - Adopted xippios-core 0.3.0, sdk-template v0.3.0 and conventions 1.21 (conventions §15).
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright [yyyy] [name of copyright owner]
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
@@ -0,0 +1,245 @@
1
+ Metadata-Version: 2.5
2
+ Name: xippios-eurostat
3
+ Version: 0.1.0
4
+ Summary: Typed client, MCP tools and HTTP routes for Eurostat dissemination API
5
+ Project-URL: Homepage, https://github.com/xippios/sdk-eurostat
6
+ Project-URL: Upstream, https://ec.europa.eu/eurostat/web/main/data/database
7
+ Project-URL: Changelog, https://github.com/xippios/sdk-eurostat/blob/main/CHANGELOG.md
8
+ Project-URL: Issues, https://github.com/xippios/sdk-eurostat/issues
9
+ Author: XIPPIOS GmbH
10
+ License-Expression: Apache-2.0
11
+ License-File: LICENSE
12
+ Keywords: eurostat,httpx,mcp,pydantic,sdk
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.12
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Typing :: Typed
20
+ Requires-Python: >=3.12
21
+ Requires-Dist: xippios-core~=0.3.0
22
+ Provides-Extra: http
23
+ Requires-Dist: xippios-core[http]~=0.3.0; extra == 'http'
24
+ Provides-Extra: mcp
25
+ Requires-Dist: xippios-core[mcp]~=0.3.0; extra == 'mcp'
26
+ Provides-Extra: testing
27
+ Requires-Dist: xippios-core[testing]~=0.3.0; extra == 'testing'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # xippios-eurostat
31
+
32
+ Typed Python client, MCP server and FastAPI routes for
33
+ [Eurostat dissemination API](https://ec.europa.eu/eurostat/web/main/data/database), part of the
34
+ [xippios SDK family](https://github.com/xippios). Names and semantics follow the
35
+ upstream documentation; every response carries release metadata (source, endpoint,
36
+ retrieved_at, published_at, vintage).
37
+
38
+ ## Install
39
+
40
+ ```bash
41
+ uv add xippios-eurostat # client only
42
+ uv add "xippios-eurostat[mcp]" # + MCP server
43
+ uv add "xippios-eurostat[http]" # + FastAPI router
44
+ ```
45
+
46
+ No API key is needed.
47
+
48
+ ## 30-second example
49
+
50
+ ```python
51
+ from xippios.eurostat import get_data
52
+
53
+ milk = get_data("apro_mk_cola", {"geo": "AT", "time": ["2022", "2023"]})
54
+ cube = milk.data # the JSON-stat 2.0 dataset, member by member
55
+ cube.id # ["freq", "milkitem", "dairyprod", "unit", "geo", "time"]
56
+ cube.size # [1, 3, 10, 2, 1, 2]: codes per dimension
57
+ cube.value["40"] # 3247.05: cell 40, row-major over size, the last dimension fastest
58
+ cube.status["64"] # "|C": confidential, as cube.extension["status"]["label"] names it
59
+ first = next(cube.observations()) # one cell with its codes and labels
60
+ first.codes # {"freq": "A", "milkitem": "PRD", "dairyprod": "D1110D", "unit": "THS_T", ...}
61
+ first.labels["dairyprod"], first.value # "Raw cows' milk delivered to dairies", 3247.05
62
+ milk.meta.published_at # 2026-10-05 23:00+02:00: the dataset's last update, `updated`
63
+ milk.meta.vintage # "2026-10-05T23:00:00+0200": the same, as Eurostat prints it
64
+ milk.meta.request # {"dataset": "apro_mk_cola", "filters": {...}, "lang": "EN"}
65
+ ```
66
+
67
+ `get_data(dataset, filters=None, *, lang=Lang.EN, since_time_period=None,
68
+ until_time_period=None, last_time_period=None, geo_level=None)` sends one request to the
69
+ Statistics API (`statistics/1.0/data/{datasetCode}`). `filters` maps any dimension of the
70
+ dataset to one code or a list of codes (`{"geo": "AT", "milkitem": "PRD"}`); a `time`
71
+ filter selects periods, and so do `since_time_period`, `until_time_period` and
72
+ `last_time_period`. Eurostat accepts one time parameter per query, the one exception
73
+ being `since_time_period` with `until_time_period`; any other combination is refused
74
+ before sending. `lang` takes `Lang.EN`, `Lang.FR` or `Lang.DE` and `geo_level` a
75
+ `GeoLevel` (`aggregate`, `country`, `nuts1`, `nuts2`, `nuts3`, `city`), both in
76
+ `xippios.eurostat.models`; a plain string such as `"FR"` works too. A code that matches
77
+ nothing gives an empty cube, size 0 on that dimension. `meta.published_at` is the cube's
78
+ `updated` with Eurostat's zone; one printed without a zone, never seen, is kept as
79
+ printed with `meta.published_at_naive` set, and `meta.vintage` holds the text either
80
+ way. An unknown dataset, and Eurostat's "No results found", raise `NotFoundError`; a
81
+ query Eurostat refuses or judges too large raises `InvalidRequestError` with Eurostat's
82
+ message and how to narrow it. A query Eurostat would answer asynchronously raises it
83
+ too: this package does not poll asynchronous answers, and the Statistics API's own route
84
+ is to send the same request again later. Ask for small slices: the cube comes back
85
+ whole, and over MCP a result above 64 KB is replaced by a preview and a note.
86
+
87
+ ### Slices
88
+
89
+ ```python
90
+ from xippios.eurostat import get_cross_section, get_latest_period, get_series
91
+
92
+ milk = {"milkitem": "PRD", "dairyprod": "D1110D", "unit": "THS_T"}
93
+ series = get_series("apro_mk_cola", {**milk, "geo": "AT"}, since="2015", until="2023")
94
+ [(o.codes["time"], o.value) for o in series.data] # [("2015", 3102.56), ..., ("2023", 3242.85)]
95
+ latest = get_latest_period("apro_mk_cola", {**milk, "geo": "AT"})
96
+ latest.data[0].codes["time"], latest.data[0].value # ("2025", 3503.31)
97
+ section = get_cross_section("apro_mk_cola", "2023", milk) # every geo code the dataset holds
98
+ len(section.data) # 36: the geo codes with a value or a status in 2023
99
+ section.meta.request # {"dataset": "apro_mk_cola", "filters": {..., "time": "2023"}, "lang": "EN"}
100
+ ```
101
+
102
+ Each slice sends one `get_data` request and returns the cube's observations as a list
103
+ of `Observation`, with `get_data`'s `meta`: `meta.request` names what was sent
104
+ (`since_time_period`, `last_time_period`, the `time` filter).
105
+ `get_series(dataset, filters, *, since=None, until=None, lang=Lang.EN)` wants every
106
+ dimension but time pinned to one code; an answer that spans more than one series raises
107
+ `InvalidRequestError` naming each dimension still open and its codes.
108
+ `get_latest_period(dataset, filters=None, *, lang=Lang.EN)` asks for `lastTimePeriod=1`,
109
+ the most recent period, and `get_cross_section(dataset, period, filters=None, *,
110
+ lang=Lang.EN)` for `time=<period>`; both return any number of series in cube order. Each
111
+ refuses a `time` filter before sending, since it selects the periods itself, and
112
+ `get_cross_section` an empty `period`. A code that matches nothing gives an empty list.
113
+ Over MCP each slice keeps the family's cap, 200 rows or 64 KB, with a note of its own on
114
+ how to see the rest.
115
+
116
+ ### Datasets and codes
117
+
118
+ ```python
119
+ from xippios.eurostat import list_codes, list_datasets
120
+
121
+ milk = list_datasets(search="milk") # 18 leaves of the table of contents
122
+ cola = list_datasets(search="apro_mk_cola").data[0]
123
+ cola.code, cola.type # ("apro_mk_cola", "dataset")
124
+ cola.title # "Production of main cows' milk products - annual data"
125
+ cola.path # "Database by themes > Agriculture, forestry and fisheries > ... > Milk and milk products"
126
+ cola.last_update, cola.data_start, cola.data_end # ("05.10.2026", "1968", "2025"), as printed
127
+ milk.meta.vintage, milk.meta.published_at # "20261027T1000", 2026-10-27 10:00 without a zone
128
+ austria = list_codes("geo", search="austria")
129
+ austria.data # [Code(code="AT", label="Austria")]
130
+ austria.meta.vintage, austria.meta.published_at # "28.0", 2026-03-25 23:00+01:00
131
+ list_codes("unit", search="THS_T").data[0] # Code(code="THS_T", label="Thousand tonnes")
132
+ ```
133
+
134
+ Both answer from lists packaged with this version, without a request: `meta.retrieved_at`
135
+ is when the package fetched the list, `meta.endpoint` the operation it came from.
136
+ `list_datasets(search=None)` reads Eurostat's table of contents (`catalogue/toc/xml`):
137
+ every dataset and pre-defined table of the navigation tree, over 10,000 leaves, one per
138
+ listing in the tree, each with its code, type, English title, the folders above it
139
+ (`path`, joined with `" > "`), its last update and structure change, its first and last
140
+ period and its number of values as Eurostat prints them. `meta.vintage` is the table of
141
+ contents' `creationDate` as printed and `meta.published_at` the same time, which
142
+ Eurostat prints without a zone, so `meta.published_at_naive` is set.
143
+ `list_codes(codelist, search=None)` reads one of twelve SDMX codelists
144
+ (`sdmx/2.1/codelist/ESTAT/<ID>`, English labels): FREQ, GEO, UNIT, CROPS, STRUCPRO,
145
+ MILKITEM, DAIRYPROD, STATINFO, LEG_FORM, FARMTYPE, SO_EUR and UAAREA, the codelists of
146
+ the dimensions of apro_cpnh1, apro_mk_cola and ef_m_farmleg, named as the dimension is
147
+ (`"geo"`, case-insensitive). `meta.vintage` is the codelist's version and
148
+ `meta.published_at` its last update. Another name raises `UnknownCode` naming the
149
+ closest packaged codelists. `search` keeps the records whose code or title (label)
150
+ contains the text, ignoring case. Over MCP `eurostat_list_datasets` keeps the family's
151
+ cap and `eurostat_list_codes` takes up to 1,000 codes within the family's 64 KB, so
152
+ every packaged codelist but GEO comes whole; both notes name `search`.
153
+
154
+ ### Bulk download
155
+
156
+ ```python
157
+ from pathlib import Path
158
+
159
+ from xippios.eurostat import download_dataset
160
+ from xippios.eurostat.parse import parse_sdmx_csv
161
+
162
+ milk = download_dataset(
163
+ "apro_mk_cola", "A...THS_T.AT", since="2022", until="2023", dest=Path("milk.csv.gz")
164
+ )
165
+ milk.data.path # PosixPath("milk.csv.gz"): the gzip-compressed SDMX-CSV file
166
+ milk.data.bytes # 335
167
+ milk.data.filename # "estat_apro_mk_cola_filtered_en.csv.gz", Eurostat's name for it
168
+ milk.meta.vintage # "05/10/26 23:00:00": LAST UPDATE as printed, day first
169
+ milk.meta.published_at # 2026-10-05 23:00 without a zone, meta.published_at_naive set
170
+ rows = parse_sdmx_csv(milk.data.path) # one SdmxCsvRow per observation, read lazily
171
+ first = next(rows)
172
+ first.dimensions # {"freq": "A", "milkitem": "PRD", "dairyprod": "D1110D", ...}
173
+ first.time_period, first.obs_value # ("2022", Decimal("3247.05"))
174
+ ```
175
+
176
+ `download_dataset(dataset, key="", *, since=None, until=None, last_n_observations=None,
177
+ dest)` sends one SDMX 2.1 data query (`dataQuery`, `sdmx/2.1/data/{flowRef}/{key}`) with
178
+ `format=SDMX-CSV` and `compressed=true` and streams the answer to `dest`, never holding
179
+ it in memory or caching it; it returns core's `Downloaded` (path, size, content type,
180
+ Eurostat's file name, retrieval time). It is a bulk task: Python only, so the MCP server
181
+ and the router skip it and no agent is handed a file path. `key` is Eurostat's series
182
+ key, the dimensions but time in the dataset's order, dot-separated, empty for every code
183
+ of a dimension, `+` between codes (`"A...THS_T.AT+DE"`); `""` downloads the whole
184
+ dataset.
185
+ `since`, `until` and `last_n_observations` are Eurostat's `startPeriod`, `endPeriod` and
186
+ `lastNObservations`. `meta.vintage` is the file's `LAST UPDATE` as printed and
187
+ `meta.published_at` the same time, which Eurostat prints without a zone; both are `None`
188
+ for a file without a row. A query Eurostat would answer asynchronously, or refuses as
189
+ too large, raises `InvalidRequestError` naming how to narrow it. `parse_sdmx_csv(path)`
190
+ reads the file, gzip-compressed or plain, row by row: each `SdmxCsvRow` has the
191
+ `dataflow`, the `last_update`, the `dimensions` in column order, the `time_period`, the
192
+ `obs_value` as a `Decimal` (`None` when empty), `obs_flag`, `conf_status` and any other
193
+ `attributes` of the dataset, as Eurostat prints them.
194
+
195
+ ## MCP
196
+
197
+ ```json
198
+ {
199
+ "mcpServers": {
200
+ "eurostat": {
201
+ "command": "uvx",
202
+ "args": ["--from", "xippios-eurostat[mcp]", "xippios-eurostat-mcp"]
203
+ }
204
+ }
205
+ }
206
+ ```
207
+
208
+ Tools are read-only and named `eurostat_<verb>_<noun>`. Results are capped, at
209
+ 200 rows or 64 KB unless a tool has a cap of its own, with a note on how to see the rest.
210
+ `--http` serves streamable HTTP instead of stdio.
211
+
212
+ ## Status
213
+
214
+ <!-- Core's family check (tests/test_family.py) reads this table: keep the "## Status"
215
+ heading and the "Task function" column. Each row's Task function cell starts with the
216
+ task's name in backticks, alone or as its call (`get_data(code, year)`); several tasks in
217
+ one row are backticked names separated by commas; prose may follow. The tables list
218
+ exactly tasks.__all__. -->
219
+
220
+ | Upstream operation | Task function | MCP tool | Status |
221
+ | --- | --- | --- | --- |
222
+ | `getData` (`statistics/1.0/data/{datasetCode}`) | `get_data(dataset, filters)`, a JSON-stat cube | `eurostat_get_data` | alpha |
223
+ | `getData` with `sinceTimePeriod` and `untilTimePeriod` | `get_series(dataset, filters, since, until)`, one series as observations in cube order, which runs oldest period first in every recorded cube | `eurostat_get_series` | alpha |
224
+ | `getData` with `lastTimePeriod=1` | `get_latest_period(dataset, filters)`, the observations of the most recent period | `eurostat_get_latest_period` | alpha |
225
+ | `getData` with `time` | `get_cross_section(dataset, period, filters)`, the observations of one period | `eurostat_get_cross_section` | alpha |
226
+ | `getTocXml` (`catalogue/toc/xml`), packaged | `list_datasets(search)`, the datasets and tables of the table of contents | `eurostat_list_datasets` | alpha |
227
+ | `codeListQuery` (`sdmx/2.1/codelist/ESTAT/{resourceID}`), packaged | `list_codes(codelist, search)`, the codes of one of twelve codelists | `eurostat_list_codes` | alpha |
228
+ | `dataQuery` (`sdmx/2.1/data/{flowRef}/{key}`), SDMX-CSV | `download_dataset(dataset, key, dest)`, a gzip-compressed SDMX-CSV file on disk | none: a bulk task, Python only, which the adapters skip | alpha |
229
+
230
+ Version 0.1.0 covers these seven tasks on Eurostat's main dissemination API,
231
+ `https://ec.europa.eu/eurostat/api/dissemination`. Not covered: the Comext and Prodcom
232
+ datasets (codes with the `DS-` prefix), which Eurostat serves from another base URL;
233
+ polling an asynchronous answer, which is refused with how to narrow the query; SDMX-ML
234
+ and TSV; codelists other than the twelve packaged ones, which `list_codes` refuses
235
+ naming the closest.
236
+
237
+ ## Upstream terms and attribution
238
+
239
+ Data comes from Eurostat dissemination API (https://ec.europa.eu/eurostat/web/main/data/database) under its own terms of use;
240
+ this package adds no rights to it. Documentation snapshot and its attribution,
241
+ Eurostat's reuse and citation lines among them: `docs/upstream/FETCHED.md`.
242
+
243
+ ## Licence
244
+
245
+ Apache-2.0. See [LICENSE](LICENSE).