lazy imports

Author: alphaville

python/opengen/__init__.py

@@ -1,12 +1,16 @@
-from . import (
-	definitions,
-	builder,
-	config,
-	functions,
-	constraints,
-	tcp,
-	ocp,
-)
+"""Top-level package for OpEn with lazy submodule imports.
+
+This module defers importing heavy subpackages to attribute access
+to avoid circular import problems during package initialization.
+
+Lazy submodule imports defer the loading of Python modules and their 
+attributes until they are first accessed, reducing startup time and 
+memory usage.  This is achieved using PEP 562 (__getattr__ and __dir__) 
+to intercept attribute access and load the underlying code only when 
+necessary.
+"""
+
+from importlib import import_module
 
 __all__ = [
 	"definitions",
@@ -17,3 +21,24 @@
 	"tcp",
 	"ocp",
 ]
+
+
+def __getattr__(name):
+	"""Lazily import submodules on attribute access.
+
+	Example: accessing ``opengen.builder`` will import
+	``opengen.builder`` and cache it on the package module.
+
+	This defers importing heavy subpackages until they're actually used 
+	(lazy imports), reducing startup cost and helping avoid import-time 
+	circular dependencies.
+	"""
+	if name in __all__:
+		module = 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(list(__all__) + list(globals().keys()))

python/opengen/builder/optimizer_builder.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import subprocess
 import shutil
 import yaml

python/test/test_constraints.py

@@ -623,7 +623,7 @@ def test_dimension_sphere2(self):
     # -----------------------------------------------------------------------
 
     def test_zero_dimension(self):        
-        z = og.opengen.constraints.Zero()
+        z = og.constraints.Zero()
         self.assertIsNone(z.dimension())
 
 if __name__ == '__main__':