overture-dataset-configs 1.0.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 (71) hide show
  1. overture_dataset_configs-1.0.0/.python-version +1 -0
  2. overture_dataset_configs-1.0.0/LICENSE +21 -0
  3. overture_dataset_configs-1.0.0/PKG-INFO +71 -0
  4. overture_dataset_configs-1.0.0/README.md +48 -0
  5. overture_dataset_configs-1.0.0/overture_dataset_configs/__init__.py +39 -0
  6. overture_dataset_configs-1.0.0/overture_dataset_configs/attribution.py +220 -0
  7. overture_dataset_configs-1.0.0/overture_dataset_configs/dataset.py +360 -0
  8. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/alltheplaces.json +51 -0
  9. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/birdeye.json +51 -0
  10. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/brightquery.json +120 -0
  11. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/byggoastofnun.json +54 -0
  12. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/crab.json +54 -0
  13. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/cuzk.json +54 -0
  14. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/dac.json +51 -0
  15. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/dados_abertos.json +90 -0
  16. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/esa.json +47 -0
  17. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/esri.json +86 -0
  18. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/foursquare.json +51 -0
  19. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/geoboundaries.json +1572 -0
  20. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/globathy.json +47 -0
  21. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/google.json +47 -0
  22. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/gurs.json +54 -0
  23. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/ibge.json +50 -0
  24. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/icar.json +54 -0
  25. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/ign_es.json +47 -0
  26. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/kartverket.json +54 -0
  27. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/krick.json +51 -0
  28. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/linz.json +98 -0
  29. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/meta.json +51 -0
  30. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/microsoft.json +129 -0
  31. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/ncei.json +47 -0
  32. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/nyc_dcp.json +68 -0
  33. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/open_addresses.json +17261 -0
  34. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/opentravel.json +53 -0
  35. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/osm.json +129 -0
  36. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/overture.json +49 -0
  37. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/pdok.json +54 -0
  38. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/pinmeto.json +51 -0
  39. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/renderseo.json +51 -0
  40. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/stadfangaskra.json +47 -0
  41. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/tomtom.json +47 -0
  42. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/uberall.json +52 -0
  43. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/us_census_bureau.json +67 -0
  44. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/us_dot.json +106 -0
  45. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/usgs.json +47 -0
  46. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/vancouver.json +47 -0
  47. overture_dataset_configs-1.0.0/overture_dataset_configs/datasets/zenodo.json +59 -0
  48. overture_dataset_configs-1.0.0/overture_dataset_configs/license_policy.json +41 -0
  49. overture_dataset_configs-1.0.0/overture_dataset_configs/license_policy.py +104 -0
  50. overture_dataset_configs-1.0.0/overture_dataset_configs/schema.py +258 -0
  51. overture_dataset_configs-1.0.0/overture_dataset_configs/spdx.py +75 -0
  52. overture_dataset_configs-1.0.0/overture_dataset_configs.egg-info/PKG-INFO +71 -0
  53. overture_dataset_configs-1.0.0/overture_dataset_configs.egg-info/SOURCES.txt +69 -0
  54. overture_dataset_configs-1.0.0/overture_dataset_configs.egg-info/dependency_links.txt +1 -0
  55. overture_dataset_configs-1.0.0/overture_dataset_configs.egg-info/requires.txt +8 -0
  56. overture_dataset_configs-1.0.0/overture_dataset_configs.egg-info/scm_file_list.json +66 -0
  57. overture_dataset_configs-1.0.0/overture_dataset_configs.egg-info/scm_version.json +8 -0
  58. overture_dataset_configs-1.0.0/overture_dataset_configs.egg-info/top_level.txt +1 -0
  59. overture_dataset_configs-1.0.0/pyproject.toml +58 -0
  60. overture_dataset_configs-1.0.0/setup.cfg +4 -0
  61. overture_dataset_configs-1.0.0/tests/conftest.py +142 -0
  62. overture_dataset_configs-1.0.0/tests/test_attribution.py +214 -0
  63. overture_dataset_configs-1.0.0/tests/test_cli.py +35 -0
  64. overture_dataset_configs-1.0.0/tests/test_configs.py +36 -0
  65. overture_dataset_configs-1.0.0/tests/test_dataset.py +306 -0
  66. overture_dataset_configs-1.0.0/tests/test_license_policy.py +91 -0
  67. overture_dataset_configs-1.0.0/tests/test_policy.py +28 -0
  68. overture_dataset_configs-1.0.0/tests/test_schema.py +379 -0
  69. overture_dataset_configs-1.0.0/tests/test_semantics.py +105 -0
  70. overture_dataset_configs-1.0.0/tests/test_spdx.py +61 -0
  71. overture_dataset_configs-1.0.0/uv.lock +1382 -0
@@ -0,0 +1 @@
1
+ 3.11
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Overture Maps
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,71 @@
1
+ Metadata-Version: 2.4
2
+ Name: overture-dataset-configs
3
+ Version: 1.0.0
4
+ Summary: Dataset configs and license policy for Overture providers, with loaders, validation and attribution rendering.
5
+ Author: Overture Maps Foundation
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/OvertureMaps/overture-providers
8
+ Project-URL: Source, https://github.com/OvertureMaps/overture-providers/tree/main/packages/overture_dataset_configs
9
+ Project-URL: Issues, https://github.com/OvertureMaps/overture-providers/issues
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Requires-Python: >=3.11
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: pydantic>=2.0
16
+ Requires-Dist: botocore>=1.31
17
+ Provides-Extra: dev
18
+ Requires-Dist: pytest>=9.1.1; extra == "dev"
19
+ Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
20
+ Requires-Dist: overture-core>=1.5.0; extra == "dev"
21
+ Requires-Dist: license-expression>=30.0; extra == "dev"
22
+ Dynamic: license-file
23
+
24
+ # overture-dataset-configs
25
+
26
+ [![PyPI](https://img.shields.io/pypi/v/overture-dataset-configs?color=4051CC&labelColor=001A39)](https://pypi.org/project/overture-dataset-configs/)
27
+ [![Test Python](https://github.com/OvertureMaps/overture-providers/actions/workflows/test_python.yml/badge.svg?branch=main)](https://github.com/OvertureMaps/overture-providers/actions/workflows/test_python.yml)
28
+ [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-4051CC?labelColor=001A39)](https://github.com/OvertureMaps/overture-providers/blob/main/packages/overture_dataset_configs/pyproject.toml)
29
+ [![License: MIT](https://img.shields.io/badge/license-MIT-05A5AF?labelColor=001A39)](https://github.com/OvertureMaps/overture-providers/blob/main/packages/overture_dataset_configs/LICENSE)
30
+
31
+ Dataset configs for Overture providers, the per-theme license policy, and the classes that validate, load and render them.
32
+
33
+ ```python
34
+ from overture_dataset_configs import load_config, provider_names
35
+ from overture_dataset_configs.dataset import Dataset
36
+ from overture_dataset_configs.license_policy import load_policy
37
+
38
+ provider_names() # ["alltheplaces", "birdeye", ...]
39
+ load_config("linz") # raw dict from overture_dataset_configs/datasets/linz.json
40
+
41
+ ds = Dataset.from_name("osm", "planet") # packaged configs by default
42
+ ds.dataset_id, ds.license_type, ds.download_url
43
+
44
+ load_policy().allowed("places") # {"CDLA-Permissive-2.0", ...}
45
+ ```
46
+
47
+ | Module | Scope |
48
+ | --- | --- |
49
+ | `dataset` | `Dataset`: one provider/resource config, with its collection, ingestion and matching sections. |
50
+ | `schema` | Strict pydantic models for the config files; `python -m overture_dataset_configs.schema <files>` validates from the shell. |
51
+ | `license_policy` | `LicensePolicy`: validating and querying the per-theme license allowlist. |
52
+ | `attribution` | Flattening configs into license entries and rendering them as Markdown or plain text. |
53
+ | `spdx` | Fetching canonical SPDX license texts from a pinned `license-list-data` release. |
54
+
55
+ For a command line, overture-core's `overture-datasets` CLI validates and renders these configs.
56
+
57
+ ## Concepts
58
+
59
+ - **Provider**: an organization Overture takes data from, such as Land Information New Zealand.
60
+ - **Dataset** (a `resources` entry): one licensed collection of data from a provider, such as a single layer or file set. A provider can have many datasets, and each has its own license, coverage and refresh cadence.
61
+ - **License policy**: per theme, the license identifiers Overture accepts. Every dataset's license type should appear in it.
62
+
63
+ For how themes, attribution, and licensing work across Overture data, see the [Overture documentation](https://docs.overturemaps.org/): the [schema](https://docs.overturemaps.org/schema/) for themes, and the [attribution page](https://docs.overturemaps.org/attribution/) for the terms published with each release.
64
+
65
+ Each file in [`overture_dataset_configs/datasets`](https://github.com/OvertureMaps/overture-providers/tree/main/packages/overture_dataset_configs/overture_dataset_configs/datasets) describes one provider and its datasets. Files are named `<provider_label>.json` and looked up by file stem. The field reference is [`schema.py`](https://github.com/OvertureMaps/overture-providers/blob/main/packages/overture_dataset_configs/overture_dataset_configs/schema.py), which also rejects unknown keys.
66
+
67
+ ## Contributing
68
+
69
+ 1. Edit or add a file, then run `uv sync --extra dev` and `uv run pytest` from this directory. The tests validate every file against the schema, plus semantic checks (license ids and URLs, attribution, URL pairs), and run the configs through the `overture-datasets` CLI (`validate --policy`, `license`).
70
+ 2. A new field needs a matching change to `schema.py` in the same PR.
71
+ 3. Provider and resource labels feed dataset IDs and S3 paths, so don't rename them.
@@ -0,0 +1,48 @@
1
+ # overture-dataset-configs
2
+
3
+ [![PyPI](https://img.shields.io/pypi/v/overture-dataset-configs?color=4051CC&labelColor=001A39)](https://pypi.org/project/overture-dataset-configs/)
4
+ [![Test Python](https://github.com/OvertureMaps/overture-providers/actions/workflows/test_python.yml/badge.svg?branch=main)](https://github.com/OvertureMaps/overture-providers/actions/workflows/test_python.yml)
5
+ [![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-4051CC?labelColor=001A39)](https://github.com/OvertureMaps/overture-providers/blob/main/packages/overture_dataset_configs/pyproject.toml)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-05A5AF?labelColor=001A39)](https://github.com/OvertureMaps/overture-providers/blob/main/packages/overture_dataset_configs/LICENSE)
7
+
8
+ Dataset configs for Overture providers, the per-theme license policy, and the classes that validate, load and render them.
9
+
10
+ ```python
11
+ from overture_dataset_configs import load_config, provider_names
12
+ from overture_dataset_configs.dataset import Dataset
13
+ from overture_dataset_configs.license_policy import load_policy
14
+
15
+ provider_names() # ["alltheplaces", "birdeye", ...]
16
+ load_config("linz") # raw dict from overture_dataset_configs/datasets/linz.json
17
+
18
+ ds = Dataset.from_name("osm", "planet") # packaged configs by default
19
+ ds.dataset_id, ds.license_type, ds.download_url
20
+
21
+ load_policy().allowed("places") # {"CDLA-Permissive-2.0", ...}
22
+ ```
23
+
24
+ | Module | Scope |
25
+ | --- | --- |
26
+ | `dataset` | `Dataset`: one provider/resource config, with its collection, ingestion and matching sections. |
27
+ | `schema` | Strict pydantic models for the config files; `python -m overture_dataset_configs.schema <files>` validates from the shell. |
28
+ | `license_policy` | `LicensePolicy`: validating and querying the per-theme license allowlist. |
29
+ | `attribution` | Flattening configs into license entries and rendering them as Markdown or plain text. |
30
+ | `spdx` | Fetching canonical SPDX license texts from a pinned `license-list-data` release. |
31
+
32
+ For a command line, overture-core's `overture-datasets` CLI validates and renders these configs.
33
+
34
+ ## Concepts
35
+
36
+ - **Provider**: an organization Overture takes data from, such as Land Information New Zealand.
37
+ - **Dataset** (a `resources` entry): one licensed collection of data from a provider, such as a single layer or file set. A provider can have many datasets, and each has its own license, coverage and refresh cadence.
38
+ - **License policy**: per theme, the license identifiers Overture accepts. Every dataset's license type should appear in it.
39
+
40
+ For how themes, attribution, and licensing work across Overture data, see the [Overture documentation](https://docs.overturemaps.org/): the [schema](https://docs.overturemaps.org/schema/) for themes, and the [attribution page](https://docs.overturemaps.org/attribution/) for the terms published with each release.
41
+
42
+ Each file in [`overture_dataset_configs/datasets`](https://github.com/OvertureMaps/overture-providers/tree/main/packages/overture_dataset_configs/overture_dataset_configs/datasets) describes one provider and its datasets. Files are named `<provider_label>.json` and looked up by file stem. The field reference is [`schema.py`](https://github.com/OvertureMaps/overture-providers/blob/main/packages/overture_dataset_configs/overture_dataset_configs/schema.py), which also rejects unknown keys.
43
+
44
+ ## Contributing
45
+
46
+ 1. Edit or add a file, then run `uv sync --extra dev` and `uv run pytest` from this directory. The tests validate every file against the schema, plus semantic checks (license ids and URLs, attribution, URL pairs), and run the configs through the `overture-datasets` CLI (`validate --policy`, `license`).
47
+ 2. A new field needs a matching change to `schema.py` in the same PR.
48
+ 3. Provider and resource labels feed dataset IDs and S3 paths, so don't rename them.
@@ -0,0 +1,39 @@
1
+ """Public Overture dataset license/policy configs, addressable by provider name."""
2
+
3
+ import json
4
+ from importlib.resources import files
5
+ from importlib.resources.abc import Traversable
6
+ from typing import Any
7
+
8
+ _DATASETS = files(__package__) / "datasets"
9
+
10
+
11
+ def _path(provider: str) -> Traversable:
12
+ return _DATASETS / f"{provider}.json"
13
+
14
+
15
+ def provider_names() -> list[str]:
16
+ """Return the sorted provider labels that have a packaged config."""
17
+ return sorted(
18
+ p.name.removesuffix(".json")
19
+ for p in _DATASETS.iterdir()
20
+ if p.name.endswith(".json")
21
+ )
22
+
23
+
24
+ def load_config(provider: str) -> dict[str, Any]:
25
+ """Return the parsed config for ``provider`` (the JSON file stem).
26
+
27
+ Raises ``KeyError`` if no config exists for that provider.
28
+ """
29
+ path = _path(provider)
30
+ if "/" in provider or "\\" in provider or not path.is_file():
31
+ raise KeyError(f"unknown provider: {provider!r}")
32
+ return json.loads(path.read_text(encoding="utf-8"))
33
+
34
+
35
+ def load_license_policy() -> dict[str, list[str]]:
36
+ """Return the per-theme allowlist of license identifiers."""
37
+ return json.loads(
38
+ (files(__package__) / "license_policy.json").read_text(encoding="utf-8")
39
+ )
@@ -0,0 +1,220 @@
1
+ """License / attribution entries derived from dataset config files.
2
+
3
+ A *license entry* is the flat dict shape written to a release's
4
+ ``license.json``. This module owns how such an entry is extracted from a
5
+ provider/resource pair and how a list of entries is rendered as plain text or
6
+ Markdown.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import re
12
+ from typing import Any
13
+
14
+ from overture_dataset_configs.schema import DatasetFile
15
+
16
+
17
+ def license_entry(provider: dict[str, Any], resource: dict[str, Any]) -> dict[str, Any]:
18
+ """Flatten a provider dict plus one of its resource dicts into a license entry.
19
+
20
+ Both arguments follow the dataset file shape (see ``schema.DatasetFile``);
21
+ missing optional sections degrade to empty strings / lists rather than raising.
22
+ A license ``type`` of ``None`` is kept as ``None``, as the pipeline artifact has always emitted it.
23
+ """
24
+ collection = resource.get("collection") or {}
25
+ license_data = collection.get("license") or {}
26
+ coverage = collection.get("coverage") or {}
27
+
28
+ return {
29
+ "provider_name": provider["name"],
30
+ "provider_label": provider["label"],
31
+ "provider_url": (provider.get("url") or {}).get("primary", ""),
32
+ "resource_name": resource["name"],
33
+ "resource_label": resource["label"],
34
+ "license_type": license_data.get("type", ""),
35
+ "license_url": (license_data.get("url") or {}).get("primary", ""),
36
+ "requires_attribution": license_data.get("requires_attribution", False),
37
+ "attribution": license_data.get("attribution", ""),
38
+ "coverage_description": coverage.get("description", ""),
39
+ "coverage_areas": [a.get("iso_3166_1", "") for a in coverage.get("areas", [])],
40
+ }
41
+
42
+
43
+ def entries_from_file(
44
+ dataset: DatasetFile, resources: set[str] | None = None
45
+ ) -> list[dict[str, Any]]:
46
+ """License entries for a validated dataset file.
47
+
48
+ ``resources`` restricts output to the given resource labels; ``None``
49
+ means every resource in the file. Unknown labels raise ``KeyError``.
50
+ """
51
+ provider = dataset.provider.model_dump()
52
+ available = {r.label: r for r in dataset.resources}
53
+ if resources is None:
54
+ selected = list(dataset.resources)
55
+ else:
56
+ missing = sorted(resources - available.keys())
57
+ if missing:
58
+ raise KeyError(
59
+ f"resource(s) {missing} not found in provider '{dataset.provider.label}'; "
60
+ f"available: {sorted(available)}"
61
+ )
62
+ selected = [available[label] for label in sorted(resources)]
63
+ entries = []
64
+ for r in selected:
65
+ resource = r.model_dump()
66
+ entry = license_entry(provider, resource)
67
+ license_data = (resource.get("collection") or {}).get("license") or {}
68
+ entry["notice"] = license_data.get("text") or ""
69
+ entries.append(entry)
70
+ return entries
71
+
72
+
73
+ def _display_name(entry: dict[str, Any]) -> str:
74
+ if entry.get("requires_attribution") and entry.get("attribution"):
75
+ return entry["attribution"]
76
+ return entry.get("resource_name", "")
77
+
78
+
79
+ def render_attribution_bullet(entry: dict[str, Any]) -> str:
80
+ """One Markdown bullet: ``- [name](url). Available under [SPDX](license_url).``"""
81
+ name = _display_name(entry)
82
+ url = entry.get("provider_url") or ""
83
+ license_type = entry.get("license_type") or ""
84
+ license_url = entry.get("license_url") or ""
85
+
86
+ name_part = f"[{name}]({url})" if url else name
87
+ if license_type and license_url:
88
+ license_part = f" Available under [{license_type}]({license_url})."
89
+ elif license_type:
90
+ license_part = f" Available under {license_type}."
91
+ else:
92
+ license_part = ""
93
+ return f"- {name_part}.{license_part}"
94
+
95
+
96
+ def _sorted(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
97
+ return sorted(
98
+ entries, key=lambda e: (e["provider_name"].lower(), e["resource_name"].lower())
99
+ )
100
+
101
+
102
+ _MD_LINK = re.compile(r"\[([^\]]+)\]\(((?:[^()\s]|\([^()\s]*\))+)\)")
103
+
104
+
105
+ def _plain_links(text: str) -> str:
106
+ """Rewrite Markdown ``[label](url)`` links as ``label <url>``."""
107
+ return _MD_LINK.sub(r"\1 <\2>", text)
108
+
109
+
110
+ def _notices(entries: list[dict[str, Any]]) -> list[tuple[str, str]]:
111
+ """``(heading, notice text)`` per provider/notice pair, in sorted order, deduplicated."""
112
+ out: list[tuple[str, str]] = []
113
+ seen: set[tuple[str, str]] = set()
114
+ for entry in _sorted(entries):
115
+ notice = (entry.get("notice") or "").strip()
116
+ key = (entry["provider_label"], notice)
117
+ if not notice or key in seen:
118
+ continue
119
+ seen.add(key)
120
+ provider, resource = entry["provider_name"], entry["resource_name"]
121
+ heading = provider if provider == resource else f"{provider}: {resource}"
122
+ out.append((heading, notice))
123
+ return out
124
+
125
+
126
+ def render_markdown(
127
+ entries: list[dict[str, Any]],
128
+ title: str = "Data Attribution",
129
+ *,
130
+ attribution: bool = True,
131
+ notices: bool = False,
132
+ license_texts: dict[str, str] | None = None,
133
+ ) -> str:
134
+ """Render entries as a Markdown document grouped by provider.
135
+
136
+ Resources from one provider that render to an identical attribution line
137
+ collapse to one bullet. ``notices`` adds each resource's license notice
138
+ text; ``license_texts`` (SPDX id -> text) appends one copy of each license.
139
+ """
140
+ if not entries:
141
+ return ""
142
+ lines = [f"# {title}", ""]
143
+ if attribution:
144
+ current_provider = None
145
+ seen: set[str] = set()
146
+ for entry in _sorted(entries):
147
+ if entry["provider_label"] != current_provider:
148
+ current_provider = entry["provider_label"]
149
+ seen = set()
150
+ if len(lines) > 2:
151
+ lines.append("")
152
+ lines.append(f"## {entry['provider_name']}")
153
+ lines.append("")
154
+ bullet = render_attribution_bullet(entry)
155
+ if bullet not in seen:
156
+ seen.add(bullet)
157
+ lines.append(bullet)
158
+ notice_items = _notices(entries) if notices else []
159
+ if notice_items:
160
+ lines += ["", "## Notices", ""] if attribution else ["## Notices", ""]
161
+ for heading, text in notice_items:
162
+ lines += [f"### {heading}", "", text, ""]
163
+ lines.pop()
164
+ if license_texts:
165
+ if len(lines) > 2:
166
+ lines.append("")
167
+ lines += ["## License Texts", ""]
168
+ for spdx_id, text in license_texts.items():
169
+ lines += [f"### {spdx_id}", "", "~~~~text", text, "~~~~", ""]
170
+ lines.pop()
171
+ return "\n".join(lines) + "\n"
172
+
173
+
174
+ def render_text(
175
+ entries: list[dict[str, Any]],
176
+ title: str = "Data Attribution",
177
+ *,
178
+ attribution: bool = True,
179
+ notices: bool = False,
180
+ license_texts: dict[str, str] | None = None,
181
+ ) -> str:
182
+ """Render entries as plain text, one block per resource.
183
+
184
+ See ``render_markdown`` for ``notices`` and ``license_texts``.
185
+ """
186
+ if not entries:
187
+ return ""
188
+ blocks = [title, "=" * len(title)]
189
+ for entry in _sorted(entries) if attribution else []:
190
+ block = [
191
+ "",
192
+ _display_name(entry),
193
+ f" Provider: {entry['provider_name']}"
194
+ + (f" <{entry['provider_url']}>" if entry.get("provider_url") else ""),
195
+ f" Resource: {entry['resource_name']}",
196
+ ]
197
+ if entry.get("license_type"):
198
+ block.append(
199
+ f" License: {entry['license_type']}"
200
+ + (f" <{entry['license_url']}>" if entry.get("license_url") else "")
201
+ )
202
+ if entry.get("coverage_description"):
203
+ block.append(f" Coverage: {entry['coverage_description']}")
204
+ blocks.extend(block)
205
+ notice_items = _notices(entries) if notices else []
206
+ if notice_items:
207
+ blocks += ["", "Notices", "-------"]
208
+ for heading, text in notice_items:
209
+ blocks += ["", heading, "", _plain_links(text)]
210
+ if license_texts:
211
+ blocks += ["", "License Texts", "-------------"]
212
+ for spdx_id, text in license_texts.items():
213
+ blocks += ["", spdx_id, "", text]
214
+ return "\n".join(blocks) + "\n"
215
+
216
+
217
+ RENDERERS = {
218
+ "md": render_markdown,
219
+ "txt": render_text,
220
+ }