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.
- xippios_eurostat-0.1.0/.gitignore +23 -0
- xippios_eurostat-0.1.0/CHANGELOG.md +137 -0
- xippios_eurostat-0.1.0/LICENSE +201 -0
- xippios_eurostat-0.1.0/PKG-INFO +245 -0
- xippios_eurostat-0.1.0/README.md +216 -0
- xippios_eurostat-0.1.0/docs/handover.md +184 -0
- xippios_eurostat-0.1.0/docs/upstream/FETCHED.md +150 -0
- xippios_eurostat-0.1.0/docs/upstream/api/async.wadl +41 -0
- xippios_eurostat-0.1.0/docs/upstream/api/catalogue.wadl +453 -0
- xippios_eurostat-0.1.0/docs/upstream/api/sdmx-rest.wadl +1442 -0
- xippios_eurostat-0.1.0/docs/upstream/api/sdmx-rest.yaml +1904 -0
- xippios_eurostat-0.1.0/docs/upstream/api/statistics-rest.wadl +130 -0
- xippios_eurostat-0.1.0/docs/upstream/samples/apro_mk_cola-json-stat.json +1 -0
- xippios_eurostat-0.1.0/docs/upstream/samples/apro_mk_cola-sdmx-csv.csv +21 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/api-statistics.md +113 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/asynchronous-api.md +251 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/catalogue-api/dcat.md +14 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/catalogue-api/toc.md +53 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/catalogue-api.md +8 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/prefixed-datasets.md +11 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/sdmx2-1/data-query.md +260 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/sdmx2-1/structure-queries.md +163 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines/sdmx2-1.md +10 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-detailed-guidelines.md +16 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-faq/tsv-format.md +196 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-faq.md +110 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-getting-started/api.md +205 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-getting-started/catalogue-api.md +107 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-getting-started/sdmx2.1.md +652 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-getting-started.md +104 -0
- xippios_eurostat-0.1.0/docs/upstream/user-guide/api-introduction.md +199 -0
- xippios_eurostat-0.1.0/pyproject.toml +104 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/__init__.py +27 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/_client.py +163 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/_version.py +10 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/api/__init__.py +14 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/api/catalogue.py +39 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/api/sdmx.py +196 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/api/statistics.py +111 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/enums.py +3 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/errors.py +153 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/http.py +18 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/mcp.py +33 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/models.py +458 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/params.py +191 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/parse/__init__.py +11 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/parse/sdmx_csv.py +173 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/py.typed +0 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/README.md +59 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/crops.json +2907 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/dairyprod.json +671 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/farmtype.json +459 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/freq.json +55 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/geo.json +17175 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/leg_form.json +119 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/lists.json +135 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/milkitem.json +75 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/so_eur.json +279 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/statinfo.json +443 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/strucpro.json +103 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/toc.json +114132 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/uaarea.json +91 -0
- xippios_eurostat-0.1.0/src/xippios/eurostat/reference/unit.json +3099 -0
- 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).
|