pdoc 14.0.0__tar.gz → 14.2.0__tar.gz

{pdoc-14.0.0 → pdoc-14.2.0}/CHANGELOG.md

@@ -4,6 +4,38 @@
 
 <!-- ✨ You do not need to add a pull request reference or an author, this will be added automatically by CI. ✨ -->
 
+## 2023-12-13: pdoc 14.2.0
+
+ - pdoc now documents PyO3 or pybind11 submodules that are not picked up by Python's builtin pkgutil module.
+   ([#633](https://github.com/mitmproxy/pdoc/issues/633), @mhils)
+ - pdoc now supports Python 3.12's `type` statements and has improved `TypeAlias` rendering.
+   ([#651](https://github.com/mitmproxy/pdoc/pull/651), @mhils)
+ - Imports in a TYPE_CHECKING section that reference members defined in another module's TYPE_CHECKING section now work
+   correctly.
+   ([#649](https://github.com/mitmproxy/pdoc/pull/649), @mhils)
+ - Add support for `code-block` ReST directives
+   ([#624](https://github.com/mitmproxy/pdoc/pull/624), @JCGoran)
+ - If a variable's value meets certain entropy criteria and matches an environment variable value,
+   pdoc will now emit a warning and display the variable's name as a placeholder instead.
+   This heuristic is meant to prevent accidental leakage of environment secrets and can be disabled by setting
+   `PDOC_DISPLAY_ENV_VARS=1`.
+   ([#622](https://github.com/mitmproxy/pdoc/pull/622), @mhils)
+
+## 2023-09-10: pdoc 14.1.0
+
+ - Add compatibility with Python 3.12
+   ([#620](https://github.com/mitmproxy/pdoc/pull/620), @mhils)
+ - Add support for relative links. Instead of explicitly referring to `mypackage.helpers.foo`,
+   one can now also refer to `.helpers.foo` within the `mypackage` module, or `..helpers.foo` in a submodule.
+   ([#544](https://github.com/mitmproxy/pdoc/pull/544), @Crozzers)
+ - Function signatures will now display "Foo" instead "demo.Foo" if the function is in the same module.
+   ([#544](https://github.com/mitmproxy/pdoc/pull/544), @mhils)
+ - pdoc now also picks up docstrings from `.pyi` stub files.
+   ([#619](https://github.com/mitmproxy/pdoc/pull/619), @mhils)
+ - Fix horizontal scroll navigation z-index issue.
+   ([#616](https://github.com/mitmproxy/pdoc/pull/616), @Domi04151309)
+ - Be more strict about parsing URLs in pdoc's web server.
+   ([#617](https://github.com/mitmproxy/pdoc/pull/617), @mhils)
 
 ## 2023-06-19: pdoc 14.0.0
 

{pdoc-14.0.0/pdoc.egg-info → pdoc-14.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.0.0
+Version: 14.2.0
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
 License: Unlicense
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
@@ -30,7 +31,7 @@ License-File: LICENSE
 <a href="https://pdoc.dev/"><img alt="pdoc" src="https://pdoc.dev/logo.svg" width="200" height="100" /></a>
 <br><br>
 <a href="https://pdoc.dev/docs/pdoc.html"><img height="20" alt="pdoc documentation" src="https://shields.mitmproxy.org/badge/docs-pdoc.dev-brightgreen.svg"></a>
-<img height="20" alt="CI Status" src="https://shields.mitmproxy.org/github/workflow/status/mitmproxy/pdoc/CI?label=CI&logo=github">
+<img height="20" alt="CI Status" src="https://shields.mitmproxy.org/github/actions/workflow/status/mitmproxy/pdoc/main.yml?label=CI&logo=github">
 <img height="20" alt="Code Coverage" src="https://shields.mitmproxy.org/badge/coverage-100%25-brightgreen">
 <a href="https://autofix.ci"><img height="20" alt="autofix.ci: yes" src="https://shields.mitmproxy.org/badge/autofix.ci-yes-success?logo=data:image/svg+xml;base64,PHN2ZyBmaWxsPSIjZmZmIiB2aWV3Qm94PSIwIDAgMTI4IDEyOCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCB0cmFuc2Zvcm09InNjYWxlKDAuMDYxLC0wLjA2MSkgdHJhbnNsYXRlKC0yNTAsLTE3NTApIiBkPSJNMTMyNSAtMzQwcS0xMTUgMCAtMTY0LjUgMzIuNXQtNDkuNSAxMTQuNXEwIDMyIDUgNzAuNXQxMC41IDcyLjV0NS41IDU0djIyMHEtMzQgLTkgLTY5LjUgLTE0dC03MS41IC01cS0xMzYgMCAtMjUxLjUgNjJ0LTE5MSAxNjl0LTkyLjUgMjQxcS05MCAxMjAgLTkwIDI2NnEwIDEwOCA0OC41IDIwMC41dDEzMiAxNTUuNXQxODguNSA4MXExNSA5OSAxMDAuNSAxODAuNXQyMTcgMTMwLjV0MjgyLjUgNDlxMTM2IDAgMjU2LjUgLTQ2IHQyMDkgLTEyNy41dDEyOC41IC0xODkuNXExNDkgLTgyIDIyNyAtMjEzLjV0NzggLTI5OS41cTAgLTEzNiAtNTggLTI0NnQtMTY1LjUgLTE4NC41dC0yNTYuNSAtMTAzLjVsLTI0MyAtMzAwdi01MnEwIC0yNyAzLjUgLTU2LjV0Ni41IC01Ny41dDMgLTUycTAgLTg1IC00MS41IC0xMTguNXQtMTU3LjUgLTMzLjV6TTEzMjUgLTI2MHE3NyAwIDk4IDE0LjV0MjEgNTcuNXEwIDI5IC0zIDY4dC02LjUgNzN0LTMuNSA0OHY2NGwyMDcgMjQ5IHEtMzEgMCAtNjAgNS41dC01NCAxMi41bC0xMDQgLTEyM3EtMSAzNCAtMiA2My41dC0xIDU0LjVxMCA2OSA5IDEyM2wzMSAyMDBsLTExNSAtMjhsLTQ2IC0yNzFsLTIwNSAyMjZxLTE5IC0xNSAtNDMgLTI4LjV0LTU1IC0yNi41bDIxOSAtMjQydi0yNzZxMCAtMjAgLTUuNSAtNjB0LTEwLjUgLTc5dC01IC01OHEwIC00MCAzMCAtNTMuNXQxMDQgLTEzLjV6TTEyNjIgNjE2cS0xMTkgMCAtMjI5LjUgMzQuNXQtMTkzLjUgOTYuNWw0OCA2NCBxNzMgLTU1IDE3MC41IC04NXQyMDQuNSAtMzBxMTM3IDAgMjQ5IDQ1LjV0MTc5IDEyMXQ2NyAxNjUuNWg4MHEwIC0xMTQgLTc3LjUgLTIwNy41dC0yMDggLTE0OXQtMjg5LjUgLTU1LjV6TTgwMyA1OTVxODAgMCAxNDkgMjkuNXQxMDggNzIuNWwyMjEgLTY3bDMwOSA4NnE0NyAtMzIgMTA0LjUgLTUwdDExNy41IC0xOHE5MSAwIDE2NSAzOHQxMTguNSAxMDMuNXQ0NC41IDE0Ni41cTAgNzYgLTM0LjUgMTQ5dC05NS41IDEzNHQtMTQzIDk5IHEtMzcgMTA3IC0xMTUuNSAxODMuNXQtMTg2IDExNy41dC0yMzAuNSA0MXEtMTAzIDAgLTE5Ny41IC0yNnQtMTY5IC03Mi41dC0xMTcuNSAtMTA4dC00MyAtMTMxLjVxMCAtMzQgMTQuNSAtNjIuNXQ0MC41IC01MC41bC01NSAtNTlxLTM0IDI5IC01NCA2NS41dC0yNSA4MS41cS04MSAtMTggLTE0NSAtNzB0LTEwMSAtMTI1LjV0LTM3IC0xNTguNXEwIC0xMDIgNDguNSAtMTgwLjV0MTI5LjUgLTEyM3QxNzkgLTQ0LjV6Ii8+PC9zdmc+"></a>
 <a href="https://pypi.python.org/pypi/pdoc"><img height="20" alt="PyPI Version" src="https://shields.mitmproxy.org/pypi/v/pdoc.svg"></a>

{pdoc-14.0.0 → pdoc-14.2.0}/README.md

@@ -2,7 +2,7 @@
 <a href="https://pdoc.dev/"><img alt="pdoc" src="https://pdoc.dev/logo.svg" width="200" height="100" /></a>
 <br><br>
 <a href="https://pdoc.dev/docs/pdoc.html"><img height="20" alt="pdoc documentation" src="https://shields.mitmproxy.org/badge/docs-pdoc.dev-brightgreen.svg"></a>
-<img height="20" alt="CI Status" src="https://shields.mitmproxy.org/github/workflow/status/mitmproxy/pdoc/CI?label=CI&logo=github">
+<img height="20" alt="CI Status" src="https://shields.mitmproxy.org/github/actions/workflow/status/mitmproxy/pdoc/main.yml?label=CI&logo=github">
 <img height="20" alt="Code Coverage" src="https://shields.mitmproxy.org/badge/coverage-100%25-brightgreen">
 <a href="https://autofix.ci"><img height="20" alt="autofix.ci: yes" src="https://shields.mitmproxy.org/badge/autofix.ci-yes-success?logo=data:image/svg+xml;base64,PHN2ZyBmaWxsPSIjZmZmIiB2aWV3Qm94PSIwIDAgMTI4IDEyOCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCB0cmFuc2Zvcm09InNjYWxlKDAuMDYxLC0wLjA2MSkgdHJhbnNsYXRlKC0yNTAsLTE3NTApIiBkPSJNMTMyNSAtMzQwcS0xMTUgMCAtMTY0LjUgMzIuNXQtNDkuNSAxMTQuNXEwIDMyIDUgNzAuNXQxMC41IDcyLjV0NS41IDU0djIyMHEtMzQgLTkgLTY5LjUgLTE0dC03MS41IC01cS0xMzYgMCAtMjUxLjUgNjJ0LTE5MSAxNjl0LTkyLjUgMjQxcS05MCAxMjAgLTkwIDI2NnEwIDEwOCA0OC41IDIwMC41dDEzMiAxNTUuNXQxODguNSA4MXExNSA5OSAxMDAuNSAxODAuNXQyMTcgMTMwLjV0MjgyLjUgNDlxMTM2IDAgMjU2LjUgLTQ2IHQyMDkgLTEyNy41dDEyOC41IC0xODkuNXExNDkgLTgyIDIyNyAtMjEzLjV0NzggLTI5OS41cTAgLTEzNiAtNTggLTI0NnQtMTY1LjUgLTE4NC41dC0yNTYuNSAtMTAzLjVsLTI0MyAtMzAwdi01MnEwIC0yNyAzLjUgLTU2LjV0Ni41IC01Ny41dDMgLTUycTAgLTg1IC00MS41IC0xMTguNXQtMTU3LjUgLTMzLjV6TTEzMjUgLTI2MHE3NyAwIDk4IDE0LjV0MjEgNTcuNXEwIDI5IC0zIDY4dC02LjUgNzN0LTMuNSA0OHY2NGwyMDcgMjQ5IHEtMzEgMCAtNjAgNS41dC01NCAxMi41bC0xMDQgLTEyM3EtMSAzNCAtMiA2My41dC0xIDU0LjVxMCA2OSA5IDEyM2wzMSAyMDBsLTExNSAtMjhsLTQ2IC0yNzFsLTIwNSAyMjZxLTE5IC0xNSAtNDMgLTI4LjV0LTU1IC0yNi41bDIxOSAtMjQydi0yNzZxMCAtMjAgLTUuNSAtNjB0LTEwLjUgLTc5dC01IC01OHEwIC00MCAzMCAtNTMuNXQxMDQgLTEzLjV6TTEyNjIgNjE2cS0xMTkgMCAtMjI5LjUgMzQuNXQtMTkzLjUgOTYuNWw0OCA2NCBxNzMgLTU1IDE3MC41IC04NXQyMDQuNSAtMzBxMTM3IDAgMjQ5IDQ1LjV0MTc5IDEyMXQ2NyAxNjUuNWg4MHEwIC0xMTQgLTc3LjUgLTIwNy41dC0yMDggLTE0OXQtMjg5LjUgLTU1LjV6TTgwMyA1OTVxODAgMCAxNDkgMjkuNXQxMDggNzIuNWwyMjEgLTY3bDMwOSA4NnE0NyAtMzIgMTA0LjUgLTUwdDExNy41IC0xOHE5MSAwIDE2NSAzOHQxMTguNSAxMDMuNXQ0NC41IDE0Ni41cTAgNzYgLTM0LjUgMTQ5dC05NS41IDEzNHQtMTQzIDk5IHEtMzcgMTA3IC0xMTUuNSAxODMuNXQtMTg2IDExNy41dC0yMzAuNSA0MXEtMTAzIDAgLTE5Ny41IC0yNnQtMTY5IC03Mi41dC0xMTcuNSAtMTA4dC00MyAtMTMxLjVxMCAtMzQgMTQuNSAtNjIuNXQ0MC41IC01MC41bC01NSAtNTlxLTM0IDI5IC01NCA2NS41dC0yNSA4MS41cS04MSAtMTggLTE0NSAtNzB0LTEwMSAtMTI1LjV0LTM3IC0xNTguNXEwIC0xMDIgNDguNSAtMTgwLjV0MTI5LjUgLTEyM3QxNzkgLTQ0LjV6Ii8+PC9zdmc+"></a>
 <a href="https://pypi.python.org/pypi/pdoc"><img height="20" alt="PyPI Version" src="https://shields.mitmproxy.org/pypi/v/pdoc.svg"></a>

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/__init__.py

@@ -180,13 +180,14 @@ ways.
 - If `__all__` is defined in the module, then all identifiers in that list will be considered public.
    No other identifiers will be considered public.
 - If `__all__` is not defined, then pdoc will consider all members public that
-   1. do not start with an underscore
+   1. do not start with an underscore,
+   2. don't have `@private` in their docstring,
    2. and are defined in the current module (i.e. they are not imported).
 
 In general, we recommend keeping these conventions:
 
 - If you want to document a private member, consider making it public.
-- If you want to hide a public member, consider making it private.
+- If you want to hide a public member, consider making it private or add `@private` to their docstring,
 - If you want to document a special `__dunder__` method, the recommended way to do so is
   to not document the dunder method specifically, but to add some usage examples in the class documentation.
 
@@ -461,7 +462,7 @@ You can find an example in [`examples/library-usage`](https://github.com/mitmpro
 from __future__ import annotations
 
 __docformat__ = "markdown"  # explicitly disable rST processing in the examples above.
-__version__ = "14.0.0"  # this is read from setup.py
+__version__ = "14.2.0"  # this is read from setup.py
 
 from pathlib import Path
 from typing import overload

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/__main__.py

@@ -112,7 +112,7 @@ renderopts.add_argument(
     "--search",
     action=BooleanOptionalAction,
     default=True,
-    help="Enable search functionality.",
+    help="Enable search functionality if multiple modules are documented.",
 )
 renderopts.add_argument(
     "--show-source",

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/_compat.py

@@ -16,6 +16,24 @@ else:  # pragma: no cover
     def ast_unparse(t):  # type: ignore
         return _unparse(t).strip("\t\n \"'")
 
+if sys.version_info >= (3, 12):
+    from ast import TypeAlias as ast_TypeAlias
+else:  # pragma: no cover
+    class ast_TypeAlias:
+        pass
+
+if sys.version_info >= (3, 12):
+    from typing import TypeAliasType
+else:  # pragma: no cover
+    class TypeAliasType:
+        """Placeholder class for TypeAliasType"""
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:  # pragma: no cover
+    class TypeAlias:
+        pass
+
 if sys.version_info >= (3, 9):
     from types import GenericAlias
 else:  # pragma: no cover
@@ -43,65 +61,6 @@ else:  # pragma: no cover
             x = x[len(prefix):]
         return x
 
-if sys.version_info >= (3, 8):
-    from functools import cached_property
-else:  # pragma: no cover
-    from threading import RLock
-
-    # https://github.com/python/cpython/blob/863eb7170b3017399fb2b786a1e3feb6457e54c2/Lib/functools.py#L930-L980
-    # ✂ start ✂
-    _NOT_FOUND = object()
-
-    class cached_property:  # type: ignore
-        def __init__(self, func):
-            self.func = func
-            self.attrname = None
-            self.__doc__ = func.__doc__
-            self.lock = RLock()
-
-        def __set_name__(self, owner, name):
-            if self.attrname is None:
-                self.attrname = name
-            elif name != self.attrname:
-                raise TypeError(
-                    "Cannot assign the same cached_property to two different names "
-                    f"({self.attrname!r} and {name!r})."
-                )
-
-        def __get__(self, instance, owner=None):
-            if instance is None:
-                return self
-            if self.attrname is None:
-                raise TypeError(
-                    "Cannot use cached_property instance without calling __set_name__ on it.")
-            try:
-                cache = instance.__dict__
-            except AttributeError:  # not all objects have __dict__ (e.g. class defines slots)
-                msg = (
-                    f"No '__dict__' attribute on {type(instance).__name__!r} "
-                    f"instance to cache {self.attrname!r} property."
-                )
-                raise TypeError(msg) from None
-            val = cache.get(self.attrname, _NOT_FOUND)
-            if val is _NOT_FOUND:
-                with self.lock:
-                    # check if another thread filled cache while we awaited lock
-                    val = cache.get(self.attrname, _NOT_FOUND)
-                    if val is _NOT_FOUND:
-                        val = self.func(instance)
-                        try:
-                            cache[self.attrname] = val
-                        except TypeError:
-                            msg = (
-                                f"The '__dict__' attribute on {type(instance).__name__!r} instance "
-                                f"does not support item assignment for caching {self.attrname!r} property."
-                            )
-                            raise TypeError(msg) from None
-            return val
-
-        __class_getitem__ = classmethod(GenericAlias)
-    # ✂ end ✂
-
 
 if (3, 9) <= sys.version_info < (3, 9, 8) or (3, 10) <= sys.version_info < (3, 10, 1):  # pragma: no cover
     import inspect
@@ -117,12 +76,6 @@ if (3, 9) <= sys.version_info < (3, 9, 8) or (3, 10) <= sys.version_info < (3, 1
 else:
     from inspect import formatannotation
 
-if sys.version_info >= (3, 8):
-    from functools import singledispatchmethod
-else:  # pragma: no cover
-    class singledispatchmethod:
-        pass  # pragma: no cover
-
 if sys.version_info >= (3, 9):
     from argparse import BooleanOptionalAction
 else:  # pragma: no cover
@@ -173,11 +126,12 @@ else:  # pragma: no cover
 __all__ = [
     "cache",
     "ast_unparse",
+    "ast_TypeAlias",
+    "TypeAliasType",
+    "TypeAlias",
     "GenericAlias",
     "UnionType",
     "removesuffix",
-    "cached_property",
     "formatannotation",
-    "singledispatchmethod",
     "BooleanOptionalAction",
 ]

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/doc.py

@@ -22,11 +22,12 @@ from abc import abstractmethod
 from collections.abc import Callable
 import dataclasses
 import enum
+from functools import cached_property
+from functools import singledispatchmethod
 from functools import wraps
 import inspect
 import os
 from pathlib import Path
-import pkgutil
 import re
 import sys
 import textwrap
@@ -43,17 +44,16 @@ import warnings
 from pdoc import doc_ast
 from pdoc import doc_pyi
 from pdoc import extract
+from pdoc._compat import TypeAlias
+from pdoc._compat import TypeAliasType
+from pdoc._compat import cache
+from pdoc._compat import formatannotation
 from pdoc.doc_types import GenericAlias
 from pdoc.doc_types import NonUserDefinedCallables
 from pdoc.doc_types import empty
 from pdoc.doc_types import resolve_annotations
 from pdoc.doc_types import safe_eval_type
 
-from ._compat import cache
-from ._compat import cached_property
-from ._compat import formatannotation
-from ._compat import singledispatchmethod
-
 
 def _include_fullname_in_traceback(f):
     """
@@ -454,9 +454,6 @@ class Module(Namespace[types.ModuleType]):
     @cached_property
     def submodules(self) -> list[Module]:
         """A list of all (direct) submodules."""
-        if not self.is_package:
-            return []
-
         include: Callable[[str], bool]
         mod_all = _safe_getattr(self.obj, "__all__", False)
         if mod_all is not False:
@@ -471,9 +468,8 @@ class Module(Namespace[types.ModuleType]):
                 # (think of OS-specific modules, e.g. _linux.py failing to import on Windows).
                 return not name.startswith("_")
 
-        submodules = []
-        for mod in pkgutil.iter_modules(self.obj.__path__, f"{self.fullname}."):
-            _, _, mod_name = mod.name.rpartition(".")
+        submodules: list[Module] = []
+        for mod_name, mod in extract.iter_modules2(self.obj).items():
             if not include(mod_name):
                 continue
             try:
@@ -1006,7 +1002,9 @@ class Function(Doc[types.FunctionType]):
                 )
             )
         for p in sig.parameters.values():
-            p._annotation = safe_eval_type(p.annotation, globalns, localns, mod, self.fullname)  # type: ignore
+            p._annotation = safe_eval_type(  # type: ignore
+                p.annotation, globalns, localns, mod, self.fullname
+            )
         return sig
 
     @cached_property
@@ -1092,6 +1090,11 @@ class Variable(Doc[None]):
         else:
             return False
 
+    @cached_property
+    def is_type_alias_type(self) -> bool:
+        """`True` if the variable is a `typing.TypeAliasType`, `False` otherwise."""
+        return isinstance(self.default_value, TypeAliasType)
+
     @cached_property
     def is_enum_member(self) -> bool:
         """`True` if the variable is an enum member, `False` otherwise."""
@@ -1105,6 +1108,27 @@ class Variable(Doc[None]):
         """The variable's default value as a pretty-printed str."""
         if self.default_value is empty:
             return ""
+        if isinstance(self.default_value, TypeAliasType):
+            return formatannotation(self.default_value.__value__)
+        elif self.annotation == TypeAlias:
+            return formatannotation(self.default_value)
+
+        # This is not perfect, but a solid attempt at preventing accidental leakage of secrets.
+        # If you have input on how to improve the heuristic, please send a pull request!
+        value_taken_from_env_var = (
+            isinstance(self.default_value, str)
+            and len(self.default_value) >= 8
+            and self.default_value in _environ_lookup()
+        )
+        if value_taken_from_env_var and not os.environ.get("PDOC_DISPLAY_ENV_VARS", ""):
+            env_var = "$" + _environ_lookup()[self.default_value]
+            warnings.warn(
+                f"The default value of {self.fullname} matches the {env_var} environment variable. "
+                f"To prevent accidental leakage of secrets, the default value is not displayed. "
+                f"Disable this behavior by setting PDOC_DISPLAY_ENV_VARS=1 as an environment variable.",
+                RuntimeWarning,
+            )
+            return env_var
 
         try:
             pretty = repr(self.default_value)
@@ -1124,6 +1148,14 @@ class Variable(Doc[None]):
             return ""
 
 
+@cache
+def _environ_lookup():
+    """
+    A reverse lookup of os.environ. This is a cached function so that it is evaluated lazily.
+    """
+    return {value: key for key, value in os.environ.items()}
+
+
 class _PrettySignature(inspect.Signature):
     """
     A subclass of `inspect.Signature` that pads __str__ over several lines

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/doc_ast.py

@@ -21,6 +21,7 @@ import warnings
 
 import pdoc
 
+from ._compat import ast_TypeAlias
 from ._compat import ast_unparse
 from ._compat import cache
 
@@ -115,7 +116,11 @@ def _walk_tree(
     func_docstrings = {}
     annotations = {}
     for a, b in _pairwise_longest(_nodes(tree)):
-        if isinstance(a, ast.AnnAssign) and isinstance(a.target, ast.Name) and a.simple:
+        if isinstance(a, ast_TypeAlias):
+            name = a.name.id
+        elif (
+            isinstance(a, ast.AnnAssign) and isinstance(a.target, ast.Name) and a.simple
+        ):
             name = a.target.id
             annotations[name] = unparse(a.annotation)
         elif (
@@ -183,6 +188,8 @@ def sort_by_source(
             name = a.target.id
         elif isinstance(a, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
             name = a.name
+        elif isinstance(a, ast_TypeAlias):
+            name = a.name.id
         else:
             continue
 

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/doc_pyi.py

@@ -70,16 +70,12 @@ def _patch_doc(target_doc: doc.Doc, stub_mod: doc.Module) -> None:
     if isinstance(target_doc, doc.Function) and isinstance(stub_doc, doc.Function):
         target_doc.signature = stub_doc.signature
         target_doc.funcdef = stub_doc.funcdef
+        target_doc.docstring = stub_doc.docstring or target_doc.docstring
     elif isinstance(target_doc, doc.Variable) and isinstance(stub_doc, doc.Variable):
         target_doc.annotation = stub_doc.annotation
+        target_doc.docstring = stub_doc.docstring or target_doc.docstring
     elif isinstance(target_doc, doc.Namespace) and isinstance(stub_doc, doc.Namespace):
-        # pdoc currently does not include variables without docstring in .members (not ideal),
-        # so the regular patching won't work. We manually copy over type annotations instead.
-        for k, v in stub_doc._var_annotations.items():
-            var = target_doc.members.get(k, None)
-            if isinstance(var, doc.Variable):
-                var.annotation = v
-
+        target_doc.docstring = stub_doc.docstring or target_doc.docstring
         for m in target_doc.members.values():
             _patch_doc(m, stub_mod)
     else:

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/doc_types.py

@@ -124,9 +124,9 @@ def safe_eval_type(
 
     # Simple _eval_type has failed. We now execute all TYPE_CHECKING sections in the module and try again.
     if module:
+        assert module.__dict__ is globalns
         try:
-            code = compile(type_checking_sections(module), "<string>", "exec")
-            eval(code, globalns, globalns)
+            _eval_type_checking_sections(module, set())
         except Exception as e:
             warnings.warn(
                 f"Failed to run TYPE_CHECKING code while parsing {t} type annotation for {fullname}: {e}"
@@ -148,7 +148,34 @@ def safe_eval_type(
             f"Error parsing type annotation {t} for {fullname}. Import of {mod} failed: {err}"
         )
         return t
-    return safe_eval_type(t, {mod: val, **globalns}, localns, module, fullname)
+    else:
+        globalns[mod] = val
+    return safe_eval_type(t, globalns, localns, module, fullname)
+
+
+def _eval_type_checking_sections(module: types.ModuleType, seen: set) -> None:
+    """
+    Evaluate all TYPE_CHECKING sections within a module.
+
+    The added complication here is that TYPE_CHECKING sections may import members from other modules' TYPE_CHECKING
+    sections. So we try to recursively execute those other modules' TYPE_CHECKING sections as well.
+    See https://github.com/mitmproxy/pdoc/issues/648 for a real world example.
+    """
+    if module.__name__ in seen:
+        raise RecursionError(f"Recursion error when importing {module.__name__}.")
+    seen.add(module.__name__)
+
+    code = compile(type_checking_sections(module), "<string>", "exec")
+    while True:
+        try:
+            eval(code, module.__dict__, module.__dict__)
+        except ImportError as e:
+            if e.name is not None and (mod := sys.modules.get(e.name, None)):
+                _eval_type_checking_sections(mod, seen)
+            else:
+                raise
+        else:
+            break
 
 
 def _eval_type(t, globalns, localns, recursive_guard=frozenset()):

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/docstrings.py

@@ -393,7 +393,9 @@ def _rst_admonitions(contents: str, source_file: Path | None) -> str:
                 f"{indent(contents, ind)}\n"
                 f"{ind}</div>\n"
             )
-        elif type == "versionadded":
+        if type == "code-block":
+            return f"{ind}```{val}\n{contents}\n```\n"
+        if type == "versionadded":
             text = f"New in version {val}"
         elif type == "versionchanged":
             text = f"Changed in version {val}"
@@ -409,7 +411,7 @@ def _rst_admonitions(contents: str, source_file: Path | None) -> str:
 
         return text
 
-    admonition = "note|warning|danger|versionadded|versionchanged|deprecated|seealso|math|include"
+    admonition = "note|warning|danger|versionadded|versionchanged|deprecated|seealso|math|include|code-block"
     return re.sub(
         rf"""
             ^(?P<indent>[ ]*)\.\.[ ]+(?P<type>{admonition})::(?P<val>.*)

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/extract.py

@@ -204,9 +204,7 @@ def mock_some_common_side_effects():
         "os.startfile", new=_noop, create=True
     ), patch("sys.stdout", new=io.StringIO()), patch(
         "sys.stderr", new=io.StringIO()
-    ), patch(
-        "sys.stdin", new=io.StringIO()
-    ):
+    ), patch("sys.stdin", new=io.StringIO()):
         yield
 
 
@@ -229,22 +227,71 @@ but we don't want to catch a user's KeyboardInterrupt.
 """
 
 
+def iter_modules2(module: types.ModuleType) -> dict[str, pkgutil.ModuleInfo]:
+    """
+    Returns all direct child modules of a given module.
+    This function is similar to `pkgutil.iter_modules`, but
+
+      1. Respects a package's `__all__` attribute if specified.
+         If `__all__` is defined, submodules not listed in `__all__` are excluded.
+      2. It will try to detect submodules that are not findable with iter_modules,
+         but are present in the module object.
+    """
+    mod_all = getattr(module, "__all__", None)
+
+    submodules = {}
+
+    for submodule in pkgutil.iter_modules(
+        getattr(module, "__path__", []), f"{module.__name__}."
+    ):
+        name = submodule.name.rpartition(".")[2]
+        if mod_all is None or name in mod_all:
+            submodules[name] = submodule
+
+    # 2023-12: PyO3 and pybind11 submodules are not detected by pkgutil
+    # This is a hacky workaround to register them.
+    members = dir(module) if mod_all is None else mod_all
+    for name in members:
+        if name in submodules or name == "__main__":
+            continue
+        member = getattr(module, name, None)
+        is_wild_child_module = (
+            isinstance(member, types.ModuleType)
+            # the name is either just "bar", but can also be "foo.bar",
+            # see https://github.com/PyO3/pyo3/issues/759#issuecomment-1811992321
+            and (
+                member.__name__ == f"{module.__name__}.{name}"
+                or (
+                    member.__name__ == name
+                    and sys.modules.get(member.__name__, None) is not member
+                )
+            )
+        )
+        if is_wild_child_module:
+            # fixup the module name so that the rest of pdoc does not break
+            assert member
+            member.__name__ = f"{module.__name__}.{name}"
+            sys.modules[f"{module.__name__}.{name}"] = member
+            submodules[name] = pkgutil.ModuleInfo(
+                None,  # type: ignore
+                name=f"{module.__name__}.{name}",
+                ispkg=True,
+            )
+
+    submodules.pop("__main__", None)  # https://github.com/mitmproxy/pdoc/issues/438
+
+    return submodules
+
+
 def walk_packages2(
     modules: Iterable[pkgutil.ModuleInfo],
 ) -> Iterator[pkgutil.ModuleInfo]:
     """
     For a given list of modules, recursively yield their names and all their submodules' names.
 
-    This function is similar to `pkgutil.walk_packages`, but respects a package's `__all__` attribute if specified.
-    If `__all__` is defined, submodules not listed in `__all__` are excluded.
+    This function is similar to `pkgutil.walk_packages`, but based on `iter_modules2`.
     """
-
-    # noinspection PyDefaultArgument
-    def seen(p, m={}):  # pragma: no cover
-        if p in m:
-            return True
-        m[p] = True
-
+    # the original walk_packages implementation has a recursion check for path, but that does not seem to be needed?
     for mod in modules:
         yield mod
 
@@ -255,19 +302,8 @@ def walk_packages2(
                 warnings.warn(f"Error loading {mod.name}:\n{traceback.format_exc()}")
                 continue
 
-            mod_all = getattr(module, "__all__", None)
-            # don't traverse path items we've seen before
-            path = [p for p in (getattr(module, "__path__", None) or []) if not seen(p)]
-
-            submodules = []
-            for submodule in pkgutil.iter_modules(path, f"{mod.name}."):
-                name = submodule.name.rpartition(".")[2]
-                if name == "__main__":
-                    continue  # https://github.com/mitmproxy/pdoc/issues/438
-                if mod_all is None or name in mod_all:
-                    submodules.append(submodule)
-
-            yield from walk_packages2(submodules)
+            submodules = iter_modules2(module)
+            yield from walk_packages2(submodules.values())
 
 
 def module_mtime(modulename: str) -> float | None:

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/render_helpers.py

@@ -43,7 +43,7 @@ formatter = pygments.formatters.HtmlFormatter(
     anchorlinenos=True,
 )
 """
-The pygments formatter used for pdoc.render_helpers.highlight. 
+The pygments formatter used for pdoc.render_helpers.highlight.
 Overwrite this to configure pygments highlighting of code blocks.
 
 The usage of the `.codehilite` CSS selector in custom templates is deprecated since pdoc 10, use `.pdoc-code` instead.
@@ -51,7 +51,7 @@ The usage of the `.codehilite` CSS selector in custom templates is deprecated si
 
 signature_formatter = pygments.formatters.HtmlFormatter(nowrap=True)
 """
-The pygments formatter used for pdoc.render_helpers.format_signature. 
+The pygments formatter used for pdoc.render_helpers.format_signature.
 Overwrite this to configure pygments highlighting of signatures.
 """
 
@@ -287,13 +287,30 @@ def linkify(context: Context, code: str, namespace: str = "") -> str:
             '</span><span class="o">.</span><span class="n">', "."
         )
         identifier = removesuffix(plain_text, "()")
-
-        # Check if this is a local reference within this module?
         mod: pdoc.doc.Module = context["module"]
-        for qualname in qualname_candidates(identifier, namespace):
-            doc = mod.get(qualname)
-            if doc and context["is_public"](doc).strip():
-                return f'<a href="#{qualname}">{plain_text}</a>'
+
+        # Check if this is a relative reference?
+        if identifier.startswith("."):
+            taken_from_mod = mod
+            if namespace and (ns := mod.get(namespace)):
+                # Imported from somewhere else, so the relative reference should be from the original module.
+                taken_from_mod = context["all_modules"].get(ns.taken_from[0], mod)
+            if taken_from_mod.is_package:
+                # If we are in __init__.py, we want `.foo` to refer to a child module.
+                parent_module = taken_from_mod.modulename
+            else:
+                # If we are in a leaf module, we want `.foo` to refer to the adjacent module.
+                parent_module = taken_from_mod.modulename.rpartition(".")[0]
+            while identifier.startswith(".."):
+                identifier = identifier[1:]
+                parent_module = parent_module.rpartition(".")[0]
+            identifier = parent_module + identifier
+        else:
+            # Check if this is a local reference within this module?
+            for qualname in qualname_candidates(identifier, namespace):
+                doc = mod.get(qualname)
+                if doc and context["is_public"](doc).strip():
+                    return f'<a href="#{qualname}">{plain_text}</a>'
 
         module = ""
         qualname = ""
@@ -309,9 +326,9 @@ def linkify(context: Context, code: str, namespace: str = "") -> str:
                     and context["is_public"](doc).strip()
                 ):
                     if plain_text.endswith("()"):
-                        plain_text = f"{doc.fullname}()"
+                        plain_text = f"{doc.qualname}()"
                     else:
-                        plain_text = doc.fullname
+                        plain_text = doc.qualname
                     return f'<a href="#{qualname}">{plain_text}</a>'
         except ValueError:
             # possible_sources did not find a parent module.
@@ -326,8 +343,13 @@ def linkify(context: Context, code: str, namespace: str = "") -> str:
                 doc is not None and context["is_public"](doc).strip()
             )
             if target_exists_and_public:
+                assert doc is not None  # mypy
                 if qualname:
                     qualname = f"#{qualname}"
+                if plain_text.endswith("()"):
+                    plain_text = f"{doc.fullname}()"
+                else:
+                    plain_text = doc.fullname
                 return f'<a href="{relative_link(context["module"].modulename, module)}{qualname}">{plain_text}</a>'
             else:
                 return text
@@ -337,11 +359,14 @@ def linkify(context: Context, code: str, namespace: str = "") -> str:
             r"""
             # Part 1: foo.bar or foo.bar() (without backticks)
             (?<![/=?#&])  # heuristic: not part of a URL
-            \b
-            
-            # First part of the identifier (e.g. "foo")    
-            (?!\d)[a-zA-Z0-9_]+
-            # Rest of the identifier (e.g. ".bar")
+            # First part of the identifier (e.g. "foo") - this is optional for relative references.
+            (?:
+                \b
+                (?!\d)[a-zA-Z0-9_]+
+                |
+                \.*  # We may also start with multiple dots.
+            )
+            # Rest of the identifier (e.g. ".bar" or "..bar")
             (?:
                 # A single dot or a dot surrounded with pygments highlighting.
                 (?:\.|</span><span\ class="o">\.</span><span\ class="n">)

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/search.py

@@ -5,6 +5,11 @@ and works without any third-party services in a privacy-preserving way. When a u
 search box for the first time, pdoc will fetch the search index (`search.js`) and use that to
 answer all upcoming queries.
 
+##### Single-Page Documentation
+
+If pdoc is documenting a single module only, search functionality will be disabled.
+The browser's built-in search functionality will provide a better user experience in these cases.
+
 ##### Search Coverage
 
 The search functionality covers all documented elements and their docstrings.

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/templates/content.css

@@ -128,7 +128,7 @@ This makes sure that the pdoc styling doesn't leak to the rest of the page when
     padding: .2em .4em;
     margin: 0;
     font-size: 85%;
-    background-color: var(--code);
+    background-color: var(--accent);
     border-radius: 6px;
 }
 

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/templates/default/module.html.jinja2

@@ -177,6 +177,7 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
     {% endif %}
 {% enddefaultmacro %}
 {% defaultmacro variable(var) -%}
+    {%- if var.is_type_alias_type %}<span class="def">type</span> {% endif -%}
     <span class="name">{{ var.name }}</span>{{ annotation(var) }}{{ default_value(var) }}
 {% enddefaultmacro %}
 {% defaultmacro submodule(mod) -%}

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/templates/layout.css

@@ -124,7 +124,8 @@ nav.pdoc {
     padding: 0 0 0 var(--pad);
     overflow-wrap: anywhere;
     scrollbar-width: thin; /* Scrollbar width on Firefox */
-    scrollbar-color: var(--accent2) transparent /* Scrollbar color on Firefox */
+    scrollbar-color: var(--accent2) transparent; /* Scrollbar color on Firefox */
+    z-index: 1
 }
 
 nav.pdoc::-webkit-scrollbar {

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc/web.py

@@ -40,7 +40,7 @@ class DocHandler(http.server.BaseHTTPRequestHandler):
         except ConnectionError:  # pragma: no cover
             pass
 
-    def handle_request(self) -> str | None:
+    def handle_request(self) -> str:
         """Actually handle a request. Called by `do_HEAD` and `do_GET`."""
         path = self.path.split("?", 1)[0]
 
@@ -51,6 +51,13 @@ class DocHandler(http.server.BaseHTTPRequestHandler):
             self.send_header("content-type", "application/javascript")
             self.end_headers()
             return self.server.render_search_index()
+        elif "." in removesuffix(path, ".html"):
+            # See https://github.com/mitmproxy/pdoc/issues/615: All module separators should be normalized to "/".
+            # We could redirect here, but that would create the impression of a working link, which will fall apart
+            # when pdoc prerenders to static HTML. So we rather fail early.
+            self.send_response(404)
+            self.end_headers()
+            return "Not Found: Please normalize all module separators to '/'."
         else:
             module_name = removesuffix(path.lstrip("/"), ".html").replace("/", ".")
             if module_name not in self.server.all_modules:

{pdoc-14.0.0 → pdoc-14.2.0/pdoc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.0.0
+Version: 14.2.0
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
 License: Unlicense
@@ -20,6 +20,7 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
@@ -30,7 +31,7 @@ License-File: LICENSE
 <a href="https://pdoc.dev/"><img alt="pdoc" src="https://pdoc.dev/logo.svg" width="200" height="100" /></a>
 <br><br>
 <a href="https://pdoc.dev/docs/pdoc.html"><img height="20" alt="pdoc documentation" src="https://shields.mitmproxy.org/badge/docs-pdoc.dev-brightgreen.svg"></a>
-<img height="20" alt="CI Status" src="https://shields.mitmproxy.org/github/workflow/status/mitmproxy/pdoc/CI?label=CI&logo=github">
+<img height="20" alt="CI Status" src="https://shields.mitmproxy.org/github/actions/workflow/status/mitmproxy/pdoc/main.yml?label=CI&logo=github">
 <img height="20" alt="Code Coverage" src="https://shields.mitmproxy.org/badge/coverage-100%25-brightgreen">
 <a href="https://autofix.ci"><img height="20" alt="autofix.ci: yes" src="https://shields.mitmproxy.org/badge/autofix.ci-yes-success?logo=data:image/svg+xml;base64,PHN2ZyBmaWxsPSIjZmZmIiB2aWV3Qm94PSIwIDAgMTI4IDEyOCIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCB0cmFuc2Zvcm09InNjYWxlKDAuMDYxLC0wLjA2MSkgdHJhbnNsYXRlKC0yNTAsLTE3NTApIiBkPSJNMTMyNSAtMzQwcS0xMTUgMCAtMTY0LjUgMzIuNXQtNDkuNSAxMTQuNXEwIDMyIDUgNzAuNXQxMC41IDcyLjV0NS41IDU0djIyMHEtMzQgLTkgLTY5LjUgLTE0dC03MS41IC01cS0xMzYgMCAtMjUxLjUgNjJ0LTE5MSAxNjl0LTkyLjUgMjQxcS05MCAxMjAgLTkwIDI2NnEwIDEwOCA0OC41IDIwMC41dDEzMiAxNTUuNXQxODguNSA4MXExNSA5OSAxMDAuNSAxODAuNXQyMTcgMTMwLjV0MjgyLjUgNDlxMTM2IDAgMjU2LjUgLTQ2IHQyMDkgLTEyNy41dDEyOC41IC0xODkuNXExNDkgLTgyIDIyNyAtMjEzLjV0NzggLTI5OS41cTAgLTEzNiAtNTggLTI0NnQtMTY1LjUgLTE4NC41dC0yNTYuNSAtMTAzLjVsLTI0MyAtMzAwdi01MnEwIC0yNyAzLjUgLTU2LjV0Ni41IC01Ny41dDMgLTUycTAgLTg1IC00MS41IC0xMTguNXQtMTU3LjUgLTMzLjV6TTEzMjUgLTI2MHE3NyAwIDk4IDE0LjV0MjEgNTcuNXEwIDI5IC0zIDY4dC02LjUgNzN0LTMuNSA0OHY2NGwyMDcgMjQ5IHEtMzEgMCAtNjAgNS41dC01NCAxMi41bC0xMDQgLTEyM3EtMSAzNCAtMiA2My41dC0xIDU0LjVxMCA2OSA5IDEyM2wzMSAyMDBsLTExNSAtMjhsLTQ2IC0yNzFsLTIwNSAyMjZxLTE5IC0xNSAtNDMgLTI4LjV0LTU1IC0yNi41bDIxOSAtMjQydi0yNzZxMCAtMjAgLTUuNSAtNjB0LTEwLjUgLTc5dC01IC01OHEwIC00MCAzMCAtNTMuNXQxMDQgLTEzLjV6TTEyNjIgNjE2cS0xMTkgMCAtMjI5LjUgMzQuNXQtMTkzLjUgOTYuNWw0OCA2NCBxNzMgLTU1IDE3MC41IC04NXQyMDQuNSAtMzBxMTM3IDAgMjQ5IDQ1LjV0MTc5IDEyMXQ2NyAxNjUuNWg4MHEwIC0xMTQgLTc3LjUgLTIwNy41dC0yMDggLTE0OXQtMjg5LjUgLTU1LjV6TTgwMyA1OTVxODAgMCAxNDkgMjkuNXQxMDggNzIuNWwyMjEgLTY3bDMwOSA4NnE0NyAtMzIgMTA0LjUgLTUwdDExNy41IC0xOHE5MSAwIDE2NSAzOHQxMTguNSAxMDMuNXQ0NC41IDE0Ni41cTAgNzYgLTM0LjUgMTQ5dC05NS41IDEzNHQtMTQzIDk5IHEtMzcgMTA3IC0xMTUuNSAxODMuNXQtMTg2IDExNy41dC0yMzAuNSA0MXEtMTAzIDAgLTE5Ny41IC0yNnQtMTY5IC03Mi41dC0xMTcuNSAtMTA4dC00MyAtMTMxLjVxMCAtMzQgMTQuNSAtNjIuNXQ0MC41IC01MC41bC01NSAtNTlxLTM0IDI5IC01NCA2NS41dC0yNSA4MS41cS04MSAtMTggLTE0NSAtNzB0LTEwMSAtMTI1LjV0LTM3IC0xNTguNXEwIC0xMDIgNDguNSAtMTgwLjV0MTI5LjUgLTEyM3QxNzkgLTQ0LjV6Ii8+PC9zdmc+"></a>
 <a href="https://pypi.python.org/pypi/pdoc"><img height="20" alt="PyPI Version" src="https://shields.mitmproxy.org/pypi/v/pdoc.svg"></a>

{pdoc-14.0.0 → pdoc-14.2.0}/pdoc.egg-info/requires.txt

@@ -8,7 +8,6 @@ astunparse
 [dev]
 tox
 ruff
-black
 mypy
 types-pygments
 pytest
@@ -16,3 +15,4 @@ pytest-cov
 pytest-timeout
 hypothesis
 pygments>=2.14.0
+pdoc-pyo3-sample-library==1.0.11

{pdoc-14.0.0 → pdoc-14.2.0}/pyproject.toml

@@ -27,6 +27,7 @@ classifiers = [
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
     "Typing :: Typed",
 ]
 
@@ -43,7 +44,6 @@ pdoc = "pdoc.__main__:cli"
 dev = [
     "tox",
     "ruff",
-    "black",
     "mypy",
     "types-pygments",
     "pytest",
@@ -51,6 +51,7 @@ dev = [
     "pytest-timeout",
     "hypothesis",
     "pygments >= 2.14.0",
+    "pdoc-pyo3-sample-library==1.0.11",
 ]
 
 [build-system]
@@ -88,9 +89,6 @@ markers = [
     "slow: marks tests as slow.",
 ]
 
-[tool.black]
-extend-exclude = "test/testdata/demo.py"
-
 [[tool.mypy.overrides]]
 module = "pytest.*"
 ignore_missing_imports = true
@@ -100,8 +98,9 @@ module = "demopackage2"
 ignore_missing_imports = true
 
 [tool.ruff]
-line-length = 140
+extend-exclude = ["test/testdata/demo.py"]
 select = ["E", "F", "I"]
+ignore = ["E501"]
 
 [tool.ruff.isort]
 force-single-line = true

{pdoc-14.0.0 → pdoc-14.2.0}/test/test_doc.py

@@ -11,6 +11,7 @@ from pdoc import extract
 from pdoc.doc import Class
 from pdoc.doc import Module
 from pdoc.doc import Variable
+from pdoc.doc import _environ_lookup
 from pdoc.doc_types import empty
 
 here = Path(__file__).parent
@@ -143,3 +144,34 @@ def test_raising_submodules():
             assert m.submodules
     finally:
         f.write_bytes(b"# syntax error will be inserted by test here\n")
+
+
+def test_default_value_masks_env_vars(monkeypatch):
+    monkeypatch.setenv("SUPER_SECRET_TOKEN", "correct horse battery staple")
+    monkeypatch.setenv("VERSION_NUMBER", "42.0.1")
+    _environ_lookup.cache_clear()
+    try:
+        v1 = Variable(
+            "module",
+            "var",
+            taken_from=("module", "var"),
+            docstring="",
+            annotation=empty,
+            default_value="correct horse battery staple",
+        )
+        with pytest.warns(
+            match=r"The default value of module.var matches the \$SUPER_SECRET_TOKEN environment variable."
+        ):
+            assert v1.default_value_str == "$SUPER_SECRET_TOKEN"
+
+        v2 = Variable(
+            "module",
+            "version",
+            taken_from=("module", "version"),
+            docstring="",
+            annotation=empty,
+            default_value="42.0.1",
+        )
+        assert v2.default_value_str == "'42.0.1'"
+    finally:
+        _environ_lookup.cache_clear()

{pdoc-14.0.0 → pdoc-14.2.0}/test/test_doc_types.py

@@ -12,8 +12,9 @@ from pdoc.doc_types import safe_eval_type
     "typestr", ["totally_unknown_module", "!!!!", "html.unknown_attr"]
 )
 def test_eval_fail(typestr):
+    a = types.ModuleType("a")
     with pytest.warns(UserWarning, match="Error parsing type annotation"):
-        assert safe_eval_type(typestr, {}, None, types.ModuleType("a"), "a") == typestr
+        assert safe_eval_type(typestr, a.__dict__, None, a, "a") == typestr
 
 
 def test_eval_fail2(monkeypatch):
@@ -22,8 +23,9 @@ def test_eval_fail2(monkeypatch):
         "get_source",
         lambda _: "import typing\nif typing.TYPE_CHECKING:\n\traise RuntimeError()",
     )
+    a = types.ModuleType("a")
     with pytest.warns(UserWarning, match="Failed to run TYPE_CHECKING code"):
-        assert safe_eval_type("xyz", {}, None, types.ModuleType("a"), "a") == "xyz"
+        assert safe_eval_type("xyz", a.__dict__, None, a, "a") == "xyz"
 
 
 def test_eval_fail3(monkeypatch):
@@ -32,16 +34,24 @@ def test_eval_fail3(monkeypatch):
         "get_source",
         lambda _: "import typing\nif typing.TYPE_CHECKING:\n\tFooFn = typing.Callable[[],int]",
     )
+    a = types.ModuleType("a")
+    a.__dict__["typing"] = typing
     with pytest.warns(
         UserWarning,
         match="Error parsing type annotation .+ after evaluating TYPE_CHECKING blocks",
     ):
-        assert (
-            safe_eval_type(
-                "FooFn[int]", {"typing": typing}, None, types.ModuleType("a"), "a"
-            )
-            == "FooFn[int]"
-        )
+        assert safe_eval_type("FooFn[int]", a.__dict__, None, a, "a") == "FooFn[int]"
+
+
+def test_eval_fail_import_nonexistent(monkeypatch):
+    monkeypatch.setattr(
+        doc_ast,
+        "get_source",
+        lambda _: "import typing\nif typing.TYPE_CHECKING:\n\timport nonexistent_module",
+    )
+    a = types.ModuleType("a")
+    with pytest.warns(UserWarning, match="No module named 'nonexistent_module'"):
+        assert safe_eval_type("xyz", a.__dict__, None, a, "a") == "xyz"
 
 
 def test_eval_union_types_on_old_python(monkeypatch):
@@ -53,3 +63,21 @@ def test_eval_union_types_on_old_python(monkeypatch):
     ):
         # str never implements `|`, so we can use that to trigger the error on newer versions.
         safe_eval_type('"foo" | "bar"', {}, None, None, "example")
+
+
+def test_recurse(monkeypatch):
+    def get_source(mod):
+        if mod == a:
+            return "import typing\nif typing.TYPE_CHECKING:\n\tfrom b import Foo"
+        else:
+            return "import typing\nif typing.TYPE_CHECKING:\n\tfrom a import Foo"
+
+    a = types.ModuleType("a")
+    b = types.ModuleType("b")
+
+    monkeypatch.setattr(doc_ast, "get_source", get_source)
+    monkeypatch.setitem(sys.modules, "a", a)
+    monkeypatch.setitem(sys.modules, "b", b)
+
+    with pytest.warns(UserWarning, match="Recursion error when importing a"):
+        assert safe_eval_type("xyz", a.__dict__, None, a, "a") == "xyz"

{pdoc-14.0.0 → pdoc-14.2.0}/test/test_extract.py

@@ -27,6 +27,7 @@ def test_walk_specs():
         "demopackage._child_e",
         "demopackage.child_b",
         "demopackage.child_c",
+        "demopackage.subpackage",
     ]
     with pytest.raises(ValueError, match="No modules found matching spec: unknown"):
         with pytest.warns(UserWarning, match="Cannot find spec for unknown"):
@@ -59,6 +60,14 @@ def test_walk_specs():
         "test.mod_with_main.__main__",
     ]
 
+    assert walk_specs(["pdoc_pyo3_sample_library"]) == [
+        "pdoc_pyo3_sample_library",
+        "pdoc_pyo3_sample_library.submodule",
+        "pdoc_pyo3_sample_library.submodule.subsubmodule",
+        "pdoc_pyo3_sample_library.explicit_submodule",
+        "pdoc_pyo3_sample_library.correct_name_submodule",
+    ]
+
 
 def test_parse_spec(monkeypatch):
     p = sys.path

{pdoc-14.0.0 → pdoc-14.2.0}/test/test_snapshot.py

@@ -29,14 +29,14 @@ class Snapshot:
     def __init__(
         self,
         id: str,
-        filenames: list[str] | None = None,
+        specs: list[str] | None = None,
         render_options: dict | None = None,
         with_output_directory: bool = False,
         min_version: tuple[int, int] = (3, 7),
         warnings: list[str] | None = None,
     ):
         self.id = id
-        self.specs = filenames or [f"{id}.py"]
+        self.specs = specs or [f"{id}.py"]
         self.render_options = render_options or {}
         self.with_output_directory = with_output_directory
         self.min_version = min_version
@@ -145,6 +145,7 @@ snapshots = [
         min_version=(3, 12),
     ),
     Snapshot("math_demo", render_options={"math": True}),
+    Snapshot("math_misc", render_options={"math": True}),
     Snapshot("mermaid_demo", render_options={"mermaid": True}, min_version=(3, 9)),
     Snapshot(
         "render_options",
@@ -159,8 +160,9 @@ snapshots = [
         },
         with_output_directory=True,
     ),
+    Snapshot("pyo3_sample_library", specs=["pdoc_pyo3_sample_library"]),
     Snapshot("top_level_reimports", ["top_level_reimports"]),
-    Snapshot("type_checking_imports"),
+    Snapshot("type_checking_imports", ["type_checking_imports.main"]),
     Snapshot("type_stub", min_version=(3, 10)),
     Snapshot(
         "visibility",

{pdoc-14.0.0 → pdoc-14.2.0}/test/test_web.py

@@ -91,3 +91,9 @@ def test_get_module_mtime():
 
 def test_get_unknown():
     assert b"404 Not Found" in handle_request(b"GET /unknown HTTP/1.1\r\n\r\n")
+
+
+def test_get_not_normalized():
+    assert b"Not Found: Please normalize all module separators" in handle_request(
+        b"GET /module.submodule HTTP/1.1\r\n\r\n"
+    )