lazy-loader 0.4

lazy_loader使得按需加载子包和函数变得容易。

动机

1. 允许子包在不产生导入成本的情况下对用户可见。
2. 允许外部库仅在需要时导入，从而提高导入时间。

有关更详细的讨论，请参阅SPEC。

安装

pip install -U lazy_loader

我们建议使用Python >= 3.11的lazy_loader。如果使用Python 3.11，请升级到3.11.9或更高版本。如果使用Python 3.12，请升级到3.12.3或更高版本。这些版本避免了一个已知的竞争条件。

用法

懒加载子包

考虑来自scikit-image的__init__.py

subpackages = [
    ...,
    'filters',
    ...
]

import lazy_loader as lazy
__getattr__, __dir__, _ = lazy.attach(__name__, subpackages)

现在您可以这样做

import skimage as ski
ski.filters.gaussian(...)

只有在访问时才会加载filters子包。

懒加载子包和函数

考虑skimage/filters/__init__.py

from ..util import lazy

__getattr__, __dir__, __all__ = lazy.attach(
    __name__,
    submodules=['rank'],
    submod_attrs={
        '_gaussian': ['gaussian', 'difference_of_gaussians'],
        'edges': ['sobel', 'scharr', 'prewitt', 'roberts',
                  'laplace', 'farid']
    }
)

上面的代码等同于

from . import rank
from ._gaussian import gaussian, difference_of_gaussians
from .edges import (sobel, scharr, prewitt, roberts,
                    laplace, farid)

不同之处在于，所有子包（如rank）和函数（如sobel）在访问时都会被加载。

类型检查器

静态类型检查器和IDE无法从懒加载导入中推断类型信息。作为解决方案，您可以使用lazy.attach_stub加载类型存根（.pyi文件）。

import lazy_loader as lazy
__getattr__, __dir__, _ = lazy.attach_stub(__name__, "subpackages.pyi")

请注意，由于导入现在定义在.pyi文件中，它们不仅对类型检查是必要的，在运行时也是必要的。

SPEC 详细描述了此解决方案。

早期失败

使用懒加载，缺失的导入在加载库时不再失败。在开发和测试期间，您可以设置EAGER_IMPORT环境变量来禁用懒加载。

外部库

上面讨论的lazy.attach函数用于设置包内部导入。

使用lazy.load来懒加载外部库

sp = lazy.load('scipy')  # `sp` will only be loaded when accessed
sp.linalg.norm(...)

请注意，懒加载子包，即load('scipy.linalg')将导致包含子包的包立即导入；因此，不建议使用此用法。

您可以要求lazy.load在调用时立即引发导入错误

linalg = lazy.load('scipy.linalg', error_on_import=True)

可选要求

懒加载的一个用途是加载可选依赖项，只有当访问可选功能时才会出现ImportErrors。如果可选功能依赖于特定版本，可以设置版本要求

np = lazy.load("numpy", require="numpy >=1.24")

在这种情况下，如果安装了numpy，但版本小于1.24，则返回的np模块将在属性访问时引发错误。使用此功能不是全有或全无：一个模块可能依赖于numpy的一个版本，而另一个模块可能不设置任何要求。

请注意，要求必须使用分布名称而不是导入名称。例如，pyyaml分布为导入提供了yaml模块。