dwdopen 0.2.1__tar.gz

dwdopen-0.2.1/.claude/hooks/post-tool-call.py

@@ -0,0 +1,102 @@
+import hashlib
+import json
+import os
+import sys
+import tempfile
+from datetime import datetime, timezone
+from http.client import HTTPConnection, HTTPException
+from pathlib import Path
+import traceback
+from contextlib import closing
+from typing import Optional
+import argparse
+
+WEBSERVER_HOST = "localhost"
+WEBSERVER_ENDPOINT = "/api/provenance/call"
+PORT_FILE_SUFFIX = "-provenance-port.txt"
+
+class ProvenanceHookError(RuntimeError):
+    pass
+
+def http_request(method, host, port, location, *, body: Optional[bytes] = None, headers={}, timeout=None, wait_for_response=False) -> bytes:
+    with closing(HTTPConnection(host, port, timeout=timeout)) as connection:
+        connection.request(method, location, body=body, headers=headers)
+        if wait_for_response:
+          response = connection.getresponse()
+          responseText = response.read()
+
+def get_server_port():
+    claude_root = os.getenv("CLAUDE_PROJECT_DIR")
+    path_hash = hashlib.md5(claude_root.encode('utf-8')).hexdigest()
+    port_file = Path(tempfile.gettempdir()) / (path_hash + PORT_FILE_SUFFIX)
+
+    return int(port_file.read_text("utf-8").strip())
+
+
+def send_diff_to_webserver(file_path, timestamp_ms, wait_for_response):
+    try:
+        port = get_server_port()
+    except FileNotFoundError as e:
+        raise ProvenanceHookError(
+            f"Could not determine API port: {e.filename} does not exist") from e
+    except Exception as e:
+        raise ProvenanceHookError("Could not determine API port") from e
+
+    url = f"http://{WEBSERVER_HOST}:{port}{WEBSERVER_ENDPOINT}"
+
+    try:
+        payload = {"file_path": file_path, "timestamp": timestamp_ms}
+        return http_request(
+            "POST",
+            WEBSERVER_HOST,
+            port=port,
+            location=WEBSERVER_ENDPOINT,
+            body=json.dumps(payload, ensure_ascii=False).encode("utf-8"),
+            headers={'Content-Type': 'application/json'},
+            timeout=0.5,
+            wait_for_response=wait_for_response
+        )
+
+    except (HTTPException, OSError, ConnectionError) as e:
+        raise ProvenanceHookError(
+            f"Network error while sending diff to {url}") from e
+    except Exception as e:
+        raise ProvenanceHookError(
+            f"Unknown error while sending diff to {url}") from e
+
+
+def extract_file_path(tool_name, tool_input):
+    if tool_name in ["Write", "Edit", "MultiEdit"]:
+        return tool_input.get('file_path', 'unknown')
+    if tool_name == "NotebookEdit":
+        return tool_input.get('notebook_path', 'unknown')
+    return 'unknown'
+
+
+def excepthook(type, value, traceback_):
+    traceback.print_exception(type, value, traceback_, file=sys.stderr)
+    sys.exit(1)
+
+
+def main():
+    data = json.load(sys.stdin)
+    tool_name = data.get('tool_name', 'unknown')
+
+    p = argparse.ArgumentParser()
+    p.add_argument("--wait_for_response", default=False)
+    args = p.parse_args()
+
+    modification_tools = [
+        "Write", "Edit", "MultiEdit", "NotebookEdit"
+    ]
+
+    if tool_name in modification_tools:
+        tool_input = data.get('tool_input', {})
+        file_path = extract_file_path(tool_name, tool_input)
+        if file_path:
+            timestamp_ms = int(datetime.now(timezone.utc).timestamp() * 1000)
+            send_diff_to_webserver(file_path, timestamp_ms, args.wait_for_response)
+
+if __name__ == "__main__":
+    sys.excepthook = excepthook
+    sys.exit(main())

dwdopen-0.2.1/.claude/settings.local.json

@@ -0,0 +1,69 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(curl -s --max-time 30 https://opendata.dwd.de/weather/nwp/)",
+      "Bash(curl -s --max-time 30 https://opendata.dwd.de/weather/nwp/v1/)",
+      "Bash(curl -s --max-time 30 https://opendata.dwd.de/weather/nwp/v1/m/)",
+      "Bash(curl -s --max-time 40 https://opendata.dwd.de/weather/nwp/v1/m/icon-eu/p/)",
+      "Bash(curl -s --max-time 30 https://opendata.dwd.de/weather/nwp/v1/ -I)",
+      "Bash(curl -s --max-time 30 https://opendata.dwd.de/test/)",
+      "Bash(grep -v '^\\\\s*$')",
+      "Bash(curl -s --max-time 30 https://opendata.dwd.de/weather/)",
+      "WebFetch(domain:www.dwd.de)",
+      "WebSearch",
+      "WebFetch(domain:opendata.dwd.de)",
+      "Bash(curl -s --max-time 120 -r 0-400000 https://opendata.dwd.de/weather/nwp/content.log.bz2 -o clog.part)",
+      "Bash(bzip2 -dc clog.part)",
+      "mcp__claude_ai_Claude_Docs__guide",
+      "Bash(PYTHONPATH=src python3 -c ' *)",
+      "Read(//media/root/Data/conda/envs/**)",
+      "Bash(python3 -c \"import httpx\")",
+      "Bash(pip list *)",
+      "Bash(echo \"exit=$?\")",
+      "Bash(python3 -c ' *)",
+      "Bash(python3 -m pip install -q -e \".[dev]\")",
+      "Bash(python3 -c \"import httpx,pytest,dwdopen;print\\('ok', httpx.__version__, pytest.__version__\\)\")",
+      "Bash(conda install *)",
+      "Bash(python3 -m pip install -q -e .)",
+      "Bash(python3 -c \"import httpx,pytest,dwdopen;print\\('ok',httpx.__version__,pytest.__version__\\)\")",
+      "Bash(python3 -m pytest -q -m \"not live\")",
+      "Bash(python3 -m pytest -q -m live)",
+      "Bash(python3 -m ruff check src tests)",
+      "Bash(python3 -m mypy src)",
+      "Bash(python3 -m pip install -q ruff mypy)",
+      "Bash(python3 -m ruff check src tests --output-format=concise)",
+      "Bash(python3 -m ruff check src/dwdopen/_fileserver/catalogue.py --output-format=concise)",
+      "Bash(python3 -m pytest -q)",
+      "Bash(python3 -m ruff check src/dwdopen/_fileserver/catalogue.py src/dwdopen/nwp/catalogue.py --output-format=concise)",
+      "Bash(echo \"rc=$?\")",
+      "Bash(python3 -m ruff check src/dwdopen/_fileserver/catalogue.py src/dwdopen/nwp/catalogue.py tests/unit/test_catalogue.py --output-format=concise)",
+      "Bash(python3 -m ruff check tests/unit/test_catalogue.py --fix --output-format=concise)",
+      "Bash(python3 -m ruff check src/dwdopen/_fileserver/catalogue.py tests/unit/test_catalogue.py --output-format=concise)",
+      "Bash(git mv *)",
+      "Bash(python3 -m mypy src/dwdopen/client.py)",
+      "Bash(python3 -m ruff check src/dwdopen/client.py src/dwdopen/_fileserver/traversal.py tests/unit/test_traversal.py --output-format=concise)",
+      "Bash(python3 *)",
+      "Bash(sed -n '/def parameter\\(/,/raise NotImplementedError/p' src/dwdopen/nwp/model.py)",
+      "Bash(sed -n '/TODO levels and ensembles NYI/,/^        return Query/p' src/dwdopen/nwp/model.py)",
+      "Bash(grib_ls -p shortName,typeOfFirstFixedSurface,level lv/press.grib2)",
+      "Bash(cdo -s sinfon lv/press.grib2)",
+      "Bash(sed -i 's/^def _expand_level_cadence\\(selector: Every, kind: LevelType\\) -> list\\\\[Decimal\\\\]:$/def _expand_level_cadence\\(\\\\n selector: Every[LevelScalar], kind: LevelType\\\\n\\) -> list[Decimal]:/' src/dwdopen/nwp/query.py)",
+      "Bash(sed -i 's/^def _expand_cadence\\(selector: Every\\) -> list\\\\[timedelta\\\\]:$/def _expand_cadence\\(selector: Every[StepScalar]\\) -> list[timedelta]:/' src/dwdopen/nwp/query.py)",
+      "Bash(sed -i 's/^ LevelSelector,$/ LevelScalar,\\\\n LevelSelector,/' src/dwdopen/nwp/query.py)",
+      "Bash(sed -i 's/^ StepSelector,$/ StepScalar,\\\\n StepSelector,/' src/dwdopen/nwp/query.py)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-tool-call.py"
+          }
+        ]
+      }
+    ]
+  }
+}

dwdopen-0.2.1/.gitignore

@@ -0,0 +1,12 @@
+# IDEs
+.idea/
+.vscode/
+__pycache__/
+
+# GRIB output
+*.grib2
+*.grb2
+dist/
+
+build/
+*.egg-info/

dwdopen-0.2.1/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+Versions follow [semantic versioning](https://semver.org/).
+
+## 0.2.1
+
+- Lowered floor to Python 3.11.
+- Packaging: added project URLs.
+- Simplified some code and sugar.
+- Moved from pre-alpha to alpha, added this changelog.
+
+## 0.2.0
+
+- Add support to download ensemble members. `members=` on `select()`, taking a number,
+  a list, `Between`, `Every` or `"all"`.
+- **`combine="member"`** writes one combined file per member, each named after it.
+- Plans report members in their repr and in generated file names.
+
+## 0.1.5
+
+- Already-downloaded files are skipped. A file counts as done when its size matches
+  the catalogue and it starts with `GRIB` and ends with `7777`.
+- Generated file names end in a hash of the plan, which is what makes the check possible.
+- `DownloadResult.assets_skipped` reports on how much has been skipped and how much needs
+  to transfer.
+- Interrupted downloads clean up the temporary folder(s).
+
+## 0.1.4
+
+- Added support for time-invariant fields.
+
+## 0.1.3
+
+- Generated file names. Give `combine="all"` a directory and it names the file after the
+  model, run, selection and step range.
+- `ResolvedRequest` and `Asset` print a readable summary instead of listing every asset.
+
+## 0.1.2
+
+- Model and parameter names are matched ignoring case, so `t_2m` and `T_2M` both work.
+- `hours()` and `minutes()` convenience functions from plain numbers.
+- A bare number as a step is refused with a message, as it might be ambiguous.
+
+## 0.1.1
+
+- Vertical levels: `level_type=` and `levels=`, in hPa for pressure, indices for model
+  levels and metres for soil.
+- `AmbiguousSelectionError` when a parameter exists on several level types and none was
+  named.
+- Level listings are fetched concurrently.
+
+## 0.1.0
+
+- First release. Model and parameter discovery, step selection, run resolution, and
+  parallel downloads with atomic writes.
+- Messages in a combined file are sorted time-major.

dwdopen-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christoph Fischer
+
+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.

dwdopen-0.2.1/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.5
+Name: dwdopen
+Version: 0.2.1
+Summary: Typed Python access to DWD Open Data numerical weather prediction (ICON).
+Project-URL: Homepage, https://github.com/MuffinCompiler/dwdopen
+Project-URL: Repository, https://github.com/MuffinCompiler/dwdopen
+Project-URL: Issues, https://github.com/MuffinCompiler/dwdopen/issues
+Project-URL: Changelog, https://github.com/MuffinCompiler/dwdopen/blob/master/CHANGELOG.md
+Author: Christoph Fischer
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dwd,grib,icon,nwp,opendata,weather
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dwdopen
+
+Python library to access [DWD Open Data](https://opendata.dwd.de/) numerical weather
+prediction (NWP) data: discover what data is currently offered, define what you want,
+and download it.
+
+> Still in "pre-alpha", not everything works yet.
+> See [Not yet implemented](#not-yet-implemented).
+
+## Install
+
+Requires **Python 3.12+**.
+
+```bash
+pip install git+https://github.com/MuffinCompiler/dwdopen@v0.1.0
+```
+
+## Quickstart
+
+```python
+from dwdopen import DWD
+
+with DWD() as dwd:
+    icon_eu = dwd.nwp.model("icon-eu")
+
+    query = icon_eu.select(parameters=["T_2M", "PMSL"], steps="6h")
+    query.download("forecast.grib2")
+```
+
+Nothing touches the network until a call needs availability information.
+
+### Investigate your request before you download
+
+`resolve()` freezes a query against one run and hands back a plan you can inspect before
+any download happens:
+
+```python
+plan = icon_eu.select(parameters="U", level_type="pressure").resolve()
+print(plan)
+# ResolvedRequest(run=2026-09-23T06:00:00+00:00, 1860 assets, 1.5 GB, U,
+#                 on pressure (100), 20 levels, steps 0h..120h)
+
+print(plan.assets[0])
+# Asset(U, 50 hPa, 0h, 723.4 KB)
+
+plan.download("u.grib2")
+```
+
+A plan never switches to a newer run later, so what you inspected is what you get.
+
+### Discovery
+
+```python
+dwd.nwp.models()                    # every model DWD currently publishes
+icon_eu.parameters()                # every parameter of one model
+icon_eu.parameter("T").level_types  # (pressure (100), model (150))
+icon_eu.levels("T", "pressure")     # available level values
+```
+
+Everything comes from the live catalogue, so a parameter
+DWD adds should show up without a new dwdopen release.
+
+## Selecting
+
+### Forecast steps
+
+Steps are **durations**, ICON-D2 publishes precipitation every
+15 minutes and ICON-D2-RUC every 5.
+
+```python
+from dwdopen import Between, Every, hours, minutes
+
+steps="6h"                        # exactly this step
+steps=["0h", "3h", "6h"]          # exactly these
+steps=Every("0h", "48h", "3h")    # interval, inclusive at both ends
+steps=Between("0h", "48h")        # whatever exists in the interval
+steps="all"                       # everything published
+
+steps=hours(0, 6, 12, 18)         # plain numbers, if that is what you have
+steps=hours(range(0, 121, 3))     # or any iterable of them
+steps=minutes(0, 15, 30)          # for the sub-hourly models
+```
+
+`hours()` and `minutes()` turn a single number into a single duration, so they compose
+with the others too: `Every(hours(0), hours(48), hours(3))`.
+
+`Every` names exact steps, so a missing one makes the request incomplete. `Between` and
+`"all"` ask for whatever is there and can never be incomplete.
+
+Note that DWD publishes data incrementally on the server, so a run might just be halfway
+available. If you use `Between`, you might just get what's already available, not the full
+data.
+
+### Ensemble members
+
+The `-eps` models publish each member separately. Members are plain integers; how many
+there are differs per model (40 for ICON-EPS and ICON-EU-EPS, 20 for ICON-D2-EPS, 10 for
+ICON-ART-EPS):
+
+```python
+eps.select(parameters="T_2M", members=[1, 2, 5])
+eps.select(parameters="T_2M", members=Between(1, 10))
+eps.select(parameters="T_2M")                       # every member
+```
+
+Leaving `members` out takes all of them, the same as levels and steps.
+Ensembles publish a reduced level set: `icon-eu-eps` `T` has 3 pressure levels
+and 3 model levels, against 20 and 74 for deterministic ICON-EU. Check the output of
+`model.levels()` to see what is actually there.
+
+### Vertical levels
+
+```python
+icon_eu.select(parameters="T", level_type="pressure", levels=[850, 500])
+icon_eu.select(parameters="T", level_type="model", levels=Between(60, 74))
+icon_eu.select(parameters="T_SO", level_type="soil", levels="all")
+```
+
+`level_type` may be left out only while the selection is unambiguous. `T` is available on
+both pressure and model levels, so omitting it raises `AmbiguousSelectionError` rather
+than guessing. A 2-D field such as `T_2M` needs no level type at all. Time-invariant fields
+need no level type either. These are published under every run with a single step.
+`HHL` is the exception, being model half-level heights:
+
+```python
+icon_d2.select(parameters="HSURF", steps="0h")                      # no level type
+icon_d2.select(parameters="HHL", level_type="model", levels="all")
+```
+
+## Downloading
+
+```python
+query.download("forecast.grib2")                    # one combined file
+query.download("members/", combine="member")        # one file per ensemble member
+query.download("forecast/", combine="none")         # one file per message
+query.download("f.grib2", temp_dir="/scratch")      # partial downloads before combining elsewhere
+```
+
+`combine="all"` concatenates the messages into a single GRIB2 file, which is valid
+because GRIB2 messages are self-delimiting. You can also provide just a directory in
+this case and the name is generated automatically.
+
+```python
+plan = query.resolve()
+plan.suggested_name()            # 'icon-eu_2026-09-24T0600_PMSL+T_2M_0h-24h.grib2'
+plan.download("/home/weather/")   # writes that name into the directory
+```
+
+Messages are sorted time-major: every field of one forecast step together, steps
+ascending. Some programs like CDO require grib files to be sorted by time to work
+correctly.
+
+Downloads run concurrently, are written to a temporary name and renamed into place, so a
+partial file is never mistaken for a finished one. Several processes may write the same
+directory at once.
+
+Already downloaded files are skipped, a second run of the same selection transfers nothing:
+A file counts as done when its size matches the catalogue and it starts with `GRIB`
+and ends with `7777`. For `combine="all"` this works when the name was generated, because
+the generated name ends in a hash of the plan and so describes that exact selection.
+
+`DownloadResult.assets_skipped` says how many were already there, which is worth
+checking in a scheduled job. Nothing is kept between runs. A partial download is discarded,
+so an interrupted job never leaves files behind.
+
+`temp_dir` must be on the same filesystem as the destination, because publishing a
+finished file is a rename and a rename cannot cross filesystems.
+
+## Logging
+
+The library logs through the standard `dwdopen` logger. It never prompts or reads from
+stdin as the library is meant to run unattended.
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+`INFO` reports what is about to be downloaded and how large it is. `WARNING` covers
+retries and mixed level types.
+
+## Not yet implemented
+
+- [ ] Resume and skip existing files. A failed run currently re-downloads from scratch.
+- [ ] Ensemble members** (`-eps` models, the `e/<NN>/` path segment).
+- [ ] `combine="member"` and `combine="parameter"`.
+- [ ] Listing cache. Every call re-reads the catalogue today.
+- [ ] Feedback of download progress (bar, text, visual?)
+- [ ] ICON-ART wavelengths (the `wvl1` segment).
+- [ ] A command-line interface.
+- [ ] Automatic parameter choice for `Model.latest_run()`, which needs
+      `parameter=` at the moment.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Forecast data itself is provided by Deutscher Wetterdienst (DWD) under its own
+[terms of use](https://www.dwd.de/EN/service/copyright/copyright_node.html).

dwdopen-0.2.1/README.md

@@ -0,0 +1,199 @@
+# dwdopen
+
+Python library to access [DWD Open Data](https://opendata.dwd.de/) numerical weather
+prediction (NWP) data: discover what data is currently offered, define what you want,
+and download it.
+
+> Still in "pre-alpha", not everything works yet.
+> See [Not yet implemented](#not-yet-implemented).
+
+## Install
+
+Requires **Python 3.12+**.
+
+```bash
+pip install git+https://github.com/MuffinCompiler/dwdopen@v0.1.0
+```
+
+## Quickstart
+
+```python
+from dwdopen import DWD
+
+with DWD() as dwd:
+    icon_eu = dwd.nwp.model("icon-eu")
+
+    query = icon_eu.select(parameters=["T_2M", "PMSL"], steps="6h")
+    query.download("forecast.grib2")
+```
+
+Nothing touches the network until a call needs availability information.
+
+### Investigate your request before you download
+
+`resolve()` freezes a query against one run and hands back a plan you can inspect before
+any download happens:
+
+```python
+plan = icon_eu.select(parameters="U", level_type="pressure").resolve()
+print(plan)
+# ResolvedRequest(run=2026-09-23T06:00:00+00:00, 1860 assets, 1.5 GB, U,
+#                 on pressure (100), 20 levels, steps 0h..120h)
+
+print(plan.assets[0])
+# Asset(U, 50 hPa, 0h, 723.4 KB)
+
+plan.download("u.grib2")
+```
+
+A plan never switches to a newer run later, so what you inspected is what you get.
+
+### Discovery
+
+```python
+dwd.nwp.models()                    # every model DWD currently publishes
+icon_eu.parameters()                # every parameter of one model
+icon_eu.parameter("T").level_types  # (pressure (100), model (150))
+icon_eu.levels("T", "pressure")     # available level values
+```
+
+Everything comes from the live catalogue, so a parameter
+DWD adds should show up without a new dwdopen release.
+
+## Selecting
+
+### Forecast steps
+
+Steps are **durations**, ICON-D2 publishes precipitation every
+15 minutes and ICON-D2-RUC every 5.
+
+```python
+from dwdopen import Between, Every, hours, minutes
+
+steps="6h"                        # exactly this step
+steps=["0h", "3h", "6h"]          # exactly these
+steps=Every("0h", "48h", "3h")    # interval, inclusive at both ends
+steps=Between("0h", "48h")        # whatever exists in the interval
+steps="all"                       # everything published
+
+steps=hours(0, 6, 12, 18)         # plain numbers, if that is what you have
+steps=hours(range(0, 121, 3))     # or any iterable of them
+steps=minutes(0, 15, 30)          # for the sub-hourly models
+```
+
+`hours()` and `minutes()` turn a single number into a single duration, so they compose
+with the others too: `Every(hours(0), hours(48), hours(3))`.
+
+`Every` names exact steps, so a missing one makes the request incomplete. `Between` and
+`"all"` ask for whatever is there and can never be incomplete.
+
+Note that DWD publishes data incrementally on the server, so a run might just be halfway
+available. If you use `Between`, you might just get what's already available, not the full
+data.
+
+### Ensemble members
+
+The `-eps` models publish each member separately. Members are plain integers; how many
+there are differs per model (40 for ICON-EPS and ICON-EU-EPS, 20 for ICON-D2-EPS, 10 for
+ICON-ART-EPS):
+
+```python
+eps.select(parameters="T_2M", members=[1, 2, 5])
+eps.select(parameters="T_2M", members=Between(1, 10))
+eps.select(parameters="T_2M")                       # every member
+```
+
+Leaving `members` out takes all of them, the same as levels and steps.
+Ensembles publish a reduced level set: `icon-eu-eps` `T` has 3 pressure levels
+and 3 model levels, against 20 and 74 for deterministic ICON-EU. Check the output of
+`model.levels()` to see what is actually there.
+
+### Vertical levels
+
+```python
+icon_eu.select(parameters="T", level_type="pressure", levels=[850, 500])
+icon_eu.select(parameters="T", level_type="model", levels=Between(60, 74))
+icon_eu.select(parameters="T_SO", level_type="soil", levels="all")
+```
+
+`level_type` may be left out only while the selection is unambiguous. `T` is available on
+both pressure and model levels, so omitting it raises `AmbiguousSelectionError` rather
+than guessing. A 2-D field such as `T_2M` needs no level type at all. Time-invariant fields
+need no level type either. These are published under every run with a single step.
+`HHL` is the exception, being model half-level heights:
+
+```python
+icon_d2.select(parameters="HSURF", steps="0h")                      # no level type
+icon_d2.select(parameters="HHL", level_type="model", levels="all")
+```
+
+## Downloading
+
+```python
+query.download("forecast.grib2")                    # one combined file
+query.download("members/", combine="member")        # one file per ensemble member
+query.download("forecast/", combine="none")         # one file per message
+query.download("f.grib2", temp_dir="/scratch")      # partial downloads before combining elsewhere
+```
+
+`combine="all"` concatenates the messages into a single GRIB2 file, which is valid
+because GRIB2 messages are self-delimiting. You can also provide just a directory in
+this case and the name is generated automatically.
+
+```python
+plan = query.resolve()
+plan.suggested_name()            # 'icon-eu_2026-09-24T0600_PMSL+T_2M_0h-24h.grib2'
+plan.download("/home/weather/")   # writes that name into the directory
+```
+
+Messages are sorted time-major: every field of one forecast step together, steps
+ascending. Some programs like CDO require grib files to be sorted by time to work
+correctly.
+
+Downloads run concurrently, are written to a temporary name and renamed into place, so a
+partial file is never mistaken for a finished one. Several processes may write the same
+directory at once.
+
+Already downloaded files are skipped, a second run of the same selection transfers nothing:
+A file counts as done when its size matches the catalogue and it starts with `GRIB`
+and ends with `7777`. For `combine="all"` this works when the name was generated, because
+the generated name ends in a hash of the plan and so describes that exact selection.
+
+`DownloadResult.assets_skipped` says how many were already there, which is worth
+checking in a scheduled job. Nothing is kept between runs. A partial download is discarded,
+so an interrupted job never leaves files behind.
+
+`temp_dir` must be on the same filesystem as the destination, because publishing a
+finished file is a rename and a rename cannot cross filesystems.
+
+## Logging
+
+The library logs through the standard `dwdopen` logger. It never prompts or reads from
+stdin as the library is meant to run unattended.
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+`INFO` reports what is about to be downloaded and how large it is. `WARNING` covers
+retries and mixed level types.
+
+## Not yet implemented
+
+- [ ] Resume and skip existing files. A failed run currently re-downloads from scratch.
+- [ ] Ensemble members** (`-eps` models, the `e/<NN>/` path segment).
+- [ ] `combine="member"` and `combine="parameter"`.
+- [ ] Listing cache. Every call re-reads the catalogue today.
+- [ ] Feedback of download progress (bar, text, visual?)
+- [ ] ICON-ART wavelengths (the `wvl1` segment).
+- [ ] A command-line interface.
+- [ ] Automatic parameter choice for `Model.latest_run()`, which needs
+      `parameter=` at the moment.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+Forecast data itself is provided by Deutscher Wetterdienst (DWD) under its own
+[terms of use](https://www.dwd.de/EN/service/copyright/copyright_node.html).