pdoc 14.6.0__tar.gz → 14.7.0__tar.gz

{pdoc-14.6.0 → pdoc-14.7.0}/CHANGELOG.md

@@ -4,6 +4,27 @@
 
 ## Unreleased: pdoc next
 
+
+## 11 September 2024: pdoc 14.7.0
+
+- Do not shorten `current_module.func` to `func` in docstrings when linking.
+  This prevents logical errors in code examples with imports.
+  ([#740](https://github.com/mitmproxy/pdoc/pull/740), @mhils)
+- Add support for Python 3.13.
+  ([#730](https://github.com/mitmproxy/pdoc/pull/730), @mhils)
+- pdoc now strips `collections.abc.` from type annotations to make them more concise.
+  ([#736](https://github.com/mitmproxy/pdoc/pull/736), @mhils)
+
+## 2024-08-27: pdoc 14.6.1
+
+- Fix a bug where entire modules would be excluded by `--no-include-undocumented`.
+  To exclude modules, see https://pdoc.dev/docs/pdoc.html#exclude-submodules-from-being-documented.
+  ([#728](https://github.com/mitmproxy/pdoc/pull/728), @mhils)
+- Fix a bug where pdoc would crash when importing pyi files.
+  ([#732](https://github.com/mitmproxy/pdoc/pull/732), @mhils)
+- Fix a bug where subclasses of TypedDict subclasses would not render correctly.
+  ([#729](https://github.com/mitmproxy/pdoc/pull/729), @mhils)
+
 ## 2024-07-24: pdoc 14.6.0
 
 - If `example.data.Data` is also exposed as `example.Data`, pdoc now links to `example.Data` in documentation.

{pdoc-14.6.0/pdoc.egg-info → pdoc-14.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.6.0
+Version: 14.7.0
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
 License: MIT-0
@@ -21,6 +21,7 @@ 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: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown

{pdoc-14.6.0 → pdoc-14.7.0}/pdoc/__init__.py

@@ -481,7 +481,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.6.0"  # this is read from setup.py
+__version__ = "14.7.0"  # this is read from setup.py
 
 from pathlib import Path
 from typing import overload

{pdoc-14.6.0 → pdoc-14.7.0}/pdoc/_compat.py

@@ -123,6 +123,16 @@ else:  # pragma: no cover
             return ' | '.join(self.option_strings)
 
 
+if sys.version_info >= (3, 10):
+    from typing import is_typeddict
+else:  # pragma: no cover
+    def is_typeddict(tp):
+        try:
+            return tp.__orig_bases__[-1].__name__ == "TypedDict"
+        except Exception:
+            return False
+
+
 __all__ = [
     "cache",
     "ast_unparse",
@@ -134,4 +144,5 @@ __all__ = [
     "removesuffix",
     "formatannotation",
     "BooleanOptionalAction",
+    "is_typeddict",
 ]

{pdoc-14.6.0 → pdoc-14.7.0}/pdoc/doc.py

@@ -37,6 +37,7 @@ import types
 from typing import Any
 from typing import ClassVar
 from typing import Generic
+from typing import TypedDict
 from typing import TypeVar
 from typing import Union
 from typing import get_origin
@@ -49,6 +50,7 @@ from pdoc._compat import TypeAlias
 from pdoc._compat import TypeAliasType
 from pdoc._compat import cache
 from pdoc._compat import formatannotation
+from pdoc._compat import is_typeddict
 from pdoc.doc_types import GenericAlias
 from pdoc.doc_types import NonUserDefinedCallables
 from pdoc.doc_types import empty
@@ -655,14 +657,21 @@ class Class(Namespace[type]):
     @cached_property
     def _bases(self) -> tuple[type, ...]:
         orig_bases = _safe_getattr(self.obj, "__orig_bases__", ())
-        old_python_typeddict_workaround = (
-            sys.version_info < (3, 12)
-            and orig_bases
-            and _safe_getattr(orig_bases[-1], "__name__", None) == "TypedDict"
-        )
-        if old_python_typeddict_workaround:  # pragma: no cover
-            # TypedDicts on Python <3.12 have a botched __mro__. We need to fix it.
-            return (self.obj, *orig_bases[:-1])
+
+        if is_typeddict(self.obj):
+            if sys.version_info < (3, 12):  # pragma: no cover
+                # TypedDicts on Python <3.12 have a botched __mro__. We need to fix it.
+                return (self.obj, *orig_bases[:-1])
+            else:
+                # TypedDict on Python >=3.12 removes intermediate classes from __mro__,
+                # so we use orig_bases to recover the full mro.
+                while orig_bases and orig_bases[-1] is not TypedDict:
+                    parent_bases = _safe_getattr(orig_bases[-1], "__orig_bases__", ())
+                    if (
+                        len(parent_bases) != 1 or parent_bases in orig_bases
+                    ):  # sanity check that things look right
+                        break  # pragma: no cover
+                    orig_bases = (*orig_bases, parent_bases[0])
 
         # __mro__ and __orig_bases__ differ between Python versions and special cases like TypedDict/NamedTuple.
         # This here is a pragmatic approximation of what we want.
@@ -1123,9 +1132,11 @@ class Variable(Doc[None]):
         if self.default_value is empty:
             return ""
         if isinstance(self.default_value, TypeAliasType):
-            return formatannotation(self.default_value.__value__)
+            formatted = formatannotation(self.default_value.__value__)
+            return _remove_collections_abc(formatted)
         elif self.annotation == TypeAlias:
-            return formatannotation(self.default_value)
+            formatted = formatannotation(self.default_value)
+            return _remove_collections_abc(formatted)
 
         # 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!
@@ -1157,7 +1168,8 @@ class Variable(Doc[None]):
     def annotation_str(self) -> str:
         """The variable's type annotation as a pretty-printed str."""
         if self.annotation is not empty:
-            return f": {formatannotation(self.annotation)}"
+            formatted = formatannotation(self.annotation)
+            return f": {_remove_collections_abc(formatted)}"
         else:
             return ""
 
@@ -1193,6 +1205,7 @@ class _PrettySignature(inspect.Signature):
         for param in self.parameters.values():
             formatted = str(param)
             formatted = _remove_memory_addresses(formatted)
+            formatted = _remove_collections_abc(formatted)
 
             kind = param.kind
 
@@ -1229,7 +1242,8 @@ class _PrettySignature(inspect.Signature):
 
     def _return_annotation_str(self) -> str:
         if self.return_annotation is not empty:
-            return formatannotation(self.return_annotation)
+            formatted = formatannotation(self.return_annotation)
+            return _remove_collections_abc(formatted)
         else:
             return ""
 
@@ -1324,3 +1338,8 @@ _Enum_default_docstrings = tuple(
 def _remove_memory_addresses(x: str) -> str:
     """Remove memory addresses from repr() output"""
     return re.sub(r" at 0x[0-9a-fA-F]+(?=>)", "", x)
+
+
+def _remove_collections_abc(x: str) -> str:
+    """Remove 'collections.abc' from type signatures."""
+    return re.sub(r"(?!\.)\bcollections\.abc\.", "", x)

{pdoc-14.6.0 → pdoc-14.7.0}/pdoc/doc_ast.py

@@ -240,12 +240,11 @@ def _parse_class(source: str) -> ast.ClassDef:
     Returns an empty ast.ClassDef if source is empty.
     """
     tree = _parse(source)
-    assert len(tree.body) <= 1
-    if tree.body:
+    if tree.body and len(tree.body) == 1:
         t = tree.body[0]
-        assert isinstance(t, ast.ClassDef)
-        return t
-    return ast.ClassDef(body=[], decorator_list=[])
+        if isinstance(t, ast.ClassDef):
+            return t
+    return ast.ClassDef(name="PdocStub", body=[], decorator_list=[])  # type: ignore
 
 
 @cache
@@ -256,8 +255,7 @@ def _parse_function(source: str) -> ast.FunctionDef | ast.AsyncFunctionDef:
     Returns an empty ast.FunctionDef if source is empty.
     """
     tree = _parse(source)
-    assert len(tree.body) <= 1
-    if tree.body:
+    if tree.body and len(tree.body) == 1:
         t = tree.body[0]
         if isinstance(t, (ast.FunctionDef, ast.AsyncFunctionDef)):
             return t
@@ -265,7 +263,9 @@ def _parse_function(source: str) -> ast.FunctionDef | ast.AsyncFunctionDef:
             # we have a lambda function,
             # to simplify the API return the ast.FunctionDef stub.
             pass
-    return ast.FunctionDef(body=[], decorator_list=[])
+    return ast.FunctionDef(
+        name="pdoc_stub", args=ast.arguments(), body=[], decorator_list=[]
+    )  # type: ignore
 
 
 def _parse(

{pdoc-14.6.0 → pdoc-14.7.0}/pdoc/doc_pyi.py

@@ -6,6 +6,7 @@ This makes it possible to add type hints for native modules such as modules writ
 
 from __future__ import annotations
 
+import importlib.util
 from pathlib import Path
 import sys
 import traceback
@@ -45,13 +46,28 @@ def find_stub_file(module_name: str) -> Path | None:
 
 
 def _import_stub_file(module_name: str, stub_file: Path) -> types.ModuleType:
-    """Import the type stub outside of the normal import machinery."""
-    code = compile(stub_file.read_text(), str(stub_file), "exec")
-    m = types.ModuleType(module_name)
-    m.__file__ = str(stub_file)
-    eval(code, m.__dict__, m.__dict__)
+    """
+    Import the type stub outside of the normal import machinery.
 
-    return m
+    Note that currently, for objects imported by the stub file, the _original_ module
+    is used and not the corresponding stub file.
+    """
+    sys.path_hooks.append(
+        importlib.machinery.FileFinder.path_hook(
+            (importlib.machinery.SourceFileLoader, [".pyi"])
+        )
+    )
+    try:
+        loader = importlib.machinery.SourceFileLoader(module_name, str(stub_file))
+        spec = importlib.util.spec_from_file_location(
+            module_name, stub_file, loader=loader
+        )
+        assert spec is not None
+        m = importlib.util.module_from_spec(spec)
+        loader.exec_module(m)
+        return m
+    finally:
+        sys.path_hooks.pop()
 
 
 def _prepare_module(ns: doc.Namespace) -> None:

{pdoc-14.6.0 → pdoc-14.7.0}/pdoc/render_helpers.py

@@ -307,11 +307,17 @@ def module_candidates(identifier: str, current_module: str) -> Iterable[str]:
 
 
 @pass_context
-def linkify(context: Context, code: str, namespace: str = "") -> str:
+def linkify(
+    context: Context, code: str, namespace: str = "", shorten: bool = True
+) -> str:
     """
     Link all identifiers in a block of text. Identifiers referencing unknown modules or modules that
     are not rendered at the moment will be ignored.
     A piece of text is considered to be an identifier if it either contains a `.` or is surrounded by `<code>` tags.
+
+    If `shorten` is True, replace identifiers with short forms where possible.
+    For example, replace "current_module.Foo" with "Foo". This is useful for annotations
+    (which are verbose), but undesired for docstrings (where we want to preserve intent).
     """
 
     def linkify_repl(m: re.Match):
@@ -381,12 +387,15 @@ def linkify(context: Context, code: str, namespace: str = "") -> str:
                     and (target_object is doc.obj or target_object is None)
                     and context["is_public"](doc).strip()
                 ):
-                    if module == mod:
-                        url_text = qualname
+                    if shorten:
+                        if module == mod:
+                            url_text = qualname
+                        else:
+                            url_text = doc.fullname
+                        if plain_text.endswith("()"):
+                            url_text += "()"
                     else:
-                        url_text = doc.fullname
-                    if plain_text.endswith("()"):
-                        url_text += "()"
+                        url_text = plain_text
                     return f'<a href="{relative_link(context["module"].modulename, doc.modulename)}#{qualname}">{url_text}</a>'
 
         # No matches found.

{pdoc-14.6.0 → pdoc-14.7.0}/pdoc/templates/default/module.html.jinja2

@@ -209,7 +209,7 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
 {% enddefaultmacro %}
 {% defaultmacro docstring(var) %}
     {% if var.docstring %}
-        <div class="docstring">{{ var.docstring | replace("@public", "") | to_markdown | to_html | linkify(namespace=var.qualname) }}</div>
+        <div class="docstring">{{ var.docstring | replace("@public", "") | to_markdown | to_html | linkify(namespace=var.qualname, shorten=False) }}</div>
     {% endif %}
 {% enddefaultmacro %}
 {% defaultmacro nav_members(members) %}
@@ -244,7 +244,7 @@ See https://pdoc.dev/docs/pdoc/render_helpers.html#DefaultMacroExtension for an
     {% elif "@public" in doc.docstring %}
         {# show members explicitly marked as @public #}
         true
-    {% elif not include_undocumented and not doc.docstring %}
+    {% elif not include_undocumented and not doc.docstring and doc.kind != "module" %}
         {# hide members that are undocumented if include_undocumented has been toggled off. #}
     {% elif doc.name == "__init__" and (doc.docstring or (doc.kind == "function" and doc.signature_without_self.parameters)) %}
         {# show constructors that have a docstring or at least one extra argument #}

{pdoc-14.6.0 → pdoc-14.7.0/pdoc.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.6.0
+Version: 14.7.0
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
 License: MIT-0
@@ -21,6 +21,7 @@ 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: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown

{pdoc-14.6.0 → pdoc-14.7.0}/pyproject.toml

@@ -28,6 +28,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Typing :: Typed",
 ]
 

{pdoc-14.6.0 → pdoc-14.7.0}/test/test_doc.py

@@ -1,7 +1,6 @@
 import builtins
 import dataclasses
 from pathlib import Path
-import sys
 import types
 from unittest.mock import patch
 
@@ -120,13 +119,15 @@ def test_builtin_source():
     assert m.source_lines is None
 
 
-@pytest.mark.skipif(sys.version_info < (3, 9), reason="3.9+ only")
 def test_raising_getdoc():
-    class Foo:
-        @classmethod
-        @property
-        def __doc__(self):
-            raise RuntimeError
+    class FooMeta(type):
+        def __getattribute__(cls, name):
+            if name == "__doc__":
+                raise RuntimeError
+            return super().__getattribute__(name)
+
+    class Foo(metaclass=FooMeta):
+        pass
 
     x = Class(Foo.__module__, Foo.__qualname__, Foo, (Foo.__module__, Foo.__qualname__))
     with pytest.warns(UserWarning, match="inspect.getdoc(.+) raised an exception"):

{pdoc-14.6.0 → pdoc-14.7.0}/test/test_doc_types.py

@@ -50,7 +50,9 @@ def test_eval_fail_import_nonexistent(monkeypatch):
         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'"):
+    with pytest.warns(
+        UserWarning, match="No module named 'nonexistent_module'|Import of xyz failed"
+    ):
         assert safe_eval_type("xyz", a.__dict__, None, a, "a") == "xyz"
 
 
@@ -79,5 +81,7 @@ def test_recurse(monkeypatch):
     monkeypatch.setitem(sys.modules, "a", a)
     monkeypatch.setitem(sys.modules, "b", b)
 
-    with pytest.warns(UserWarning, match="Recursion error when importing a"):
+    with pytest.warns(
+        UserWarning, match="Recursion error when importing a|Import of xyz failed"
+    ):
         assert safe_eval_type("xyz", a.__dict__, None, a, "a") == "xyz"

{pdoc-14.6.0 → pdoc-14.7.0}/test/test_snapshot.py

@@ -96,8 +96,9 @@ class Snapshot:
 
 snapshots = [
     Snapshot("ast_parsing"),
+    Snapshot("collections_abc", min_version=(3, 9)),
     Snapshot("demo", min_version=(3, 9)),
-    Snapshot("enums", min_version=(3, 12)),
+    Snapshot("enums", min_version=(3, 13)),
     Snapshot("flavors_google"),
     Snapshot("flavors_numpy"),
     Snapshot("flavors_rst"),
@@ -135,16 +136,10 @@ snapshots = [
         with_output_directory=True,
     ),
     Snapshot("misc"),
-    Snapshot(
-        "misc_py39",
-        min_version=(3, 9),
-    ),
+    Snapshot("misc_py39", min_version=(3, 9)),
     Snapshot("misc_py310", min_version=(3, 10)),
-    Snapshot("misc_py311", min_version=(3, 11)),
-    Snapshot(
-        "misc_py312",
-        min_version=(3, 12),
-    ),
+    Snapshot("misc_py312", min_version=(3, 12)),
+    Snapshot("misc_py313", min_version=(3, 13)),
     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)),
@@ -164,7 +159,8 @@ snapshots = [
     Snapshot("pyo3_sample_library", specs=["pdoc_pyo3_sample_library"]),
     Snapshot("top_level_reimports", ["top_level_reimports"]),
     Snapshot("type_checking_imports", ["type_checking_imports.main"]),
-    Snapshot("type_stub", min_version=(3, 10)),
+    Snapshot("typed_dict", min_version=(3, 13)),
+    Snapshot("type_stubs", ["type_stubs"], min_version=(3, 10)),
     Snapshot(
         "visibility",
         render_options={