From c7aadf189fd77a0c1fae9f060fbd38629d35567b Mon Sep 17 00:00:00 2001 From: Stefan van der Walt Date: Fri, 16 Sep 2022 16:43:32 -0700 Subject: [PATCH] Refer to SPEC for stub usage --- README.md | 41 +++++++---------------------------------- 1 file changed, 7 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 02c9670..24ae77b 100644 --- a/README.md +++ b/README.md @@ -72,42 +72,15 @@ from .edges import (sobel, scharr, prewitt, roberts, Except that all subpackages (such as `rank`) and functions (such as `sobel`) are loaded upon access. -### Lazily load subpackages and functions from type stubs +### Type checkers -Because static type checkers and IDEs will likely be unable to find your -dynamically declared imports, you can use a [type -stub](https://mypy.readthedocs.io/en/stable/stubs.html) (`.pyi` file) to declare -the imports. However, if used with the above pattern, this results in code -duplication, as you now need to declare your submodules and attributes in two places. +Static type checkers and IDEs cannot infer type information from +lazily loaded imports. As a workaround you can load [type +stubs](https://mypy.readthedocs.io/en/stable/stubs.html) (`.pyi` +files) with `lazy.attach_stub`. -You can infer the `submodules` and `submod_attrs` arguments (explicitly provided -above to `lazy.attach`) from a stub adjacent to the `.py` file by using the -`lazy.attach_stub` function. - -Carrying on with the example above: - -The `skimage/filters/__init__.py` module would be declared as such: - -```python -from ..util import lazy - -__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__) -``` - -... and the adjacent `skimage/filters/__init__.pyi` stub would contain: - -```python -from . import rank -from ._gaussian import gaussian, difference_of_gaussians -from .edges import (sobel, scharr, prewitt, roberts, - laplace, farid) -``` - -Note that in order for this to work, you must be sure to include the `.pyi` -files in your package distribution. For example, with setuptools, you would need -to [set the `package_data` -option](https://setuptools.pypa.io/en/latest/userguide/datafiles.html#package-data) -to include `*.pyi` files. +The SPEC [describes this workaround in more +detail](https://scientific-python.org/specs/spec-0001/#type-checkers). ### Early failure