dwdopen 0.2.2__tar.gz → 0.2.3__tar.gz

{dwdopen-0.2.2 → dwdopen-0.2.3}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Versions follow [semantic versioning](https://semver.org/).
 
+## 0.2.3
+
+- Added proper logging, and print some download info by default, so users do not think
+  that the application hangs.
+- Generated file names now contain the level type.
+- Asking for a parameter on a level type it is not available on is now refused at
+  the `select()` stage.
+
 ## 0.2.2
 
 - README updated.

{dwdopen-0.2.2 → dwdopen-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dwdopen
-Version: 0.2.2
+Version: 0.2.3
 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
@@ -173,16 +173,19 @@ checking in a scheduled job.
 
 ## Logging
 
-The library logs through the standard `dwdopen` logger. It never prompts or reads from
-stdin as the library is meant to run unattended.
+The library logs through the `dwdopen` logger. You can change the logging level via::
 
 ```python
-import logging
-logging.basicConfig(level=logging.INFO)
+import logging, dwdopen
+
+dwdopen.set_log_level(logging.DEBUG)    # a line per file to download
+dwdopen.set_log_level(logging.WARNING)  # only retries and warnings
+dwdopen.set_log_level(None)             # disable the dwdopen logging
 ```
 
-`INFO` reports what is about to be downloaded and how large it is. `WARNING` covers
-retries and mixed level types.
+The handler is connected to the `dwdopen` logger. It will not override
+the logging your application sets up for itself. If you do configure your own logger
+and want to use that logger, call `set_log_level(None)`. That will uninstall the handler.
 
 ## Not yet implemented
 

{dwdopen-0.2.2 → dwdopen-0.2.3}/README.md

@@ -146,16 +146,19 @@ checking in a scheduled job.
 
 ## Logging
 
-The library logs through the standard `dwdopen` logger. It never prompts or reads from
-stdin as the library is meant to run unattended.
+The library logs through the `dwdopen` logger. You can change the logging level via::
 
 ```python
-import logging
-logging.basicConfig(level=logging.INFO)
+import logging, dwdopen
+
+dwdopen.set_log_level(logging.DEBUG)    # a line per file to download
+dwdopen.set_log_level(logging.WARNING)  # only retries and warnings
+dwdopen.set_log_level(None)             # disable the dwdopen logging
 ```
 
-`INFO` reports what is about to be downloaded and how large it is. `WARNING` covers
-retries and mixed level types.
+The handler is connected to the `dwdopen` logger. It will not override
+the logging your application sets up for itself. If you do configure your own logger
+and want to use that logger, call `set_log_level(None)`. That will uninstall the handler.
 
 ## Not yet implemented
 

{dwdopen-0.2.2 → dwdopen-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dwdopen"
-version = "0.2.2"
+version = "0.2.3"
 description = "Typed Python access to DWD Open Data numerical weather prediction (ICON)."
 readme = "README.md"
 license = "MIT"

{dwdopen-0.2.2 → dwdopen-0.2.3}/src/dwdopen/__init__.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import logging
 from importlib.metadata import PackageNotFoundError, version
 
 from dwdopen.client import DWD, NWP
@@ -27,6 +28,33 @@ from dwdopen.nwp.request import DownloadResult
 from dwdopen.nwp.run import Run
 from dwdopen.nwp.selectors import Between, Every, LevelType
 
+_handler = logging.StreamHandler()
+_handler.setFormatter(
+    logging.Formatter("%(asctime)s %(levelname)-7s %(message)s", "%H:%M:%S")
+)
+
+
+def set_log_level(level: int | None = logging.INFO) -> None:
+    """Sets the log level to use when printing logs.
+    Set to None to disable logging.
+    """
+    logger = logging.getLogger("dwdopen")
+
+    if level is None:
+        logger.removeHandler(_handler)
+        logger.setLevel(logging.NOTSET)
+        return
+
+    # Add the handler to the dwdopen logger only.
+    if _handler not in logger.handlers:
+        logger.addHandler(_handler)
+
+    logger.setLevel(level)
+
+# Setup default logging.
+set_log_level()
+
+
 __all__ = [
     "DWD",
     "NWP",
@@ -37,6 +65,7 @@ __all__ = [
     "DWDOpenError",
     "DownloadError",
     "DownloadResult",
+    "set_log_level",
     "Every",
     "IncompleteRunError",
     "InvalidSelectorError",

{dwdopen-0.2.2 → dwdopen-0.2.3}/src/dwdopen/nwp/model.py

@@ -211,12 +211,15 @@ class Model:
         the level type is unambiguous. Every selected parameter must be available
         on the same level type, or on none at all.
         """
-        if level_type is not None:
-            return LevelType.coerce(level_type)
-
         per_parameter = {
             name: self._catalogue.level_types(self._name, name) for name in parameters
         }
+
+        if level_type is not None:
+            chosen = LevelType.coerce(level_type)
+            self._require_published_on(chosen, per_parameter)
+            return chosen
+
         candidates = {lt for types in per_parameter.values() for lt in types}
 
         if not candidates:
@@ -242,3 +245,33 @@ class Model:
             )
 
         return candidates.pop()
+
+    def _require_published_on(
+        self,
+        chosen: LevelType,
+        per_parameter: dict[str, list[LevelType]],
+    ) -> None:
+        """Raise InvalidSelectorError if the chosen level type is not
+        available for all the parameters.
+        The usual case is a parameter that only exists on one of the two
+        vertical coordinates. W is on model levels alone, and OMEGA is the
+        pressure-level vertical velocity.
+        """
+        # Get all parameters that are not available on the chosen level type.
+        wrong = {
+            name: level_types
+            for name, level_types in per_parameter.items()
+            if chosen not in level_types
+        }
+        if not wrong:
+            return
+
+        details = "; ".join(
+            f"{name} is on {', '.join(str(t) for t in types) or 'a single level'}"
+            for name, types in sorted(wrong.items())
+        )
+        raise InvalidSelectorError(
+            f"{', '.join(sorted(wrong))} in {self._name!r} "
+            f"{'is' if len(wrong) == 1 else 'are'} not published on {chosen}. "
+            f"{details}"
+        )

{dwdopen-0.2.2 → dwdopen-0.2.3}/src/dwdopen/nwp/request.py

@@ -395,16 +395,18 @@ class ResolvedRequest:
         levels = {a.level for a in self.assets if a.level is not None}
         kinds = {a.level_type for a in self.assets if a.level_type is not None}
         if not kinds:
-            return ""
+            return "single"
         if len(kinds) > 1:
-            # Put number of level types
             return f"{len(kinds)}lvt"
+
         kind = kinds.pop()
+        # The readable level type name where there is one, otherwise the code.
+        name = kind.alias or f"lvt{kind.code}"
         if len(levels) == 1:
             unit = kind.user_unit or kind.unit or ""
             value = _trim(kind.to_user(levels.pop()))
-            return f"{value}{unit}" if unit != "index" else f"lv{value}"
-        return f"{len(levels)}lv"
+            return f"{name}{value}" if unit == "index" else f"{name}{value}{unit}"
+        return f"{name}{len(levels)}lv"
 
     def _describe_members(self) -> str:
         """The ensemble member, empty for a deterministic plan.

{dwdopen-0.2.2 → dwdopen-0.2.3}/tests/integration/test_live_download.py

@@ -161,7 +161,12 @@ def test_combine_member_writes_one_file_per_member(tmp_path):
     assert len(result.files) == 2
     # The member is in the name, not only in the hash, or the files would be
     # impossible to tell apart.
-    assert sorted(p.name.split("_T_2M_")[1][:3] for p in result.files) == ["e01", "e02"]
+    assert sorted(
+        part
+        for p in result.files
+        for part in p.name.split("_")
+        if part.startswith("e0")
+    ) == ["e01", "e02"]
     for path in result.files:
         assert grib_messages(path) == 1
 

{dwdopen-0.2.2 → dwdopen-0.2.3}/tests/unit/test_download.py

@@ -377,3 +377,69 @@ def test_a_generated_combined_name_is_skipped_on_a_second_run(tmp_path):
     assert second.assets_downloaded == 0
     assert second.files == first.files
     assert len(http.requested) == before  # nothing fetched
+
+
+# --- log level ------------------------------------------------------------
+
+def test_progress_is_visible_without_any_setup():
+    """A download that prints nothing looks like one that hung."""
+    import logging
+
+    logger = logging.getLogger("dwdopen")
+    assert logger.handlers, "dwdopen should attach its own handler on import"
+    assert logger.getEffectiveLevel() <= logging.INFO
+
+
+def test_the_handler_is_never_put_on_the_root_logger():
+    """basicConfig() takes effect once.
+
+    A library that configured the root logger would silently override wherever
+    an application meant its logs to go.
+    """
+    import logging
+
+    import dwdopen
+
+    root_before = list(logging.getLogger().handlers)
+    dwdopen.set_log_level(logging.DEBUG)
+    assert logging.getLogger().handlers == root_before
+    dwdopen.set_log_level()
+
+
+def test_the_level_can_be_turned_up_and_down():
+    import logging
+
+    import dwdopen
+
+    dwdopen.set_log_level(logging.DEBUG)
+    assert logging.getLogger("dwdopen").level == logging.DEBUG
+    dwdopen.set_log_level(logging.WARNING)
+    assert logging.getLogger("dwdopen").level == logging.WARNING
+    dwdopen.set_log_level()
+    assert logging.getLogger("dwdopen").level == logging.INFO
+
+
+def test_none_hands_logging_back_to_the_application(caplog):
+    import logging
+
+    import dwdopen
+
+    dwdopen.set_log_level(None)
+    try:
+        assert dwdopen._handler not in logging.getLogger("dwdopen").handlers
+        # Records still reach an application that configured its own logging.
+        with caplog.at_level(logging.INFO, logger="dwdopen"):
+            logging.getLogger("dwdopen").info("a message")
+        assert "a message" in caplog.text
+    finally:
+        dwdopen.set_log_level()
+
+
+def test_setting_the_level_twice_does_not_duplicate_the_handler():
+    import logging
+
+    import dwdopen
+
+    dwdopen.set_log_level()
+    dwdopen.set_log_level()
+    assert logging.getLogger("dwdopen").handlers.count(dwdopen._handler) == 1

{dwdopen-0.2.2 → dwdopen-0.2.3}/tests/unit/test_levels.py

@@ -216,3 +216,30 @@ def test_an_invariant_field_is_selected_without_a_level_type():
     # HSURF, CLAT, FR_LAND and friends are plain 2-D parameters in v1.
     model = model_with({"HSURF": []})
     assert model.select(parameters="HSURF", steps="0h")._level_type is None
+
+
+def test_a_parameter_not_on_the_requested_level_type_is_refused():
+    """W exists on model levels only; OMEGA is the pressure-level equivalent.
+
+    Caught at select(), so the error names the call the caller wrote instead
+    of surfacing as a 404 on an lv1 listing partway through resolve().
+    """
+    model = model_with({"U": [PRESSURE, MODEL], "W": [MODEL]})
+    with pytest.raises(InvalidSelectorError) as caught:
+        model.select(parameters=["U", "W"], level_type="pressure", levels=[850])
+    message = str(caught.value)
+    assert "W" in message
+    assert "not published on pressure" in message
+    assert "model (150)" in message      # says what it does have
+
+
+def test_a_surface_parameter_asked_for_on_levels_is_refused():
+    model = model_with({"T_2M": []})
+    with pytest.raises(InvalidSelectorError, match="single level"):
+        model.select(parameters="T_2M", level_type="pressure", levels=[850])
+
+
+def test_a_parameter_that_does_have_the_level_type_is_accepted():
+    model = model_with({"U": [PRESSURE, MODEL], "V": [PRESSURE, MODEL]})
+    query = model.select(parameters=["U", "V"], level_type="pressure", levels=[850])
+    assert query._level_type is PRESSURE

{dwdopen-0.2.2 → dwdopen-0.2.3}/tests/unit/test_naming_plans.py

@@ -37,7 +37,7 @@ def plan(assets):
 def test_one_parameter_names_the_model_run_parameter_and_steps():
     made = plan([asset("T_2M", 0), asset("T_2M", 12)])
     assert made.suggested_name() == (
-        f"icon-eu_2026-09-24T0600_T_2M_0h-12h_{made.fingerprint()}.grib2"
+        f"icon-eu_2026-09-24T0600_T_2M_single_0h-12h_{made.fingerprint()}.grib2"
     )
 
 
@@ -60,35 +60,37 @@ def test_more_parameters_are_counted_so_the_name_stays_short():
     many = [asset(f"P{i:02d}") for i in range(21)]
     name = plan(many).suggested_name()
     assert "21params" in name
-    assert len(name) < 60
+    assert len(name) < 70
 
 
 def test_a_single_pressure_level_is_named_in_hpa():
     name = plan([asset("T", level_type=PRESSURE, level=85000)]).suggested_name()
-    assert "_850hPa_" in name
+    assert "_pressure850hPa_" in name
     assert "85000" not in name
 
 
 def test_several_levels_are_counted():
     assets = [asset("T", level_type=PRESSURE, level=lv) for lv in (85000, 50000)]
-    assert "_2lv_" in plan(assets).suggested_name()
+    assert "_pressure2lv_" in plan(assets).suggested_name()
 
 
 def test_a_model_level_is_labelled_rather_than_given_a_unit():
     # The unit is "index", which reads badly as a suffix.
     name = plan([asset("T", level_type=MODEL, level=60)]).suggested_name()
-    assert "_lv60_" in name
+    assert "_model60_" in name
 
 
 def test_a_soil_level_keeps_its_metres():
     name = plan([asset("T_SO", level_type=SOIL, level="0.18")]).suggested_name()
-    assert "_0.18m_" in name
+    assert "_soil0.18m_" in name
 
 
-def test_a_surface_selection_has_no_level_part():
+def test_a_surface_selection_is_labelled_single():
+    # Named rather than left blank, so a surface file is recognisable as one
+    # instead of merely lacking a field.
     made = plan([asset("T_2M")])
     assert made.suggested_name() == (
-        f"icon-eu_2026-09-24T0600_T_2M_0h_{made.fingerprint()}.grib2"
+        f"icon-eu_2026-09-24T0600_T_2M_single_0h_{made.fingerprint()}.grib2"
     )
 
 
@@ -145,8 +147,10 @@ def test_the_realistic_worst_case_fits():
     ]
     name = plan(assets).suggested_name()
     assert len(name) <= MAX_NAME_LENGTH
-    # Short enough that the names are still listed, not counted.
-    assert "DUST_MAX_TOTAL_MC_LAYER" in name
+    # Three of these no longer fit alongside the level field and the hash, so
+    # the count takes over. Degrading is the point; overflowing is not.
+    assert "3params" in name
+    assert name.endswith(f"_{plan(assets).fingerprint()}.grib2")
 
 
 def test_long_names_fall_back_to_counting_rather_than_overflowing():
@@ -160,7 +164,7 @@ def test_forty_surface_fields_stay_short():
     assets = [asset(f"PARAM_{i:02d}", hours=h) for i in range(40) for h in (0, 120)]
     name = plan(assets).suggested_name()
     assert "40params" in name
-    assert len(name) < 60
+    assert len(name) < 70
 
 
 def test_the_suffix_survives_even_a_pathological_name():