From a9d5c5b98f9344f33f451ca01b98a0926b6395dd Mon Sep 17 00:00:00 2001
From: Simon Heybrock <simon.heybrock@ess.eu>
Date: Wed, 26 Aug 2026 05:03:42 +0000
Subject: [PATCH] refactor: import ess.reduce submodules lazily

ess/reduce/__init__.py eagerly imported nexus, normalization, polarization,
uncertainty and unwrap, so importing any part of the package paid for all of
it. Because importing a submodule always executes the parent __init__, an
importer wanting one piece had no way to opt out.

lazy.attach defers each submodule to first attribute access, the pattern
scippneutron already uses. A stub keeps the submodules visible to type
checkers. streaming is now listed alongside the others; it was importable but
missing from __all__.

    import ess.reduce                  665 ms -> 39 ms, 177 MB -> 17 MB
    from ess.reduce import streaming   715 ms -> 244 ms, 177 MB -> 60 MB
    from ess.reduce import unwrap      unchanged

Importers that want unwrap pay what they always did. Importers that want
streaming no longer pay for scippnexus, scippneutron and, when installed,
numba, none of which streaming touches.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 packages/essreduce/pyproject.toml              |  1 +
 packages/essreduce/src/ess/reduce/__init__.py  | 14 ++++++++++++--
 packages/essreduce/src/ess/reduce/__init__.pyi | 13 +++++++++++++
 3 files changed, 26 insertions(+), 2 deletions(-)
 create mode 100644 packages/essreduce/src/ess/reduce/__init__.pyi

diff --git a/packages/essreduce/pyproject.toml b/packages/essreduce/pyproject.toml
index b0418a347..b2e496b7f 100644
--- a/packages/essreduce/pyproject.toml
+++ b/packages/essreduce/pyproject.toml
@@ -32,6 +32,7 @@ dynamic = ["version"]
 dependencies = [
     "dask>=2022.1.0",
     "graphviz>=0.20",
+    "lazy_loader>=0.4",
     "sciline>=25.11.0",
     "scipp>=26.3.1",
     "scippneutron>=26.6.0",
diff --git a/packages/essreduce/src/ess/reduce/__init__.py b/packages/essreduce/src/ess/reduce/__init__.py
index 873581316..3d5936efd 100644
--- a/packages/essreduce/src/ess/reduce/__init__.py
+++ b/packages/essreduce/src/ess/reduce/__init__.py
@@ -3,7 +3,7 @@
 
 import importlib.metadata
 
-from . import nexus, normalization, polarization, uncertainty, unwrap
+import lazy_loader as lazy
 
 try:
     __version__ = importlib.metadata.version("essreduce")
@@ -12,4 +12,14 @@
 
 del importlib
 
-__all__ = ["nexus", "normalization", "polarization", "uncertainty", "unwrap"]
+__getattr__, __dir__, __all__ = lazy.attach(
+    __name__,
+    submodules=[
+        "nexus",
+        "normalization",
+        "polarization",
+        "streaming",
+        "uncertainty",
+        "unwrap",
+    ],
+)
diff --git a/packages/essreduce/src/ess/reduce/__init__.pyi b/packages/essreduce/src/ess/reduce/__init__.pyi
new file mode 100644
index 000000000..04cdbeaf9
--- /dev/null
+++ b/packages/essreduce/src/ess/reduce/__init__.pyi
@@ -0,0 +1,13 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2025 Scipp contributors (https://github.com/scipp)
+
+from . import (
+    nexus,  # noqa: F401
+    normalization,  # noqa: F401
+    polarization,  # noqa: F401
+    streaming,  # noqa: F401
+    uncertainty,  # noqa: F401
+    unwrap,  # noqa: F401
+)
+
+__version__: str