undata 0.1.0__tar.gz

undata-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+src/undata/_version.py
+.DS_Store
+
+# Local secrets. Never commit.
+.env

undata-0.1.0/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow
+[Semantic Versioning](https://semver.org/). Below 1.0, minor versions may change the API.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-13
+
+First release.
+
+### Added
+
+- The friendly API, for people who need numbers rather than an API:
+  `un.search`, `un.about`, `un.get`, `un.latest`, `un.countries`, `un.regions`,
+  `un.sdg.goals/targets/indicators/series`, `un.ask`, `un.save` and `un.cite`. Tables
+  have the same columns every time, with unit and source on every row.
+- Places by name: UN names, everyday names, ISO codes and regions all work, and tables
+  use UN M49 short names. Unknown names raise `PlaceNotFoundError` with suggestions;
+  names inside several countries raise `AmbiguousPlaceError`. Nothing is substituted.
+- Plain-English warnings: `MissingDataWarning` names countries with no data (never
+  zero-filled), `MixedYearsWarning` flags "latest" values from different years, and
+  `PlaceGuessedWarning` flags a place data.un.org's search box chose itself, read from
+  its own `placeSource` field.
+- `un.save` writes Excel with `data`, `sources` and `no data` sheets, or CSV.
+- Search re-ranks results so names containing all your words come first, and hides
+  series Data Commons imported from elsewhere unless `all_sources=True`.
+- Ten examples rewritten on the friendly API, and the examples page rebuilt for
+  colleagues new to data work.
+
+- Transport layer: single-line JSON bodies, GET-only observations, percent-encoded
+  relation expressions, retries on 429/502/503/504 honouring `Retry-After`, and
+  `BlockedRequestError`, which explains a 403 instead of implying an API key exists.
+- One wrapper per API route, including graph walks that follow `nextToken` past the
+  500-value page cap.
+- The dcid grammar: `parse_dcid`, `build_dcid`, `describe_dcid`, `child_countries_of`.
+- A live contract suite that pins the platform behaviours the package depends on,
+  including that variable search ranks Data Commons' older `sdg/...` copy above the
+  UN's own `undata/sdg/...` series.
+
+### Fixed
+
+- A request mentioning Western Sahara (`ESH`) is refused by the firewall on GET, which
+  made any request for Africa fail. Data is now fetched by POST, which it accepts.
+- The 403 message named only the POST triggers; it now lists all three.
+- The platform's "Latin America" region contains no countries, so it is no longer
+  offered; "Latin America and the Caribbean" is suggested instead.
+
+- Spaces in query strings are sent as `%20`. httpx sends `+`, which this server reads
+  literally, so `resolve("Viet Nam")` reached it as `Viet+Nam`.
+
+[Unreleased]: https://github.com/nerd-factory/undata/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/nerd-factory/undata/releases/tag/v0.1.0

undata-0.1.0/CITATION.cff

@@ -0,0 +1,18 @@
+cff-version: 1.2.0
+message: "If you use undata in published work, please cite it as below, and cite the agency that published the data."
+title: "undata: a Python client for the UN System Data Commons"
+type: software
+authors:
+  - family-names: Islam
+    given-names: Mafizul
+  - name: "Nerd Lab contributors"
+repository-code: "https://github.com/nerd-factory/undata"
+url: "https://nerd-factory.github.io/undata/"
+version: 0.1.0
+date-released: 2026-10-13
+license: MIT
+keywords:
+  - United Nations
+  - Data Commons
+  - SDG
+  - official statistics

undata-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mafizul Islam and the Nerd Lab contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

undata-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: undata
+Version: 0.1.0
+Summary: UN data in Python, without the guessing: a friendly, unofficial client for the UN System Data Commons (data.un.org).
+Project-URL: Homepage, https://nerd-factory.github.io/undata/
+Project-URL: Documentation, https://nerd-factory.github.io/undata/
+Project-URL: Source, https://github.com/nerd-factory/undata
+Project-URL: Issues, https://github.com/nerd-factory/undata/issues
+Project-URL: Changelog, https://github.com/nerd-factory/undata/blob/main/CHANGELOG.md
+Project-URL: Release notes, https://github.com/nerd-factory/undata/releases
+Project-URL: Field guide, https://mafiatun.github.io/un-data-commons-field-guide/
+Author-email: Mafizul Islam <islam50@un.org>
+Maintainer: Nerd Lab contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,data-commons,official-statistics,open-data,pandas,sdg,statistics,sustainable-development-goals,un-data,united-nations
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pandas>=2.2.2
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nerd-factory/nerd-lab/main/assets/logo/nerd-lab-offwhite.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/nerd-factory/nerd-lab/main/assets/logo/nerd-lab-ink.svg">
+  <img alt="NERD LAB" src="https://raw.githubusercontent.com/nerd-factory/nerd-lab/main/assets/logo/nerd-lab-offwhite.svg" width="300">
+</picture>
+
+# undata
+
+**UN data in Python, without the guessing.**
+
+[![CI](https://github.com/nerd-factory/undata/actions/workflows/ci.yml/badge.svg)](https://github.com/nerd-factory/undata/actions/workflows/ci.yml)
+[![Live API contract](https://github.com/nerd-factory/undata/actions/workflows/live.yml/badge.svg)](https://github.com/nerd-factory/undata/actions/workflows/live.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/nerd-factory/undata/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/nerd-factory/undata/blob/main/LICENSE)
+
+**[Ten examples, with real output →](https://nerd-factory.github.io/undata/)**
+
+</div>
+
+Type a country's name, get a table. undata is a Python package for the
+[UN System Data Commons](https://data.un.org), which holds statistics from 26 UN System
+entities. It is written for colleagues who need numbers for a report, not a course in APIs.
+
+> **Alpha.** It works today; the API may still change before 1.0.
+> **Unofficial.** A [Nerd Lab](https://github.com/nerd-factory) experiment, not affiliated with
+> or endorsed by the United Nations. The data belongs to the agencies that publish it.
+
+## Three lines to a spreadsheet
+
+```bash
+pip install undata
+```
+
+```python
+import undata as un
+
+table = un.get("undata/sdg/SH_STA_MORT.SEX--F", ["Bangladesh", "Viet Nam"])
+un.save(table, "maternal-mortality.xlsx")  # data on one sheet, citations on the next
+```
+
+In Google Colab, run `!pip install undata` in the first cell. For the latest unreleased
+changes: `pip install "git+https://github.com/nerd-factory/undata"`.
+
+Don't know the indicator's id? `un.search("maternal mortality")` lists matching indicators
+with their names. Copy the id from the first column.
+
+## Everything on one screen
+
+| Function | What it does |
+|---|---|
+| `un.search("words")` | Find indicators by what they measure. UN collections only, best match first. |
+| `un.about(indicator)` | What an indicator is, whose it is, its unit, and which years it covers. |
+| `un.get(indicator, countries, years)` | The numbers: one row per country and year, with unit and source. |
+| `un.latest(indicator, countries)` | Each country's most recent value, with a warning if those years differ. |
+| `un.countries(region)` · `un.regions()` | The names it knows, with UN names and ISO codes. |
+| `un.sdg.goals()` · `targets(16)` · `indicators("16.1")` · `series("16.1.2")` | Walk from an SDG goal down to indicators you can fetch. |
+| `un.ask("a question")` | See what data.un.org's search box decided, including whether it guessed the place. |
+| `un.save(table, "file.xlsx")` · `un.cite(table)` | Save to Excel or CSV with sources; write citations for a report. |
+
+Wherever a function asks for countries you can write names the way you would in an email
+(`"Viet Nam"`, `"Vietnam"`, `"VNM"`), a list of them, or a region such as `"Southern Asia"`
+or `"Africa"`. Every function explains itself: `help(un.get)`.
+
+Every table has the same columns:
+
+```
+country  iso3  year  value  unit  indicator_name  indicator  source  source_url
+```
+
+## The careful parts are built in
+
+- **It never guesses a place.** data.un.org's search box answers a question about "Bengal"
+  with figures for the United States. undata stops and says it does not know "Bengal".
+- **Gaps are named, never zero.** Countries without data are left out of the table and listed
+  in a `MissingDataWarning`, so a chart cannot show them as zeros.
+- **UN names in, UN names out.** Tables say Türkiye, Viet Nam and Côte d'Ivoire, whatever
+  spelling you typed.
+- **The source is on every row.** The same statistic can come from several agencies with
+  different numbers.
+- **Mixed years are flagged.** "Latest" means each country's own latest year; a
+  `MixedYearsWarning` says when those differ.
+- **It works where other clients fail.** The platform's firewall blocks Google's official
+  `datacommons-client` (any POST body containing `"select"`) and any GET request that
+  mentions Western Sahara (`ESH`, mistaken for a shell command). undata routes around both.
+
+Each behaviour is pinned by a test in [tests/live/](https://github.com/nerd-factory/undata/tree/main/tests/live) that runs against the real
+platform every night and opens an issue if the platform changes. Most of them were found
+while writing the [UN Data Commons Field Guide](https://mafiatun.github.io/un-data-commons-field-guide/).
+
+## Examples
+
+Ten runnable scripts in [examples/](https://github.com/nerd-factory/undata/tree/main/examples): a first table, comparing a region, a whole
+continent, an SDG target to its numbers, gaps, names, the search box, sources, Excel and
+citations, and checking an indicator. They run against the live platform every night, and
+[the examples page](https://nerd-factory.github.io/undata/) shows each with its real output.
+
+## For developers
+
+The friendly functions sit on three layers you can use directly: `undata.Transport` (the
+only code that touches the network), `undata._endpoints` (one thin wrapper per API route),
+and `undata.dcid` (the identifier grammar). [PLAN.md](https://github.com/nerd-factory/undata/blob/main/PLAN.md) covers the design and the
+road to 1.0.
+
+```bash
+git clone https://github.com/nerd-factory/undata && cd undata
+uv sync                     # Python 3.11+, installs dev tools
+uv run pytest               # unit tests and doctests, offline
+uv run pytest -m live       # pins the live platform's behaviour (network)
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+See [CONTRIBUTING.md](https://github.com/nerd-factory/undata/blob/main/CONTRIBUTING.md). Questions that feel too basic are welcome in
+[Nerd Lab Discussions](https://github.com/nerd-factory/nerd-lab/discussions); they are not
+too basic.
+
+## Licence
+
+Code: [MIT](https://github.com/nerd-factory/undata/blob/main/LICENSE). Data fetched with it is governed by the
+[UN Data Commons terms of use](https://data.un.org/undatacommons/terms-of-use) and by each
+contributing agency's own terms.

undata-0.1.0/README.md

@@ -0,0 +1,122 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/nerd-factory/nerd-lab/main/assets/logo/nerd-lab-offwhite.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/nerd-factory/nerd-lab/main/assets/logo/nerd-lab-ink.svg">
+  <img alt="NERD LAB" src="https://raw.githubusercontent.com/nerd-factory/nerd-lab/main/assets/logo/nerd-lab-offwhite.svg" width="300">
+</picture>
+
+# undata
+
+**UN data in Python, without the guessing.**
+
+[![CI](https://github.com/nerd-factory/undata/actions/workflows/ci.yml/badge.svg)](https://github.com/nerd-factory/undata/actions/workflows/ci.yml)
+[![Live API contract](https://github.com/nerd-factory/undata/actions/workflows/live.yml/badge.svg)](https://github.com/nerd-factory/undata/actions/workflows/live.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/nerd-factory/undata/blob/main/pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/nerd-factory/undata/blob/main/LICENSE)
+
+**[Ten examples, with real output →](https://nerd-factory.github.io/undata/)**
+
+</div>
+
+Type a country's name, get a table. undata is a Python package for the
+[UN System Data Commons](https://data.un.org), which holds statistics from 26 UN System
+entities. It is written for colleagues who need numbers for a report, not a course in APIs.
+
+> **Alpha.** It works today; the API may still change before 1.0.
+> **Unofficial.** A [Nerd Lab](https://github.com/nerd-factory) experiment, not affiliated with
+> or endorsed by the United Nations. The data belongs to the agencies that publish it.
+
+## Three lines to a spreadsheet
+
+```bash
+pip install undata
+```
+
+```python
+import undata as un
+
+table = un.get("undata/sdg/SH_STA_MORT.SEX--F", ["Bangladesh", "Viet Nam"])
+un.save(table, "maternal-mortality.xlsx")  # data on one sheet, citations on the next
+```
+
+In Google Colab, run `!pip install undata` in the first cell. For the latest unreleased
+changes: `pip install "git+https://github.com/nerd-factory/undata"`.
+
+Don't know the indicator's id? `un.search("maternal mortality")` lists matching indicators
+with their names. Copy the id from the first column.
+
+## Everything on one screen
+
+| Function | What it does |
+|---|---|
+| `un.search("words")` | Find indicators by what they measure. UN collections only, best match first. |
+| `un.about(indicator)` | What an indicator is, whose it is, its unit, and which years it covers. |
+| `un.get(indicator, countries, years)` | The numbers: one row per country and year, with unit and source. |
+| `un.latest(indicator, countries)` | Each country's most recent value, with a warning if those years differ. |
+| `un.countries(region)` · `un.regions()` | The names it knows, with UN names and ISO codes. |
+| `un.sdg.goals()` · `targets(16)` · `indicators("16.1")` · `series("16.1.2")` | Walk from an SDG goal down to indicators you can fetch. |
+| `un.ask("a question")` | See what data.un.org's search box decided, including whether it guessed the place. |
+| `un.save(table, "file.xlsx")` · `un.cite(table)` | Save to Excel or CSV with sources; write citations for a report. |
+
+Wherever a function asks for countries you can write names the way you would in an email
+(`"Viet Nam"`, `"Vietnam"`, `"VNM"`), a list of them, or a region such as `"Southern Asia"`
+or `"Africa"`. Every function explains itself: `help(un.get)`.
+
+Every table has the same columns:
+
+```
+country  iso3  year  value  unit  indicator_name  indicator  source  source_url
+```
+
+## The careful parts are built in
+
+- **It never guesses a place.** data.un.org's search box answers a question about "Bengal"
+  with figures for the United States. undata stops and says it does not know "Bengal".
+- **Gaps are named, never zero.** Countries without data are left out of the table and listed
+  in a `MissingDataWarning`, so a chart cannot show them as zeros.
+- **UN names in, UN names out.** Tables say Türkiye, Viet Nam and Côte d'Ivoire, whatever
+  spelling you typed.
+- **The source is on every row.** The same statistic can come from several agencies with
+  different numbers.
+- **Mixed years are flagged.** "Latest" means each country's own latest year; a
+  `MixedYearsWarning` says when those differ.
+- **It works where other clients fail.** The platform's firewall blocks Google's official
+  `datacommons-client` (any POST body containing `"select"`) and any GET request that
+  mentions Western Sahara (`ESH`, mistaken for a shell command). undata routes around both.
+
+Each behaviour is pinned by a test in [tests/live/](https://github.com/nerd-factory/undata/tree/main/tests/live) that runs against the real
+platform every night and opens an issue if the platform changes. Most of them were found
+while writing the [UN Data Commons Field Guide](https://mafiatun.github.io/un-data-commons-field-guide/).
+
+## Examples
+
+Ten runnable scripts in [examples/](https://github.com/nerd-factory/undata/tree/main/examples): a first table, comparing a region, a whole
+continent, an SDG target to its numbers, gaps, names, the search box, sources, Excel and
+citations, and checking an indicator. They run against the live platform every night, and
+[the examples page](https://nerd-factory.github.io/undata/) shows each with its real output.
+
+## For developers
+
+The friendly functions sit on three layers you can use directly: `undata.Transport` (the
+only code that touches the network), `undata._endpoints` (one thin wrapper per API route),
+and `undata.dcid` (the identifier grammar). [PLAN.md](https://github.com/nerd-factory/undata/blob/main/PLAN.md) covers the design and the
+road to 1.0.
+
+```bash
+git clone https://github.com/nerd-factory/undata && cd undata
+uv sync                     # Python 3.11+, installs dev tools
+uv run pytest               # unit tests and doctests, offline
+uv run pytest -m live       # pins the live platform's behaviour (network)
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+See [CONTRIBUTING.md](https://github.com/nerd-factory/undata/blob/main/CONTRIBUTING.md). Questions that feel too basic are welcome in
+[Nerd Lab Discussions](https://github.com/nerd-factory/nerd-lab/discussions); they are not
+too basic.
+
+## Licence
+
+Code: [MIT](https://github.com/nerd-factory/undata/blob/main/LICENSE). Data fetched with it is governed by the
+[UN Data Commons terms of use](https://data.un.org/undatacommons/terms-of-use) and by each
+contributing agency's own terms.

undata-0.1.0/examples/01_first_table.py

@@ -0,0 +1,10 @@
+"""Your first table: find an indicator by name, then get it for two countries."""
+
+import undata as un
+
+# 1. Find the indicator. Copy its id from the "indicator" column.
+print(un.search("maternal mortality").head(3).to_string(index=False))
+
+# 2. Get it. Country names work as you would write them.
+table = un.get("undata/sdg/SH_STA_MORT.SEX--F", ["Bangladesh", "Viet Nam"], years=(2020, 2023))
+print(table[["country", "year", "value", "unit"]].to_string(index=False))

undata-0.1.0/examples/02_compare_countries.py

@@ -0,0 +1,8 @@
+"""Compare the countries of a region on one indicator, each at its latest year."""
+
+import undata as un
+
+table = un.latest("undata/undphdro/HDI_hdi", "Southern Asia")
+
+ranked = table.sort_values("value", ascending=False)
+print(ranked[["country", "year", "value"]].to_string(index=False))

undata-0.1.0/examples/03_whole_region.py

@@ -0,0 +1,8 @@
+"""A whole continent in one line. Regions stand for every country in them."""
+
+import undata as un
+
+table = un.latest("undata/sdg/EG_ACS_ELEC", "Africa")  # % with access to electricity
+
+print(len(table), "countries, latest years:", sorted(table["year"].unique().tolist()))
+print(table.nsmallest(3, "value")[["country", "year", "value", "unit"]].to_string(index=False))

undata-0.1.0/examples/04_sdg_target.py

@@ -0,0 +1,11 @@
+"""From an SDG target your mandate names, to the numbers."""
+
+import undata as un
+
+print(un.sdg.indicators("16.1").to_string(index=False))
+
+series = un.sdg.series("16.1.2")
+print(series[series["total"]][["indicator", "name"]].to_string(index=False))
+
+rates = un.latest("undata/sdg/VC_DTH_TOTR", ["Ukraine", "Sudan", "Myanmar"])
+print(rates[["country", "year", "value"]].to_string(index=False))

undata-0.1.0/examples/05_missing_data.py

@@ -0,0 +1,8 @@
+"""Countries without data are named, never turned into zeros."""
+
+import undata as un
+
+table = un.latest("undata/sdg/VC_DTH_TOTR", ["Ukraine", "Norway", "Japan", "Mali"])
+
+print(table[["country", "year", "value"]].to_string(index=False))
+print("No data for:", [row["country"] for row in table.attrs["missing"]])

undata-0.1.0/examples/06_names_and_regions.py

@@ -0,0 +1,11 @@
+"""Names, UN names, codes and regions all work. Unknown names are never guessed."""
+
+import undata as un
+
+print(un.countries("Western Africa").head(4).to_string(index=False))
+
+for name in ["Vietnam", "Türkiye", "Ivory Coast", "COD", "Bengal"]:
+    try:
+        print(f"{name!r:<14} ->", un.places.resolve(name).name)
+    except un.PlaceNotFoundError as error:
+        print(f"{name!r:<14} -> {error}")

undata-0.1.0/examples/07_check_the_search_box.py

@@ -0,0 +1,9 @@
+"""See what data.un.org's search box decided, before you trust its chart."""
+
+import undata as un
+
+answer = un.ask("child mortality in Bengal")
+print(answer.place, "| guessed:", answer.place_was_guessed)
+
+answer = un.ask("child mortality in Bangladesh")
+print(answer.place, "| guessed:", answer.place_was_guessed)

undata-0.1.0/examples/08_know_your_source.py

@@ -0,0 +1,12 @@
+"""One statistic, three agencies. The source column says whose number you are using."""
+
+import undata as un
+
+MATERNAL_MORTALITY_RATIO = [
+    "undata/sdg/SH_STA_MORT.SEX--F",  # Global SDG Indicators Database
+    "undata/unicef/MNCH_MMR.SEX--F",  # UNICEF
+    "undata/undphdro/GII_mmr.SEX--F",  # UNDP Human Development Report Office
+]
+table = un.latest(MATERNAL_MORTALITY_RATIO, "Bangladesh")
+
+print(table[["source", "year", "value"]].to_string(index=False))

undata-0.1.0/examples/09_save_and_cite.py

@@ -0,0 +1,8 @@
+"""Save to Excel with a sheet of citations, and cite the data in a report."""
+
+import undata as un
+
+table = un.get("undata/sdg/SH_STA_MORT.SEX--F", "Southern Asia", years=(2015, 2023))
+
+un.save(table, "maternal-mortality.xlsx")  # sheets: data, sources
+print(un.cite(table))

undata-0.1.0/examples/10_about_an_indicator.py

@@ -0,0 +1,5 @@
+"""Before you use an indicator: what it measures, whose it is, how much data exists."""
+
+import undata as un
+
+print(un.about("undata/sdg/SH_STA_MORT.SEX--F"))

undata-0.1.0/pyproject.toml

@@ -0,0 +1,138 @@
+[build-system]
+requires = ["hatchling>=1.25", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "undata"
+dynamic = ["version"]
+description = "UN data in Python, without the guessing: a friendly, unofficial client for the UN System Data Commons (data.un.org)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mafizul Islam", email = "islam50@un.org" }]
+maintainers = [{ name = "Nerd Lab contributors" }]
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27", "pandas>=2.2.2", "openpyxl>=3.1"]
+keywords = [
+  "united-nations",
+  "un-data",
+  "data-commons",
+  "sdg",
+  "sustainable-development-goals",
+  "official-statistics",
+  "statistics",
+  "open-data",
+  "pandas",
+  "api-client",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "Natural Language :: English",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://nerd-factory.github.io/undata/"
+Documentation = "https://nerd-factory.github.io/undata/"
+Source = "https://github.com/nerd-factory/undata"
+Issues = "https://github.com/nerd-factory/undata/issues"
+Changelog = "https://github.com/nerd-factory/undata/blob/main/CHANGELOG.md"
+"Release notes" = "https://github.com/nerd-factory/undata/releases"
+"Field guide" = "https://mafiatun.github.io/un-data-commons-field-guide/"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3",
+  "pytest-cov>=6.0",
+  "respx>=0.22",
+  "hypothesis>=6.120",
+  "mypy>=1.13",
+  "ruff>=0.8",
+  "pandas-stubs>=2.2",
+]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/undata/_version.py"
+
+[tool.hatch.build.targets.sdist]
+# Tests and examples ship in the sdist so downstream packagers (conda-forge, Linux
+# distributions) can run them. The website and CI configuration do not.
+include = [
+  "/src",
+  "/tests",
+  "/examples",
+  "/README.md",
+  "/CHANGELOG.md",
+  "/CITATION.cff",
+  "/LICENSE",
+]
+
+# ── Tests ──────────────────────────────────────────────────────────────
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["src", "tests"]
+addopts = [
+  "-ra", "--strict-markers", "--strict-config", "--doctest-modules", "-m", "not live",
+]
+markers = [
+  "live: calls the real data.un.org API (run nightly, or with `-m live`)",
+]
+filterwarnings = ["error"]
+xfail_strict = true
+
+[tool.coverage.run]
+source = ["undata"]
+branch = true
+omit = ["src/undata/_version.py"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+exclude_also = ["if TYPE_CHECKING:", "@overload", "raise NotImplementedError"]
+
+# ── Lint and types ─────────────────────────────────────────────────────
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = ["src/undata/_version.py"]
+
+[tool.ruff.lint]
+select = [
+  "E", "W", "F", "I", "B", "UP", "SIM", "C4", "PT", "RUF", "N", "D", "S", "PL", "TRY",
+]
+ignore = [
+  "D105",    # magic methods are self-describing
+  "D107",    # __init__ is documented on the class
+  "PLR0913", # endpoint wrappers mirror the API's own parameters
+  "TRY003",  # long messages are the point: errors here explain what to do next
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D", "S101", "PLR2004", "PLC0415"]
+"examples/**" = ["D103", "S101"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+files = ["src", "tests"]
+exclude = ["src/undata/_version.py"]
+
+[[tool.mypy.overrides]]
+module = ["undata._version"]
+ignore_missing_imports = true