pdoc 14.1.0__py3-none-any.whl → 14.2.0__py3-none-any.whl

pdoc/__init__.py

@@ -462,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.1.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/__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/_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
@@ -108,6 +126,9 @@ else:  # pragma: no cover
 __all__ = [
     "cache",
     "ast_unparse",
+    "ast_TypeAlias",
+    "TypeAliasType",
+    "TypeAlias",
     "GenericAlias",
     "UnionType",
     "removesuffix",

pdoc/doc.py

@@ -28,7 +28,6 @@ from functools import wraps
 import inspect
 import os
 from pathlib import Path
-import pkgutil
 import re
 import sys
 import textwrap
@@ -45,15 +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 formatannotation
-
 
 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/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/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/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/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/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/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.1.0.dist-info → pdoc-14.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.1.0
+Version: 14.2.0
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
 License: Unlicense
@@ -32,7 +32,6 @@ Requires-Dist: astunparse ; python_version < "3.9"
 Provides-Extra: dev
 Requires-Dist: tox ; extra == 'dev'
 Requires-Dist: ruff ; extra == 'dev'
-Requires-Dist: black ; extra == 'dev'
 Requires-Dist: mypy ; extra == 'dev'
 Requires-Dist: types-pygments ; extra == 'dev'
 Requires-Dist: pytest ; extra == 'dev'
@@ -40,6 +39,7 @@ Requires-Dist: pytest-cov ; extra == 'dev'
 Requires-Dist: pytest-timeout ; extra == 'dev'
 Requires-Dist: hypothesis ; extra == 'dev'
 Requires-Dist: pygments (>=2.14.0) ; extra == 'dev'
+Requires-Dist: pdoc-pyo3-sample-library (==1.0.11) ; extra == 'dev'
 
 <p align="center">
 <a href="https://pdoc.dev/"><img alt="pdoc" src="https://pdoc.dev/logo.svg" width="200" height="100" /></a>

{pdoc-14.1.0.dist-info → pdoc-14.2.0.dist-info}/RECORD

@@ -1,16 +1,16 @@
-pdoc/__init__.py,sha256=o2yQAgRXRnoA-iHww7ZhtA96vfVJBR_6aP6QpHZBj0E,20792
-pdoc/__main__.py,sha256=YITnpb8Z3umr9R9ON8pM67VCn23tAkH0fVqD_V_NLQ8,8383
-pdoc/_compat.py,sha256=WY9q6C8oebb8tLQr7irndml5Wbc8vZwC8Y0nzY0Oumk,3343
-pdoc/doc.py,sha256=bEMXh43Ow4CPPVUS9G_OyyWq4syflEV01dK5l3RMzTo,46426
-pdoc/doc_ast.py,sha256=mNzq0REOh77zQgL2G8KEupHpWE36ECq-x5rEN51lp7Y,11202
+pdoc/__init__.py,sha256=YOPJ3nMnuABKGuQUQ1YNWhLXV8ANjZ917wU3jzn3ddI,20792
+pdoc/__main__.py,sha256=79uLvuQ8eHvU_tzXy4akpKMdDF2DN0xg5VPgv4pmyGo,8418
+pdoc/_compat.py,sha256=wKGKTxTTxfNjEcKPwvtuvNeOyiozPfL52h8PArKky-0,3843
+pdoc/doc.py,sha256=4FtcX8Pa3YJpY5-dobUcf7oAFypmjD232XSc6UEJeIg,47993
+pdoc/doc_ast.py,sha256=LBYx8NuXsoxqD_MsmDsI9ShMvOK0tnCDvu0Hv1hBies,11405
 pdoc/doc_pyi.py,sha256=u2PhgUEx46SUr3wZrlhkUVcs5mbzxuAizKYQevWRJys,3906
-pdoc/doc_types.py,sha256=NMIBtmoeEnDgDuw7rCKou2ARSIWO20SOaFwSzQuM5As,7474
-pdoc/docstrings.py,sha256=VMBMacrijV8iC6149QOGtq6rzDk9sqHghdWb657TcWw,14893
-pdoc/extract.py,sha256=paF8U6rdInUt3P1We3xTvw-O_gJJaLoxbPRET1aY_pM,12771
+pdoc/doc_types.py,sha256=P6HwAIKotcE7iKJtKpZPvbok7LpeqYEtrgUcknuMcek,8467
+pdoc/docstrings.py,sha256=F_knLP93uD5RiHUN1Ha7mGTxzadiG1880-Go0dXmdh0,14990
+pdoc/extract.py,sha256=G8mGJRHzhbckXGNuYO-hQUL51HItNkJ7ehK5g7By3o8,14277
 pdoc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pdoc/render.py,sha256=-gbybpZQUJICYABZr4HJLBsX43vsMOl1Vo1FIshz9pU,7054
 pdoc/render_helpers.py,sha256=clTbaHYpyK2rMvjhUQpdO0bqrjjcAgFkimuJMZ-uCXc,18708
-pdoc/search.py,sha256=J8RnV-QRFQf4rznrP2NwbUhOWG2FwD7IKJNCtttoVf8,7031
+pdoc/search.py,sha256=tlde_X-Z9CTwQCYr_GSiHy8PKSOtjo0GoDORTcPJn-8,7247
 pdoc/web.py,sha256=ez0lEqwlmpQnkaVfOWglht7e7bvLQXWnJPBp9usgf3k,6895
 pdoc/markdown2/LICENSE,sha256=BfcOT5Iu-7wDaKcbIta8wkP-pFncOu4yXeBlMfbeYGI,1116
 pdoc/markdown2/README.md,sha256=-b2NGwLPzTBnaCGPSqRCzHxSrqArlXxGG5w0c6pOqFk,200
@@ -30,7 +30,7 @@ pdoc/templates/theme.css,sha256=yjnbtPVmqaifTINsA5sK2a3e1aoFO0UlOMgOSKUgLvI,397
 pdoc/templates/default/error.html.jinja2,sha256=RqH14o6ZV79uBO14gKSjwObXFKKczkcLTMe1orurEJk,970
 pdoc/templates/default/frame.html.jinja2,sha256=Qp5zlts8Bl-O2f0cxJHH_QdmAkMtJJjNVA0ZU2Mbwl8,2164
 pdoc/templates/default/index.html.jinja2,sha256=MkzVYMWUuJgscty3jVbDtcEfB1vz-bp3v_sMa5MzevU,2381
-pdoc/templates/default/module.html.jinja2,sha256=tm7tcaXaSIUUPpUsikOHMYo8_2QyUMzxWVZbMPx8sFk,13044
+pdoc/templates/default/module.html.jinja2,sha256=KuBvhTefUteJ1unUA5DVedbjTTqkfA86nU4s_CF23aA,13123
 pdoc/templates/deprecated/README.md,sha256=8HPj4Bu6EPAdHbH5CQVYgcD580zpkhqbwiSFoLAVB1Q,339
 pdoc/templates/deprecated/bootstrap-reboot.min.css,sha256=-u1DTWljwtvjAc8X-ihFhIixKaPcs4w_uZ_CYvvP9-o,207
 pdoc/templates/deprecated/box-arrow-in-left.svg,sha256=-u1DTWljwtvjAc8X-ihFhIixKaPcs4w_uZ_CYvvP9-o,207
@@ -47,9 +47,9 @@ pdoc/templates/resources/info-circle-fill.svg,sha256=kO3AMXfWtacpJPzC8Pvihf46OZd
 pdoc/templates/resources/lightning-fill.svg,sha256=XEyCtbgxeAlwCezdsf7N0NFd5aMjwqyJJDpaFbYYTFA,265
 pdoc/templates/resources/navtoggle.svg,sha256=WVR0BJIucX0MgwwEawmfX0qYD1i_dSbUhoGnqPef3jw,187
 pdoc/templates/resources/pdoc-logo.svg,sha256=w5OsMmytDaA2Fr9CobeQQFxBNx4-wFFHtLvkORj0gjk,6989
-pdoc-14.1.0.dist-info/LICENSE,sha256=fhLl30uuEsshWBuhV87SDhmGoFCN0Q0Oikq5pM-U6Fw,1211
-pdoc-14.1.0.dist-info/METADATA,sha256=K50roH2PkOs8yl5TfAdlEbn8l-w9gg6bisaxo2I5hy0,7440
-pdoc-14.1.0.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
-pdoc-14.1.0.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
-pdoc-14.1.0.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
-pdoc-14.1.0.dist-info/RECORD,,
+pdoc-14.2.0.dist-info/LICENSE,sha256=fhLl30uuEsshWBuhV87SDhmGoFCN0Q0Oikq5pM-U6Fw,1211
+pdoc-14.2.0.dist-info/METADATA,sha256=J-DPKCEO0J898f_48qs9pspc_uoJvZTVoZDcYCrs5DU,7470
+pdoc-14.2.0.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
+pdoc-14.2.0.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
+pdoc-14.2.0.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
+pdoc-14.2.0.dist-info/RECORD,,