pdoc 14.6.0__py3-none-any.whl → 14.7.0__py3-none-any.whl

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/_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/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/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/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/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/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.dist-info → pdoc-14.7.0.dist-info}/METADATA

@@ -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,25 +21,26 @@ 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
 License-File: LICENSE
-Requires-Dist: Jinja2 >=2.11.0
-Requires-Dist: pygments >=2.12.0
+Requires-Dist: Jinja2>=2.11.0
+Requires-Dist: pygments>=2.12.0
 Requires-Dist: MarkupSafe
-Requires-Dist: astunparse ; python_version < "3.9"
+Requires-Dist: astunparse; python_version < "3.9"
 Provides-Extra: dev
-Requires-Dist: tox ; extra == 'dev'
-Requires-Dist: ruff ; extra == 'dev'
-Requires-Dist: mypy ; extra == 'dev'
-Requires-Dist: types-pygments ; extra == 'dev'
-Requires-Dist: pytest ; extra == 'dev'
-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'
+Requires-Dist: tox; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-pygments; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+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.6.0.dist-info → pdoc-14.7.0.dist-info}/RECORD

@@ -1,15 +1,15 @@
-pdoc/__init__.py,sha256=SR29piNT7ZRfryJ7b-MAHzsmUEN1__5kuwBatXofZ88,21456
+pdoc/__init__.py,sha256=TyBp31CH_-JtsJqTz6oKZ7nA6g89o44CIxxzmVSVyGk,21456
 pdoc/__main__.py,sha256=7Xrkxw6-qaSfZfCGFlunl3TfR93uWiCSnvoFABuOmmE,8418
-pdoc/_compat.py,sha256=wKGKTxTTxfNjEcKPwvtuvNeOyiozPfL52h8PArKky-0,3843
-pdoc/doc.py,sha256=WsxiFNwiqqY3Gn12Ee-hafVrN_AbCXCs_SC8jaTTWfQ,48881
-pdoc/doc_ast.py,sha256=ChAOF7qcuRQbdWnRamH6OUtvvIo-JOVCetPjRnb2a3w,11299
-pdoc/doc_pyi.py,sha256=TT6vbugw53vDgunegloJONSLRAaeXswqKah1_TVuUwA,4567
+pdoc/_compat.py,sha256=OKpXrlLyPCNCHx-csUMLMEuhZTyW6vNe8bznhNH4hL0,4114
+pdoc/doc.py,sha256=BATA6UqK9SU1ZWXIYSMRCZi9os3a19QJm5-gUU-bqMU,49851
+pdoc/doc_ast.py,sha256=A77c3Gq52_Im-lP475_S4fCD4GIJy0_FbEAZye885fo,11389
+pdoc/doc_pyi.py,sha256=-ZGMz_HctkOPm19eV42vR6pB4KM8odGCjgrVoRPvJXM,5078
 pdoc/doc_types.py,sha256=mIgMntaw-jCPn_yW2fVTdvkqnWwQys0UKmMTucrdI2w,8468
 pdoc/docstrings.py,sha256=IdjpZYROqRNRfj1tmAKVuB2WfS1HIMqQwOeYpvbvXio,16384
 pdoc/extract.py,sha256=7QqxtsKfvcpFi2yBvpFPQe-YR6KAW_L5PCh9v9g1m_c,14307
 pdoc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pdoc/render.py,sha256=-gbybpZQUJICYABZr4HJLBsX43vsMOl1Vo1FIshz9pU,7054
-pdoc/render_helpers.py,sha256=mqMLdsr4NQiUPQFa6FsRh5z2Id78f4CmOz84cUA_tTM,19985
+pdoc/render_helpers.py,sha256=oPQbYkixh0qaAIUHW93QCephB9gacMdtRTHA5wFOeUc,20400
 pdoc/search.py,sha256=RGFaRftEQOg1Mw4FEOmJVRY9DhBncBYSFi5r4MSknTM,7248
 pdoc/web.py,sha256=F2AvCZr2ucVf9ZlN_SWBO0XpcSKbZTfiN47ypX85zzo,6896
 pdoc/markdown2/LICENSE,sha256=BfcOT5Iu-7wDaKcbIta8wkP-pFncOu4yXeBlMfbeYGI,1116
@@ -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=8IfopEB0v7b24EmNGYbuUSO4zpXmRj0-_YL1YtWB7lE,13241
+pdoc/templates/default/module.html.jinja2,sha256=wUqEgest0bhIML_4SFByQKVfvhSZj9WUbhy-ncddUNQ,13281
 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.6.0.dist-info/LICENSE,sha256=LrhIeJ7gKTDPyOX9YVuZGr9mpmyjpkvqH6LjxvE0szM,898
-pdoc-14.6.0.dist-info/METADATA,sha256=CLKP-hbqqFiinS5d2YyqnJRiJWsfyy_Blv68-j3QRak,7285
-pdoc-14.6.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-pdoc-14.6.0.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
-pdoc-14.6.0.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
-pdoc-14.6.0.dist-info/RECORD,,
+pdoc-14.7.0.dist-info/LICENSE,sha256=LrhIeJ7gKTDPyOX9YVuZGr9mpmyjpkvqH6LjxvE0szM,898
+pdoc-14.7.0.dist-info/METADATA,sha256=CnJAbNSbI-5EBnWL4TRf2jkFiQu57dQ0Gl1ifoylXns,7321
+pdoc-14.7.0.dist-info/WHEEL,sha256=UvcQYKBHoFqaQd6LKyqHw9fxEolWLQnlzP0h_LgJAfI,91
+pdoc-14.7.0.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
+pdoc-14.7.0.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
+pdoc-14.7.0.dist-info/RECORD,,

{pdoc-14.6.0.dist-info → pdoc-14.7.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: setuptools (74.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any