pdoc 14.6.1__tar.gz → 14.7.0__tar.gz

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

@@ -5,6 +5,16 @@
 ## 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`.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.6.1
+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.1 → 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.1"  # 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.1 → pdoc-14.7.0}/pdoc/doc.py

@@ -1132,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!
@@ -1166,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 ""
 
@@ -1202,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
 
@@ -1238,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 ""
 
@@ -1333,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.1 → 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=[])  # type: ignore
+        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=[])  # type: ignore
+    return ast.FunctionDef(
+        name="pdoc_stub", args=ast.arguments(), body=[], decorator_list=[]
+    )  # type: ignore
 
 
 def _parse(

{pdoc-14.6.1 → 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.1 → 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) %}

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.6.1
+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.1 → 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.1 → 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.1 → 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"
 
 

{pdoc-14.6.1 → 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,6 +159,7 @@ 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("typed_dict", min_version=(3, 13)),
     Snapshot("type_stubs", ["type_stubs"], min_version=(3, 10)),
     Snapshot(
         "visibility",