fix(python): import converters and specs lazily so inference does not load torch (memory reduction) (#2080)

* fix(python): import converters and specs lazily so inference does not load torch

`import ctranslate2` eagerly imported the `converters` and `specs` submodules, both of
which import torch at module level (`converters` also imports transformers and
huggingface_hub). Those dependencies are only needed to convert models, so every
inference-only user with torch in the environment paid for the import.

Import both submodules on first attribute access via a module-level `__getattr__`
(PEP 562). `from ctranslate2 import converters`, `import ctranslate2.converters` and
the `ct2-*-converter` entry points are unaffected; `models` stays eager because it
only imports from the compiled extension.

Measured with torch 2.5.1+cu121 installed: `import ctranslate2` drops from 3.04s to
0.15s (the package's own import subtree, per -X importtime, from 2.73s to 0.11s).

Fixes #2078

* test(python): cover wildcard import of the lazy submodules

* test(python): cover wildcard import of the lazy submodules

Author: Anai-Guo

python/ctranslate2/__init__.py

@@ -55,5 +55,35 @@
     else:
         raise
 
-from ctranslate2 import converters, models, specs
+from ctranslate2 import models
 from ctranslate2.version import __version__
+
+# converters and specs import torch (and, for converters, transformers) at module level.
+# Those dependencies are only needed to convert models, not to run inference, so import
+# these submodules on first use to keep "import ctranslate2" free of them.
+_LAZY_SUBMODULES = ("converters", "specs")
+
+
+def __getattr__(name):
+    if name in _LAZY_SUBMODULES:
+        import importlib
+
+        module = importlib.import_module(f"{__name__}.{name}")
+        globals()[name] = module
+        return module
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(_LAZY_SUBMODULES))
+
+
+# A wildcard import resolves ``__all__`` when it is defined and the module globals
+# otherwise, so without this the lazy submodules would silently drop out of
+# ``from ctranslate2 import *``. Deriving the list keeps the wildcard surface identical
+# to what it was before they became lazy; a wildcard import asks for everything, so
+# resolving them here is expected.
+__all__ = sorted(
+    [name for name in globals() if not name.startswith("_")] + list(_LAZY_SUBMODULES)
+)

python/tests/test_misc.py

@@ -1,3 +1,6 @@
+import subprocess
+import sys
+
 import pytest
 
 from ctranslate2.extensions import _batch_iterator as batch_iterator
@@ -17,3 +20,41 @@ def test_batch_iterator(batch_size, batch_type, lengths, expected_batch_sizes):
     batch_sizes = [len(batch[0]) for batch in batches]
 
     assert batch_sizes == expected_batch_sizes
+
+
+@pytest.mark.parametrize("module_name", ["torch", "transformers"])
+def test_import_does_not_load_conversion_dependencies(module_name):
+    # The converters and specs submodules are only needed to convert models, so importing
+    # the package for inference should not pull their heavy dependencies into the process.
+    # Run in a subprocess because the test session itself imports them.
+    code = "import sys; import ctranslate2; print(%r in sys.modules)" % module_name
+    result = subprocess.run(
+        [sys.executable, "-c", code],
+        capture_output=True,
+        check=True,
+        text=True,
+    )
+
+    assert result.stdout.strip() == "False"
+
+
+def test_wildcard_import_still_exposes_lazy_submodules():
+    # Wildcard imports read ``__all__`` when it is defined, so the lazy submodules must
+    # stay listed there to keep exposing the same names as before they became lazy.
+    # converters imports transformers, which is only installed on Linux.
+    pytest.importorskip("transformers")
+
+    # Run in a subprocess so the wildcard import does not leak into the test session.
+    code = (
+        "from ctranslate2 import *\n"
+        "names = set(dir())\n"
+        "print(sorted(n for n in ('converters', 'specs') if n in names))\n"
+    )
+    result = subprocess.run(
+        [sys.executable, "-c", code],
+        capture_output=True,
+        check=True,
+        text=True,
+    )
+
+    assert result.stdout.strip() == "['converters', 'specs']"