Lazy Registry#

When your library exposes many optional modules (formats, plugins, adapters), LazyRegistry helps avoid eager imports at startup.

Basic Pattern#

from depdigest import LazyRegistry

formats = LazyRegistry(
    package_prefix="my_package.formats",
    directory="my_package/formats",
    attr_name="format_name",
)

Entry Point Mode (Optional)#

If your plugin ecosystem uses Python entry points, you can switch discovery mode:

from depdigest import LazyRegistry

formats = LazyRegistry(
    package_prefix="my_package.formats",
    directory="/unused",
    attr_name="format_name",
    discovery_mode="entry_points",
    entrypoint_group="my_package.formats",
)

Key points:

  • entrypoint_group is required for discovery_mode="entry_points".

  • MAPPING still applies, using entry point names as mapping keys.

  • Soft-dependency visibility filtering remains the same.

What Happens Under the Hood#

  • Directory entries are scanned lazily.

  • Each candidate module is imported only when registry is initialized.

  • If MAPPING links a folder to a soft dependency and capability visibility is restricted, unavailable entries can be skipped.

  • Plugin import failures are non-fatal and can be reported through diagnostics.

Required Convention#

Each module should expose the attribute used by attr_name.

Example:

# my_package/formats/openmm_form/__init__.py
format_name = "openmm"

Next#

Continue with Introspection to show dependency status to your users.