Add type checking considerations

Author: smheidrich

source/guides/handling-missing-extras-at-runtime.rst

@@ -123,6 +123,8 @@ just raise a custom exception indicating which extra would be required:
 
 .. code-block:: python
 
+   from dataclasses import dataclass
+
    @dataclass
    class MissingExtra(Exception):
      name: str
@@ -196,29 +198,59 @@ import when the functionality requiring it is actually used. E.g.:
 
 .. code-block:: python
 
-   def import_extra_func_if_avail():
+   def import_extra_module_if_avail():
      # surround this with the appropriate checks / error handling:
      ...
-     from your_optional_dependency import extra_func
+     import your_optional_dependency
      ...
 
-     return extra_func
+     return your_optional_dependency
 
    ...
 
    def some_func_requiring_your_extra():
      try:
-       some_function = import_extra_func_if_avail()
+       optional_module = import_extra_module_if_avail()
      except MissingExtra:
        ...  # handle missing extra
 
+     # now you can use functionality from the optional dependency, e.g.:
+     optional_module.extra_func(...)
+
 While this solution is more robust than the one from the preceding subsection,
-it can take more effort to make it work with static type checking.
+it can take more effort to make it work with
+:term:`static type checking <static type checker>`:
+To correctly statically type a function returning a module, you'd have to
+introduce an "artificial" type representing the latter, e.g.
+
+.. code-block:: python
+
+   from typing import cast, Protocol
+
+   class YourOptionalModuleType(Protocol):
+     extra_func: Callable[...]
+     ...  # other objects you want to use
+
+   def some_func_requiring_your_extra() -> YourOptionalModuleType:
+     ...
+
+     return cast(YourOptionalModuleType, optional_module)
+
+An alternative would be to instead have functions that import and return only
+the objects you actually need:
+
+.. code-block:: python
+
+   def import_extra_func_if_avail() -> Callable[...]:
+     # surround this with the appropriate checks / error handling:
+     ...
+     from your_optional_dependency import extra_func
+     ...
+
+     return extra_func
 
-Interaction with static type checking
-=====================================
+But this can become verbose when you import a lot of names.
 
-TODO either put here or directly in previous sections... not sure
 
 Other considerations
 ====================