From bdd74a3f780a69f456c9b627da6d4901f3279bec Mon Sep 17 00:00:00 2001
From: Talley Lambert <talley.lambert@gmail.com>
Date: Wed, 6 Jul 2022 19:19:04 -0400
Subject: [PATCH 1/7] add caveats

---
 spec-0001/index.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/spec-0001/index.md b/spec-0001/index.md
index 266e6447..b0bc4f12 100644
--- a/spec-0001/index.md
+++ b/spec-0001/index.md
@@ -207,6 +207,65 @@ In the mean time, we now have the necessary mechanisms to implement it ourselves
 
 [^cannon]: Cannon B., personal communication, 7 January 2021.
 
+### Caveats
+
+While this pattern has benefits at runtime, it does have one specific drawback:
+
+Static type checkers (such as [mypy](http://mypy-lang.org) and
+[pyright](https://github.com/microsoft/pyright)) will not be able to infer the
+types and locations dynamically-loaded modules and functions. This means that some
+integrated development environments (e.g.
+[VS Code](https://code.visualstudio.com)) will not be able to provide code
+completion, parameter hints, documentation, or other features for any objects in your module.
+
+You can direct static type checkers to the actual location of dynamically loaded objects in one of two ways:
+
+1. Use an [`if
+   typing.TYPE_CHECKING`](https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING)
+   clause .
+
+   ```python
+    from typing import TYPE_CHECKING
+
+    import lazy_loader as lazy
+
+    if TYPE_CHECKING:
+        from .edges import sobel, sobel_h, sobel_v
+
+    __getattr__, __dir__, __all__ = lazy.attach(
+        __name__,
+        submod_attrs={
+            'edges': ['sobel', 'sobel_h', 'sobel_v']
+        }
+    )
+    ```
+
+    `typing.TYPE_CHECKING` is a special variable that is set to `False` at runtime, and has negative runtime impact. 
+
+2. Use a [type stub (`.pyi`) file](https://mypy.readthedocs.io/en/stable/stubs.html). Type stubs are ignored at runtime, but used
+by static type checkers. This method entails adding a new file with a `.pyi` extension in the same directory as your actual `.py`. For example:
+
+    ```python
+    # mypackage/__init__.py
+    import lazy_loader as lazy
+
+    __getattr__, __dir__, __all__ = lazy.attach(
+        __name__,
+        submod_attrs={
+            'edges': ['sobel', 'sobel_h', 'sobel_v']
+        }
+    )
+    ```
+
+    ```python
+    # mypackage/__init__.pyi
+    from .edges import sobel, sobel_h, sobel_v
+    ```
+
+    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.
+
+    It is also sometimes harder to keep `.pyi` in sync with `.py` files, as they more often go unnoticed by contributors.
+
 ### Core Project Endorsement
 
 <!--

From 63cb3f74831e32afcd3fc7031f9497795ba69f3e Mon Sep 17 00:00:00 2001
From: Talley Lambert <talley.lambert@gmail.com>
Date: Wed, 6 Jul 2022 19:21:14 -0400
Subject: [PATCH 2/7] add additional line

---
 spec-0001/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec-0001/index.md b/spec-0001/index.md
index b0bc4f12..152faba1 100644
--- a/spec-0001/index.md
+++ b/spec-0001/index.md
@@ -216,7 +216,7 @@ Static type checkers (such as [mypy](http://mypy-lang.org) and
 types and locations dynamically-loaded modules and functions. This means that some
 integrated development environments (e.g.
 [VS Code](https://code.visualstudio.com)) will not be able to provide code
-completion, parameter hints, documentation, or other features for any objects in your module.
+completion, parameter hints, documentation, or other features for any objects in your module.  Nor will `mypy` be able to detect potential errors in your user's code.
 
 You can direct static type checkers to the actual location of dynamically loaded objects in one of two ways:
 

From 220721ead0d58ebed3c3ffaeeb8c448d319fbada Mon Sep 17 00:00:00 2001
From: Talley Lambert <talley.lambert@gmail.com>
Date: Wed, 6 Jul 2022 19:36:31 -0400
Subject: [PATCH 3/7] lint

---
 spec-0001/index.md | 69 +++++++++++++++++++++++-----------------------
 1 file changed, 34 insertions(+), 35 deletions(-)

diff --git a/spec-0001/index.md b/spec-0001/index.md
index 152faba1..0f2d9b3d 100644
--- a/spec-0001/index.md
+++ b/spec-0001/index.md
@@ -216,55 +216,54 @@ Static type checkers (such as [mypy](http://mypy-lang.org) and
 types and locations dynamically-loaded modules and functions. This means that some
 integrated development environments (e.g.
 [VS Code](https://code.visualstudio.com)) will not be able to provide code
-completion, parameter hints, documentation, or other features for any objects in your module.  Nor will `mypy` be able to detect potential errors in your user's code.
+completion, parameter hints, documentation, or other features for any objects in your module. Nor will `mypy` be able to detect potential errors in your user's code.
 
 You can direct static type checkers to the actual location of dynamically loaded objects in one of two ways:
 
-1. Use an [`if
-   typing.TYPE_CHECKING`](https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING)
-   clause .
+1.  Use an [`if typing.TYPE_CHECKING`](https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING)
+    clause .
 
-   ```python
-    from typing import TYPE_CHECKING
+    ```python
+     from typing import TYPE_CHECKING
 
-    import lazy_loader as lazy
+     import lazy_loader as lazy
 
-    if TYPE_CHECKING:
-        from .edges import sobel, sobel_h, sobel_v
+     if TYPE_CHECKING:
+         from .edges import sobel, sobel_h, sobel_v
 
-    __getattr__, __dir__, __all__ = lazy.attach(
-        __name__,
-        submod_attrs={
-            'edges': ['sobel', 'sobel_h', 'sobel_v']
-        }
-    )
+     __getattr__, __dir__, __all__ = lazy.attach(
+         __name__,
+         submod_attrs={
+             'edges': ['sobel', 'sobel_h', 'sobel_v']
+         }
+     )
     ```
 
-    `typing.TYPE_CHECKING` is a special variable that is set to `False` at runtime, and has negative runtime impact. 
+    `typing.TYPE_CHECKING` is a special variable that is set to `False` at runtime, and has negative runtime impact.
 
-2. Use a [type stub (`.pyi`) file](https://mypy.readthedocs.io/en/stable/stubs.html). Type stubs are ignored at runtime, but used
-by static type checkers. This method entails adding a new file with a `.pyi` extension in the same directory as your actual `.py`. For example:
+2.  Use a [type stub (`.pyi`) file](https://mypy.readthedocs.io/en/stable/stubs.html). Type stubs are ignored at runtime, but used
+    by static type checkers. This method entails adding a new file with a `.pyi` extension in the same directory as your actual `.py`. For example:
 
-    ```python
-    # mypackage/__init__.py
-    import lazy_loader as lazy
-
-    __getattr__, __dir__, __all__ = lazy.attach(
-        __name__,
-        submod_attrs={
-            'edges': ['sobel', 'sobel_h', 'sobel_v']
-        }
-    )
-    ```
+        ```python
+        # mypackage/__init__.py
+        import lazy_loader as lazy
 
-    ```python
-    # mypackage/__init__.pyi
-    from .edges import sobel, sobel_h, sobel_v
-    ```
+        __getattr__, __dir__, __all__ = lazy.attach(
+            __name__,
+            submod_attrs={
+                'edges': ['sobel', 'sobel_h', 'sobel_v']
+            }
+        )
+        ```
+
+        ```python
+        # mypackage/__init__.pyi
+        from .edges import sobel, sobel_h, sobel_v
+        ```
 
-    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.
+        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.
 
-    It is also sometimes harder to keep `.pyi` in sync with `.py` files, as they more often go unnoticed by contributors.
+        It is also sometimes harder to keep `.pyi` in sync with `.py` files, as they more often go unnoticed by contributors.
 
 ### Core Project Endorsement
 

From f99a5e93bd963c95b35d28479ec147a4f25e9c20 Mon Sep 17 00:00:00 2001
From: Talley Lambert <talley.lambert@gmail.com>
Date: Thu, 7 Jul 2022 03:51:33 -0400
Subject: [PATCH 4/7] Update spec-0001/index.md

Co-authored-by: Juan Nunez-Iglesias <jni@fastmail.com>
---
 spec-0001/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec-0001/index.md b/spec-0001/index.md
index 0f2d9b3d..984b4391 100644
--- a/spec-0001/index.md
+++ b/spec-0001/index.md
@@ -239,7 +239,7 @@ You can direct static type checkers to the actual location of dynamically loaded
      )
     ```
 
-    `typing.TYPE_CHECKING` is a special variable that is set to `False` at runtime, and has negative runtime impact.
+    `typing.TYPE_CHECKING` is a special variable that is set to `False` at runtime, and has negligible runtime impact.
 
 2.  Use a [type stub (`.pyi`) file](https://mypy.readthedocs.io/en/stable/stubs.html). Type stubs are ignored at runtime, but used
     by static type checkers. This method entails adding a new file with a `.pyi` extension in the same directory as your actual `.py`. For example:

From 64279fbfef8f03d91cd8ebca7a122b98f5e7860e Mon Sep 17 00:00:00 2001
From: Talley Lambert <talley.lambert@gmail.com>
Date: Wed, 20 Jul 2022 13:32:08 -0400
Subject: [PATCH 5/7] update spec

---
 spec-0001/index.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/spec-0001/index.md b/spec-0001/index.md
index 0f2d9b3d..a63c6748 100644
--- a/spec-0001/index.md
+++ b/spec-0001/index.md
@@ -216,7 +216,7 @@ Static type checkers (such as [mypy](http://mypy-lang.org) and
 types and locations dynamically-loaded modules and functions. This means that some
 integrated development environments (e.g.
 [VS Code](https://code.visualstudio.com)) will not be able to provide code
-completion, parameter hints, documentation, or other features for any objects in your module. Nor will `mypy` be able to detect potential errors in your user's code.
+completion, parameter hints, documentation, or other features for any objects in your module. Nor will `mypy` be able to detect potential errors in your users' code.
 
 You can direct static type checkers to the actual location of dynamically loaded objects in one of two ways:
 
@@ -261,9 +261,16 @@ You can direct static type checkers to the actual location of dynamically loaded
         from .edges import sobel, sobel_h, sobel_v
         ```
 
-        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.
+    _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._
 
-        It is also sometimes harder to keep `.pyi` in sync with `.py` files, as they more often go unnoticed by contributors.
+3.  If you would like to avoid the unfortunate duplication of declaring exports in _both_ a type stub and in the arguments to `lazy.attach`, the aforementioned [lazy_loader](https://github.com/scientific-python/lazy_loader) package offers a [`lazy_loader.attach_stub` function](https://github.com/scientific-python/lazy_loader#lazily-load-subpackages-and-functions-from-type-stubs) that can be used to infer your module exports directly from your stub file – which now becomes the single source of truth for your module's exports. It is used as follows:
+
+    ```python
+    from lazy_loader import attach_stub
+
+    # this assumes there is a `.pyi` file adjacent to this module
+    __getattr__, __dir__, __all__ = attach_stub(__name__, __file__)
+    ```
 
 ### Core Project Endorsement
 

From 61f3f6ffe371810e229ecc839930e83b13d01712 Mon Sep 17 00:00:00 2001
From: Stefan van der Walt <stefanv@berkeley.edu>
Date: Mon, 12 Sep 2022 11:26:18 -0700
Subject: [PATCH 6/7] Reorganize stubs advice

---
 spec-0001/index.md | 117 ++++++++++++++++++++-------------------------
 1 file changed, 52 insertions(+), 65 deletions(-)

diff --git a/spec-0001/index.md b/spec-0001/index.md
index 168238f4..162febc0 100644
--- a/spec-0001/index.md
+++ b/spec-0001/index.md
@@ -7,6 +7,7 @@ author:
   - "Dan Schult <dschult@colgate.edu>"
 discussion: https://discuss.scientific-python.org/t/spec-1-lazy-loading-for-submodules/25
 endorsed-by:
+shortcutDepth: 3
 ---
 
 ## Description
@@ -172,6 +173,57 @@ be immediately raised with:
 linalg = lazy.load('scipy.linalg', error_on_import=True)
 ```
 
+#### Type checkers
+
+The lazy loading shown above has one drawback: static type checkers
+(such as [mypy](http://mypy-lang.org) and
+[pyright](https://github.com/microsoft/pyright)) will not be able to
+infer the types of lazy-loaded modules and functions.
+Therefore, `mypy` won't be able to detect potential errors, and
+integrated development environments such as [VS
+Code](https://code.visualstudio.com) won't provide code completion.
+
+To work around this limitation, we provide an alternative way to define lazy
+imports.
+Instead of importing modules and functions in `__init__.py`
+file with `lazy.attach`, you instead specify those imports in a `__init__.pyi`
+file—called a "type stub".
+Your `__init__.py` file then loads imports from the stub using `lazy.attach_stub`.
+
+Here's an example of how to convert this `__init__.py`:
+
+```python
+# mypackage/__init__.py
+import lazy_loader as lazy
+
+__getattr__, __dir__, __all__ = lazy.attach(
+    __name__,
+    submod_attrs={
+        'edges': ['sobel', 'sobel_h', 'sobel_v']
+    }
+)
+```
+
+1. Add a [type stub (`__init__.pyi`) file](https://mypy.readthedocs.io/en/stable/stubs.html) in the same directory as the `__init__.py`.
+   Type stubs are ignored at runtime, but used by static type checkers.
+
+   ```python
+   # mypackage/__init__.pyi
+   from .edges import sobel, sobel_h, sobel_v
+   ```
+
+   Replace `lazy.attach` in `mypackage/__init__.py` with a call to `attach_stub`:
+
+   ```python
+   import lazy_loader as lazy
+
+   # this assumes there is a `.pyi` file adjacent to this module
+   __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._
+
 ## Implementation
 
 Lazy loading is implemented at
@@ -207,71 +259,6 @@ In the mean time, we now have the necessary mechanisms to implement it ourselves
 
 [^cannon]: Cannon B., personal communication, 7 January 2021.
 
-### Caveats
-
-While this pattern has benefits at runtime, it does have one specific drawback:
-
-Static type checkers (such as [mypy](http://mypy-lang.org) and
-[pyright](https://github.com/microsoft/pyright)) will not be able to infer the
-types and locations dynamically-loaded modules and functions. This means that some
-integrated development environments (e.g.
-[VS Code](https://code.visualstudio.com)) will not be able to provide code
-completion, parameter hints, documentation, or other features for any objects in your module. Nor will `mypy` be able to detect potential errors in your users' code.
-
-You can direct static type checkers to the actual location of dynamically loaded objects in one of two ways:
-
-1.  Use an [`if typing.TYPE_CHECKING`](https://docs.python.org/3/library/typing.html#typing.TYPE_CHECKING)
-    clause .
-
-    ```python
-     from typing import TYPE_CHECKING
-
-     import lazy_loader as lazy
-
-     if TYPE_CHECKING:
-         from .edges import sobel, sobel_h, sobel_v
-
-     __getattr__, __dir__, __all__ = lazy.attach(
-         __name__,
-         submod_attrs={
-             'edges': ['sobel', 'sobel_h', 'sobel_v']
-         }
-     )
-    ```
-
-    `typing.TYPE_CHECKING` is a special variable that is set to `False` at runtime, and has negligible runtime impact.
-
-2.  Use a [type stub (`.pyi`) file](https://mypy.readthedocs.io/en/stable/stubs.html). Type stubs are ignored at runtime, but used
-    by static type checkers. This method entails adding a new file with a `.pyi` extension in the same directory as your actual `.py`. For example:
-
-        ```python
-        # mypackage/__init__.py
-        import lazy_loader as lazy
-
-        __getattr__, __dir__, __all__ = lazy.attach(
-            __name__,
-            submod_attrs={
-                'edges': ['sobel', 'sobel_h', 'sobel_v']
-            }
-        )
-        ```
-
-        ```python
-        # mypackage/__init__.pyi
-        from .edges import sobel, sobel_h, sobel_v
-        ```
-
-    _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._
-
-3.  If you would like to avoid the unfortunate duplication of declaring exports in _both_ a type stub and in the arguments to `lazy.attach`, the aforementioned [lazy_loader](https://github.com/scientific-python/lazy_loader) package offers a [`lazy_loader.attach_stub` function](https://github.com/scientific-python/lazy_loader#lazily-load-subpackages-and-functions-from-type-stubs) that can be used to infer your module exports directly from your stub file – which now becomes the single source of truth for your module's exports. It is used as follows:
-
-    ```python
-    from lazy_loader import attach_stub
-
-    # this assumes there is a `.pyi` file adjacent to this module
-    __getattr__, __dir__, __all__ = attach_stub(__name__, __file__)
-    ```
-
 ### Core Project Endorsement
 
 <!--

From 28c70447ebadbaccee72be749c0cbd9cf02f8231 Mon Sep 17 00:00:00 2001
From: Talley Lambert <talley.lambert@gmail.com>
Date: Mon, 12 Sep 2022 15:34:50 -0400
Subject: [PATCH 7/7] Update spec-0001/index.md

---
 spec-0001/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/spec-0001/index.md b/spec-0001/index.md
index 162febc0..1d87ab4b 100644
--- a/spec-0001/index.md
+++ b/spec-0001/index.md
@@ -204,7 +204,7 @@ __getattr__, __dir__, __all__ = lazy.attach(
 )
 ```
 
-1. Add a [type stub (`__init__.pyi`) file](https://mypy.readthedocs.io/en/stable/stubs.html) in the same directory as the `__init__.py`.
+Add a [type stub (`__init__.pyi`) file](https://mypy.readthedocs.io/en/stable/stubs.html) in the same directory as the `__init__.py`.
    Type stubs are ignored at runtime, but used by static type checkers.
 
    ```python