Lazy import dependencies (#41)

Author: lukasbindreiter

AGENTS.md

@@ -69,6 +69,14 @@ Pre-commit hooks include YAML checks, EOF fixer, `sync-with-uv`, Ruff, and `ty`.
 - Logging uses `loguru` in several packages; workflows also supports explicit logger/tracer configuration.
 - Tests use `pytest`, with async coverage (`pytest-asyncio`) and property-based testing (`hypothesis`) in multiple packages.
 
+### Import-Time Discipline
+
+- Keep `tilebox.workflows` task-authoring imports light. Release runners create fresh virtual environments, so avoid
+  importing heavy optional/runtime dependencies (`pandas`, `numpy`, `xarray`, cloud SDKs, `ipywidgets`, OpenTelemetry
+  SDK/exporters, cache backends) from package `__init__` modules or core `Runner`/`Task` import paths.
+- Prefer lazy imports inside the methods that actually need those dependencies. Module-level `__getattr__` aliases are
+  acceptable for public package aliases and are supported by Python 3.7+.
+
 ## Protobuf And Generated Code
 
 Generated files live under paths such as:

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.56.0] - 2026-07-16
+
+### Changed
+
+- `tilebox-workflows`: Reduced import-time overhead for release runners by lazily loading optional heavy dependencies
+  such as datasets, pandas, cloud SDKs, notebook widgets, and runtime/observability modules until they are needed.
+- `tilebox-datasets`: Reduced import-time overhead by lazily exporting the root and async client APIs and deferring
+  pandas/xarray imports in time interval parsing until parsing requires them.
+- `tilebox-storage`: Reduced startup overhead by lazily exporting sync storage clients and deferring geospatial,
+  notebook, object-store, cloud SDK, HTTP, and progress-display dependencies until storage operations require them.
+
 ### Fixed
 
 - `tilebox-workflows`: Allow task `execute()` methods to use a `-> None` return annotation when postponed annotation
@@ -401,7 +412,8 @@ the first client that does not cache data (since it's already on the local file
 - Released under the [MIT](https://opensource.org/license/mit) license.
 - Released packages: `tilebox-datasets`, `tilebox-workflows`, `tilebox-storage`, `tilebox-grpc`
 
-[Unreleased]: https://github.com/tilebox/tilebox-python/compare/v0.55.0...HEAD
+[Unreleased]: https://github.com/tilebox/tilebox-python/compare/v0.55.1...HEAD
+[0.55.1]: https://github.com/tilebox/tilebox-python/compare/v0.55.0...v0.55.1
 [0.55.0]: https://github.com/tilebox/tilebox-python/compare/v0.54.0...v0.55.0
 [0.54.0]: https://github.com/tilebox/tilebox-python/compare/v0.53.0...v0.54.0
 [0.53.0]: https://github.com/tilebox/tilebox-python/compare/v0.52.0...v0.53.0

tilebox-datasets/tests/test_client.py

@@ -1,4 +1,6 @@
 import os
+import subprocess
+import sys
 from datetime import datetime, timezone
 from pathlib import Path
 from unittest.mock import MagicMock, patch
@@ -15,6 +17,24 @@
 from tilebox.datasets.query.time_interval import us_to_datetime
 
 
+def test_heavy_imports_are_lazy() -> None:
+    code = (
+        "import sys\n"
+        "import tilebox.datasets as datasets\n"
+        "assert not {'pandas', 'xarray'} & sys.modules.keys()\n"
+        "assert set(datasets.__all__) <= set(dir(datasets))\n"
+        "from tilebox.datasets.query.time_interval import TimeInterval\n"
+        "assert not {'pandas', 'xarray'} & sys.modules.keys()\n"
+        "TimeInterval.parse('2026-01-01')\n"
+        "assert 'pandas' in sys.modules\n"
+        "assert 'xarray' not in sys.modules\n"
+        "client = datasets.Client\n"
+        "assert datasets.Client is client\n"
+        "assert 'Client' in vars(datasets)\n"
+    )
+    subprocess.run([sys.executable, "-c", code], check=True)  # noqa: S603
+
+
 @pytest.mark.parametrize("url", [_TILEBOX_API_URL, _TILEBOX_DEV_API_URL, f"{_TILEBOX_API_URL}/"])
 @patch.dict(os.environ, {}, clear=True)
 @patch("tilebox.datasets.sync.client.open_channel")

tilebox-datasets/tilebox/datasets/__init__.py

@@ -1,16 +1,55 @@
 import os
 import sys
+from typing import TYPE_CHECKING, Any
 
 from loguru import logger
 
-# only here for backwards compatibility, to preserve backwards compatibility with older imports
-from tilebox.datasets.aio.timeseries import TimeseriesCollection, TimeseriesDataset
-from tilebox.datasets.sync.client import Client
-from tilebox.datasets.sync.dataset import CollectionClient, DatasetClient
+if TYPE_CHECKING:
+    from tilebox.datasets.aio.timeseries import TimeseriesCollection, TimeseriesDataset
+    from tilebox.datasets.sync.client import Client
+    from tilebox.datasets.sync.dataset import CollectionClient, DatasetClient
 
 __all__ = ["Client", "CollectionClient", "DatasetClient", "TimeseriesCollection", "TimeseriesDataset"]
 
 
+def __getattr__(name: str) -> Any:
+    # PEP 562 module __getattr__ is supported since Python 3.7. Keep these aliases lazy so importing a focused
+    # submodule like tilebox.datasets.query.id_interval does not also import the sync/aio clients and their data-model
+    # dependencies.
+    match name:
+        case "Client":
+            from tilebox.datasets.sync.client import Client  # noqa: PLC0415
+
+            value = Client
+        case "CollectionClient":
+            from tilebox.datasets.sync.dataset import CollectionClient  # noqa: PLC0415
+
+            value = CollectionClient
+        case "DatasetClient":
+            from tilebox.datasets.sync.dataset import DatasetClient  # noqa: PLC0415
+
+            value = DatasetClient
+        case "TimeseriesCollection":
+            from tilebox.datasets.aio.timeseries import TimeseriesCollection  # noqa: PLC0415
+
+            value = TimeseriesCollection
+        case "TimeseriesDataset":
+            from tilebox.datasets.aio.timeseries import TimeseriesDataset  # noqa: PLC0415
+
+            value = TimeseriesDataset
+        case _:
+            raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    # Cache the resolved export so subsequent access uses normal module lookup instead of calling __getattr__ again.
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    # Include public lazy exports in dir(module) before they have been loaded.
+    return sorted(set(globals()) | set(__all__))
+
+
 def _init_logging(level: str = "INFO") -> None:
     logger.remove()
     logger.add(sys.stdout, level=level, format="{message}", catch=True)

tilebox-datasets/tilebox/datasets/aio/__init__.py

@@ -1,7 +1,45 @@
-from tilebox.datasets.aio.client import Client
-from tilebox.datasets.aio.dataset import CollectionClient, DatasetClient
+from typing import TYPE_CHECKING, Any
 
-# only here for backwards compatibility, to preserve backwards compatibility with older imports
-from tilebox.datasets.aio.timeseries import TimeseriesCollection, TimeseriesDataset
+if TYPE_CHECKING:
+    from tilebox.datasets.aio.client import Client
+    from tilebox.datasets.aio.dataset import CollectionClient, DatasetClient
+    from tilebox.datasets.aio.timeseries import TimeseriesCollection, TimeseriesDataset
 
 __all__ = ["Client", "CollectionClient", "DatasetClient", "TimeseriesCollection", "TimeseriesDataset"]
+
+
+def __getattr__(name: str) -> Any:
+    # PEP 562 module __getattr__ is supported since Python 3.7. Keep these aliases lazy so importing
+    # tilebox.datasets.aio does not also import xarray/pandas-backed dataset clients.
+    match name:
+        case "Client":
+            from tilebox.datasets.aio.client import Client  # noqa: PLC0415
+
+            value = Client
+        case "CollectionClient":
+            from tilebox.datasets.aio.dataset import CollectionClient  # noqa: PLC0415
+
+            value = CollectionClient
+        case "DatasetClient":
+            from tilebox.datasets.aio.dataset import DatasetClient  # noqa: PLC0415
+
+            value = DatasetClient
+        case "TimeseriesCollection":
+            from tilebox.datasets.aio.timeseries import TimeseriesCollection  # noqa: PLC0415
+
+            value = TimeseriesCollection
+        case "TimeseriesDataset":
+            from tilebox.datasets.aio.timeseries import TimeseriesDataset  # noqa: PLC0415
+
+            value = TimeseriesDataset
+        case _:
+            raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    # Cache the resolved export so subsequent access uses normal module lookup instead of calling __getattr__ again.
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    # Include public lazy exports in dir(module) before they have been loaded.
+    return sorted(set(globals()) | set(__all__))

tilebox-datasets/tilebox/datasets/query/time_interval.py

@@ -1,21 +1,22 @@
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
-from typing import TypeAlias
+from typing import TYPE_CHECKING, Any, TypeAlias
 
-import numpy as np
-import xarray as xr
 from google.protobuf.duration_pb2 import Duration
 from google.protobuf.timestamp_pb2 import Timestamp
-from pandas.core.tools.datetimes import DatetimeScalar, to_datetime
 
 from tilebox.datasets.tilebox.v1 import query_pb2
 
+if TYPE_CHECKING:
+    from pandas.core.tools.datetimes import DatetimeScalar
+    from xarray import DataArray, Dataset
+
 _SMALLEST_POSSIBLE_TIMEDELTA = timedelta(microseconds=1)
 _EPOCH = datetime(1970, 1, 1, tzinfo=timezone.utc)
 
 # A type alias for the different types that can be used to specify a time interval
 TimeIntervalLike: TypeAlias = (
-    "DatetimeScalar | tuple[DatetimeScalar, DatetimeScalar] | xr.DataArray | xr.Dataset | TimeInterval"
+    "DatetimeScalar | tuple[DatetimeScalar, DatetimeScalar] | list[DatetimeScalar] | DataArray | Dataset | TimeInterval"
 )
 # once we require python >= 3.12 we can replace this with a type statement, which doesn't require a string at all
 # type TimeIntervalLike = DatetimeScalar | tuple[DatetimeScalar ...  | TimeInterval
@@ -133,30 +134,34 @@ def parse(cls, arg: TimeIntervalLike) -> "TimeInterval":
             TimeInterval: The parsed time interval
         """
 
-        match arg:
-            case TimeInterval(_, _, _, _):
-                return arg
-            case (start, end):
-                return TimeInterval(start=_convert_to_datetime(start), end=_convert_to_datetime(end))
-            case point_in_time if isinstance(point_in_time, DatetimeScalar | int):
-                dt = _convert_to_datetime(point_in_time)
-                return TimeInterval(start=dt, end=dt, start_exclusive=False, end_inclusive=True)
-            case arr if (
-                isinstance(arr, xr.DataArray)
-                and arr.ndim == 1
-                and arr.size > 0
-                and arr.dtype == np.dtype("datetime64[ns]")
-            ):
-                start = arr.data[0]
-                end = arr.data[-1]
-                return TimeInterval(
-                    start=_convert_to_datetime(start),
-                    end=_convert_to_datetime(end),
-                    start_exclusive=False,
-                    end_inclusive=True,
-                )
-            case ds if isinstance(ds, xr.Dataset) and "time" in ds.coords:
-                return cls.parse(ds.time)
+        if isinstance(arg, TimeInterval):
+            return arg
+
+        if isinstance(arg, list | tuple) and len(arg) == 2:
+            start, end = arg
+            return TimeInterval(start=_convert_to_datetime(start), end=_convert_to_datetime(end))
+
+        from pandas.core.tools.datetimes import DatetimeScalar  # noqa: PLC0415
+
+        if isinstance(arg, DatetimeScalar | int):
+            dt = _convert_to_datetime(arg)
+            return TimeInterval(start=dt, end=dt, start_exclusive=False, end_inclusive=True)
+
+        import numpy as np  # noqa: PLC0415
+        import xarray as xr  # noqa: PLC0415
+
+        if isinstance(arg, xr.DataArray) and arg.ndim == 1 and arg.size > 0 and arg.dtype == np.dtype("datetime64[ns]"):
+            start = arg.data[0]
+            end = arg.data[-1]
+            return TimeInterval(
+                start=_convert_to_datetime(start),
+                end=_convert_to_datetime(end),
+                start_exclusive=False,
+                end_inclusive=True,
+            )
+
+        if isinstance(arg, xr.Dataset) and "time" in arg.coords:
+            return cls.parse(arg.time)
 
         raise ValueError(f"Failed to convert {arg} ({type(arg)}) to TimeInterval)")
 
@@ -192,8 +197,10 @@ def to_message(self) -> query_pb2.TimeInterval:
 _EMPTY_TIME_INTERVAL = TimeInterval(_EPOCH, _EPOCH, start_exclusive=True, end_inclusive=False)
 
 
-def _convert_to_datetime(arg: DatetimeScalar) -> datetime:
+def _convert_to_datetime(arg: Any) -> datetime:
     """Convert the given datetime scalar to a datetime object in the UTC timezone"""
+    from pandas.core.tools.datetimes import to_datetime  # noqa: PLC0415
+
     dt: datetime = to_datetime(arg, utc=True).to_pydatetime()
     if dt.tzinfo is None:
         dt = dt.replace(tzinfo=timezone.utc)