{"id":891,"library":"lazy-loader","title":"Lazy Loader","description":"The `lazy-loader` library makes it easy to load Python subpackages and functions on demand. This utility is designed to help projects, especially in the scientific Python ecosystem, reduce startup time and memory usage by deferring module imports until the imported objects are actually accessed. It is actively maintained, currently at version 0.5, and sees regular updates to enhance functionality and fix bugs.","status":"active","version":"0.5","language":"python","source_language":"en","source_url":"https://github.com/scientific-python/lazy-loader","tags":["lazy loading","import","optimization","startup performance","module loading","scientific python"],"install":[{"cmd":"pip install lazy-loader","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"wrong":"import lazy_loader as lazy","symbol":"attach","correct":"from lazy_loader import attach"},{"symbol":"load","correct":"from lazy_loader import load"},{"symbol":"DelayedImportErrorModule","correct":"from lazy_loader import DelayedImportErrorModule"}],"quickstart":{"code":"import lazy_loader as lazy\nimport os\n\n# This would typically be in your package's __init__.py\n# For demonstration, we simulate it.\n\n# Define a dummy 'heavy_module' that prints when imported\n# In a real scenario, this would be a separate file or external library\nwith open('heavy_module.py', 'w') as f:\n    f.write(\"\"\"print('heavy_module imported!')\ndef expensive_func():\n    return 'Result from expensive_func'\n\"\"\")\n\n# Create a dummy package directory and __init__.py\nos.makedirs('mypackage', exist_ok=True)\nwith open('mypackage/__init__.py', 'w') as f:\n    f.write(\"\"\"import lazy_loader as lazy\n\n__getattr__, __dir__, _ = lazy.attach(\n    __name__, __file__,\n    subpackages=[\n        'heavy_module', # This will be lazily loaded\n    ],\n    attributes={\n        'my_utility_func': ('some_utility_module', 'my_utility_func') # Example for external functions\n    }\n)\n\n# If you also wanted to lazy load an external library directly (less common in __init__.py)\n# external_lib = lazy.load('sys') # Example: lazily load 'sys'\n\"\"\")\n\nprint(\"Before importing mypackage\")\nimport mypackage\nprint(\"After importing mypackage (heavy_module not yet loaded)\")\n\n# Accessing an attribute of mypackage.heavy_module triggers its load\nresult = mypackage.heavy_module.expensive_func()\nprint(f\"Accessed heavy_module: {result}\")\n\n# Clean up dummy files\nos.remove('heavy_module.py')\nos.remove('mypackage/__init__.py')\nos.rmdir('mypackage')","lang":"python","description":"This example demonstrates how to use `lazy.attach` within a package's `__init__.py` to lazily load submodules. The `heavy_module` is only imported (and its 'imported!' message printed) when one of its attributes is first accessed, not during the initial `import mypackage` statement. This is the primary use case for `lazy-loader` to improve package import times."},"warnings":[{"fix":"For `lazy-loader` versions 0.4 and later, do not use the `subpackages` argument with `lazy.attach()`. Instead, `lazy.attach(__name__, __file__)` should be used for the package itself. Subpackage lazy loading should be handled by explicitly defining `__getattr__` or `__dir__` to return submodules, or by using `lazy.load` within these functions. If you require the functionality of `subpackages` for `lazy.attach`, you would need to downgrade to `lazy-loader` version `0.3.x`.","message":"The `subpackages` argument for `lazy.attach()` was removed in `lazy-loader` version 0.4. Attempting to use this argument will result in a `TypeError`. The previous recommendation for lazily loading subpackages using this argument is no longer valid.","severity":"breaking","affected_versions":"0.4 and later"},{"fix":"Upgrade Python to version 3.11.9 or later, or 3.12.3 or later, to avoid these known race conditions.","message":"Users on specific patch versions of Python 3.11 and 3.12 may encounter a known race condition due to upstream Python bugs affecting `lazy-loader`'s functionality.","severity":"breaking","affected_versions":"<3.11.9, <3.12.3"},{"fix":"Set the `EAGER_IMPORT` environment variable to `1` (e.g., `EAGER_IMPORT=1 python your_script.py`) to force eager loading of all modules managed by `lazy-loader`. This allows import errors to surface immediately upon program startup.","message":"Lazy loading can defer import errors until runtime, making early detection of missing dependencies or typos harder during development. For debugging, `lazy-loader` can be disabled.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure the package name in the `require` argument precisely matches the distribution name. For example, `pyyaml` is the distribution name for the `yaml` module.","message":"When using the `require` argument in `lazy.load()` to specify version requirements (e.g., `lazy.load('numpy', require='numpy>=1.24')`), the requirement string must use the *package distribution name* (as found on PyPI), not necessarily the module import name.","severity":"gotcha","affected_versions":"0.4 and later"}],"env_vars":null,"search_vec":"'0.5':56 'access':48 'activ':51 'actual':47 'bug':66 'current':53 'defer':39 'demand':18 'design':22 'easi':10 'ecosystem':31 'enhanc':62 'especi':26 'fix':65 'function':16,63 'help':24 'import':41,44,69 'lazi':1,5,67 'lazy-load':4 'librari':7 'load':12,68,74 'loader':2,6 'maintain':52 'make':8 'memori':36 'modul':40,73 'object':45 'optim':70 'perform':72 'project':25 'python':13,30,76 'reduc':32 'regular':59 'scientif':29,75 'see':58 'startup':33,71 'subpackag':14 'time':34 'updat':60 'usag':37 'util':20 'version':55","created_at":"2026-03-29T06:06:28.475360+00:00","updated_at":"2026-04-16T16:10:48.069284+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5","cli_name":"","cli_version":null,"type":"library","homepage":"https://scientific-python.org/specs/spec-0001/","github":"https://github.com/scientific-python/lazy-loader","docs":null,"changelog":null,"pypi":"https://pypi.org/project/lazy-loader/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":"verified"}}