From 1302afbe09e6a3e80c40b72d14dd19458b6767d4 Mon Sep 17 00:00:00 2001 From: Stefan van der Walt Date: Thu, 15 Sep 2022 15:44:07 -0700 Subject: [PATCH] Describe why my_func.py should be defined in _my_func.py, instead of my_func.py --- spec-0001/index.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/spec-0001/index.md b/spec-0001/index.md index ef0626dd..27454c72 100644 --- a/spec-0001/index.md +++ b/spec-0001/index.md @@ -224,6 +224,13 @@ __getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__) _Note that if you use a type stub, you will need to take additional action to add the `.pyi` file to your sdist and wheel distributions. See [PEP 561](https://peps.python.org/pep-0561/) and the [mypy documentation](https://mypy.readthedocs.io/en/stable/installed_packages.html#creating-pep-561-compatible-packages) for more information._ +#### Caveats + +Thus far, we are aware of one corner case in which lazy loading does not work. +This is when you define a lazily loaded function, say `my_func`, in a file of the same name (`my_func.py`) **AND** run doctests. +Somehow, the doctest collector modifies the parent module's `__dict__` to include `my_func` (the module, not the function), essentially short circuiting the lazy loader and its ability to provide `my_module.my_func` (the function). +Fortunately, there is an easy way to address this that already aligns with common practice: define `my_func` inside `_my_func.py` instead (note the underscore). + ## Implementation Lazy loading is implemented at