pdoc 15.0.1__py3-none-any.whl → 15.0.2__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__ = "15.0.1"  # this is read from setup.py
+__version__ = "15.0.2"  # this is read from setup.py
 
 from pathlib import Path
 from typing import overload

pdoc/doc.py

@@ -637,7 +637,7 @@ class Class(Namespace[type]):
                 for attr, unresolved_annotation in dynamic_annotations.items():
                     cls_annotations[attr] = unresolved_annotation
             cls_fullname = (
-                _safe_getattr(cls, "__module__", "") + "." + cls.__qualname__
+                (_safe_getattr(cls, "__module__", "") or "") + "." + cls.__qualname__
             ).lstrip(".")
 
             new_annotations = {
@@ -1095,7 +1095,7 @@ class Variable(Doc[None]):
             default = f" = {self.default_value_str}"
         else:
             default = ""
-        return f'<var {self.qualname.rsplit(".")[-1]}{self.annotation_str}{default}{_docstr(self)}>'
+        return f"<var {self.qualname.rsplit('.')[-1]}{self.annotation_str}{default}{_docstr(self)}>"
 
     @cached_property
     def is_classvar(self) -> bool:
@@ -1169,6 +1169,9 @@ class Variable(Doc[None]):
         """The variable's type annotation as a pretty-printed str."""
         if self.annotation is not empty:
             formatted = formatannotation(self.annotation)
+            # type aliases don't include the module name in their __repr__, so we add it here.
+            if isinstance(self.annotation, TypeAliasType):
+                formatted = f"{self.annotation.__module__}.{formatted}"
             return f": {_remove_collections_abc(formatted)}"
         else:
             return ""

pdoc/doc_ast.py

@@ -273,7 +273,7 @@ def _parse(
     try:
         return ast.parse(_dedent(source))
     except Exception as e:
-        warnings.warn(f"Error parsing source code: {e}\n" f"===\n" f"{source}\n" f"===")
+        warnings.warn(f"Error parsing source code: {e}\n===\n{source}\n===")
         return ast.parse("")
 
 

pdoc/doc_types.py

@@ -114,7 +114,7 @@ def safe_eval_type(
                 f"Error parsing type annotation {t} for {fullname}: {e}. "
                 f"You are likely attempting to use Python 3.10 syntax (PEP 604 union types) with an older Python "
                 f"release. `X | Y`-style type annotations are invalid syntax on Python {py_ver}, which is what your "
-                f"pdoc instance is using. `from future import __annotations__` (PEP 563) postpones evaluation of "
+                f"pdoc instance is using. `from __future__ import annotations` (PEP 563) postpones evaluation of "
                 f"annotations, which is why your program won't crash right away. However, pdoc needs to evaluate your "
                 f"type annotations and is unable to do so on Python {py_ver}. To fix this issue, either invoke pdoc "
                 f"from Python 3.10+, or switch to `typing.Union[]` syntax."

pdoc/docstrings.py

@@ -24,6 +24,13 @@ from textwrap import dedent
 from textwrap import indent
 import warnings
 
+AnyException = (SystemExit, GeneratorExit, Exception)
+"""BaseException, but excluding KeyboardInterrupt.
+
+Modules may raise SystemExit on import (which we want to catch),
+but we don't want to catch a user's KeyboardInterrupt.
+"""
+
 
 @cache
 def convert(docstring: str, docformat: str, source_file: Path | None) -> str:
@@ -32,39 +39,52 @@ def convert(docstring: str, docformat: str, source_file: Path | None) -> str:
     """
     docformat = docformat.lower()
 
-    if any(x in docformat for x in ["google", "numpy", "restructuredtext"]):
-        docstring = rst(docstring, source_file)
+    try:
+        if any(x in docformat for x in ["google", "numpy", "restructuredtext"]):
+            docstring = rst(docstring, source_file)
 
-    if "google" in docformat:
-        docstring = google(docstring)
+        if "google" in docformat:
+            docstring = google(docstring)
 
-    if "numpy" in docformat:
-        docstring = numpy(docstring)
+        if "numpy" in docformat:
+            docstring = numpy(docstring)
 
-    if source_file is not None and os.environ.get("PDOC_EMBED_IMAGES") != "0":
-        docstring = embed_images(docstring, source_file)
+        if source_file is not None and os.environ.get("PDOC_EMBED_IMAGES") != "0":
+            docstring = embed_images(docstring, source_file)
+
+    except AnyException as e:
+        raise RuntimeError(
+            'Docstring processing failed for docstring=\n"""\n'
+            + docstring
+            + f'\n"""\n{source_file=}\n{docformat=}'
+        ) from e
 
     return docstring
 
 
 def embed_images(docstring: str, source_file: Path) -> str:
+    def local_image_to_data_uri(href: str) -> str:
+        image_path = source_file.parent / href
+        image_data = image_path.read_bytes()
+        image_mime = mimetypes.guess_type(image_path)[0]
+        image_data_b64 = base64.b64encode(image_data).decode()
+        return f"data:{image_mime};base64,{image_data_b64}"
+
     def embed_local_image(m: re.Match) -> str:
-        image_path = source_file.parent / m["href"]
         try:
-            image_data = image_path.read_bytes()
-            image_mime = mimetypes.guess_type(image_path)[0]
+            href = local_image_to_data_uri(m["href"])
         except Exception:
             return m[0]
         else:
-            data = base64.b64encode(image_data).decode()
-            return f"![{m['alt']}](data:{image_mime};base64,{data})"
-
-    return re.sub(
-        r"!\[\s*(?P<alt>.*?)\s*]\(\s*(?P<href>.+?)\s*\)",
-        embed_local_image,
-        docstring,
-    )
-    # TODO: Could probably do more here, e.g. support rST or raw HTML replacements.
+            return m["before"] + href + m["after"]
+
+    # TODO: Could probably do more here, e.g. support rST replacements.
+    for regex in [
+        r"(?P<before>!\[\s*.*?\s*]\(\s*)(?P<href>.+?)(?P<after>\s*\))",
+        r"""(?P<before>src=['"])(?P<href>.+?)(?P<after>['"])""",
+    ]:
+        docstring = re.sub(regex, embed_local_image, docstring)
+    return docstring
 
 
 def google(docstring: str) -> str:
@@ -178,13 +198,15 @@ def numpy(docstring: str) -> str:
     )
     contents = sections[0]
     for heading, content in zip(sections[1::2], sections[2::2]):
-        if content.startswith(" "):
+        if content.startswith(" ") and re.search(r"\n(?![ \n])", content):
             # If the first line of section content is indented, we consider the section to be finished
             # on the first non-indented line. We take out the rest - the tail - here.
             content, tail = re.split(r"\n(?![ \n])", content, maxsplit=1)
         else:
             tail = ""
 
+        content = dedent(content)
+
         if heading in (
             "Parameters",
             "Returns",
@@ -199,7 +221,7 @@ def numpy(docstring: str) -> str:
         elif heading == "See Also":
             contents += f"###### {heading}\n{_numpy_seealso(content)}"
         else:
-            contents += f"###### {heading}\n{dedent(content)}"
+            contents += f"###### {heading}\n{content}"
         contents += tail
     return contents
 

pdoc/extract.py

@@ -61,7 +61,7 @@ def walk_specs(specs: Sequence[Path | str]) -> list[str]:
                 modspec = importlib.util.find_spec(modname)
                 if modspec is None:
                     raise ModuleNotFoundError(modname)
-        except AnyException:
+        except pdoc.docstrings.AnyException:
             warnings.warn(
                 f"Cannot find spec for {modname} (from {spec}):\n{traceback.format_exc()}",
                 stacklevel=2,
@@ -110,7 +110,7 @@ def parse_spec(spec: Path | str) -> str:
                 modspec = importlib.util.find_spec(spec)
                 if modspec is None:
                     raise ModuleNotFoundError
-        except AnyException:
+        except pdoc.docstrings.AnyException:
             # Module does not exist, use local file.
             spec = pspec
         else:
@@ -218,18 +218,10 @@ def load_module(module: str) -> types.ModuleType:
     Returns the imported module."""
     try:
         return importlib.import_module(module)
-    except AnyException as e:
+    except pdoc.docstrings.AnyException as e:
         raise RuntimeError(f"Error importing {module}") from e
 
 
-AnyException = (SystemExit, GeneratorExit, Exception)
-"""BaseException, but excluding KeyboardInterrupt.
-
-Modules may raise SystemExit on import (which we want to catch),
-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.
@@ -315,7 +307,7 @@ def module_mtime(modulename: str) -> float | None:
     try:
         with mock_some_common_side_effects():
             spec = importlib.util.find_spec(modulename)
-    except AnyException:
+    except pdoc.docstrings.AnyException:
         pass
     else:
         if spec is not None and spec.origin is not None:
@@ -365,7 +357,7 @@ def invalidate_caches(module_name: str) -> None:
                 continue  # some funky stuff going on - one example is typing.io, which is a class.
             with mock_some_common_side_effects():
                 importlib.reload(sys.modules[modname])
-        except AnyException:
+        except pdoc.docstrings.AnyException:
             warnings.warn(
                 f"Error reloading {modname}:\n{traceback.format_exc()}",
                 stacklevel=2,

pdoc/render_helpers.py

@@ -99,7 +99,7 @@ Link pattern used for markdown2's [`link-patterns` extra](https://github.com/tre
 
 
 @cache
-def highlight(doc: pdoc.doc.Doc) -> str:
+def highlight(doc: pdoc.doc.Doc) -> Markup:
     """Highlight the source code of a documentation object using pygments."""
     if isinstance(doc, str):  # pragma: no cover
         warnings.warn(
@@ -114,7 +114,7 @@ def highlight(doc: pdoc.doc.Doc) -> str:
     return Markup(pygments.highlight(doc.source, lexer, formatter))
 
 
-def format_signature(sig: inspect.Signature, colon: bool) -> str:
+def format_signature(sig: inspect.Signature, colon: bool) -> Markup:
     """Format and highlight a function signature using pygments. Returns HTML."""
     # First get a list with all params as strings.
     result = pdoc.doc._PrettySignature._params(sig)  # type: ignore
@@ -308,7 +308,7 @@ def module_candidates(identifier: str, current_module: str) -> Iterable[str]:
 @pass_context
 def linkify(
     context: Context, code: str, namespace: str = "", shorten: bool = True
-) -> str:
+) -> Markup:
     """
     Link all identifiers in a block of text. Identifiers referencing unknown modules or modules that
     are not rendered at the moment will be ignored.
@@ -436,7 +436,7 @@ def linkify(
 
 
 @pass_context
-def link(context: Context, spec: tuple[str, str], text: str | None = None) -> str:
+def link(context: Context, spec: tuple[str, str], text: str | None = None) -> Markup:
     """Create a link for a specific `(modulename, qualname)` tuple."""
     mod: pdoc.doc.Module = context["module"]
     modulename, qualname = spec
@@ -469,7 +469,7 @@ def link(context: Context, spec: tuple[str, str], text: str | None = None) -> st
         return Markup(
             f'<a href="{relative_link(context["module"].modulename, modulename)}{qualname}">{text or fullname}</a>'
         )
-    return text or fullname
+    return Markup.escape(text or fullname)
 
 
 def edit_url(
@@ -507,7 +507,7 @@ def root_module_name(all_modules: Mapping[str, pdoc.doc.Module]) -> str | None:
         return None
 
 
-def minify_css(css: str) -> str:
+def minify_css(css: str) -> Markup:
     """Do some very basic CSS minification."""
     css = re.sub(r"[ ]{4}|\n|(?<=[:{}]) | (?=[{}])", "", css)
     css = re.sub(

pdoc/web.py

@@ -14,6 +14,7 @@ from functools import cache
 import http.server
 import traceback
 from typing import Mapping
+import urllib.parse
 import warnings
 import webbrowser
 
@@ -60,6 +61,7 @@ class DocHandler(http.server.BaseHTTPRequestHandler):
             return "Not Found: Please normalize all module separators to '/'."
         else:
             module_name = path.lstrip("/").removesuffix(".html").replace("/", ".")
+            module_name = urllib.parse.unquote(module_name)
             if module_name not in self.server.all_modules:
                 self.send_response(404)
                 self.send_header("content-type", "text/html")

{pdoc-15.0.1.dist-info → pdoc-15.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 15.0.1
+Version: 15.0.2
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
 License: MIT-0

{pdoc-15.0.1.dist-info → pdoc-15.0.2.dist-info}/RECORD

@@ -1,17 +1,17 @@
-pdoc/__init__.py,sha256=j8rkSHPnAcGqFnL6CWxEu99QY6DDS6IEkIoVLXzJqnQ,21456
+pdoc/__init__.py,sha256=jnoeoAPOPSzWTb12xjX2gUW4SV_TUCS1QS6JdnavNOA,21456
 pdoc/__main__.py,sha256=DOXWKG7I0M-E9uSs8a--9RGJNI266_2VKZpVQR4paj0,8416
 pdoc/_compat.py,sha256=iXM2kfvS8oRg30EuA-HYWyVt5iorA5JrJHAhUZvsuu4,1447
-pdoc/doc.py,sha256=lUjahuUcTXTKBEHxxd0F6L0e4oPHvalh6D5pvHZRW8Q,49865
-pdoc/doc_ast.py,sha256=WRkdDTWRNz4pJYBpWUqOGL9yZmcMezCR_uJVJ2ST9NU,11357
+pdoc/doc.py,sha256=866peOsabjNx-rexUlF41K9GYBYHqEaMv_fQUuF8gD4,50099
+pdoc/doc_ast.py,sha256=qoWLta30b2XTlwj9fI15IM0687T0dIp9Vk5bB325O60,11345
 pdoc/doc_pyi.py,sha256=r2QdI8WeUxY6jQ9O4xmL3m1zPVmIpxEAviqLYt_M5gk,5078
-pdoc/doc_types.py,sha256=LQp2AWXNUOF8chQzrPK1RZlGZNnkNswkagMTyXi9ABs,8465
-pdoc/docstrings.py,sha256=2s1ao_Ky7pOKgKXmIr7yJfFEIDD_m-5LxoT7yjNmVJs,16384
-pdoc/extract.py,sha256=Vb9vVjtJ1u6X2wqn2Z_cTObrunQ722T0Kj12nsqVG20,14379
+pdoc/doc_types.py,sha256=tcZysNBSHk1tAxbr4JSmDARoLkHlxINVW6UYvEtzUvs,8465
+pdoc/docstrings.py,sha256=m3yzwekXlQxY-_wcVEyLzT6A6hJyY-yp95ooyzx90uA,17187
+pdoc/extract.py,sha256=1EtgteSdCF61Z5kr4nR3fL9BXwKoJ9FM92aNCPS48nM,14227
 pdoc/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pdoc/render.py,sha256=8vXpDlqzRayJdaH0oU6nA6aApFYeGrtxVLOmCD7EbIU,7081
-pdoc/render_helpers.py,sha256=LJcMlaJFhKBNRGiwEbtIFbEqlncgXte97wTfxm5zDk0,20365
+pdoc/render_helpers.py,sha256=Db-uB28WkWird--4Rtu4klJnP6S7p3LJFsaAXiH4fJQ,20395
 pdoc/search.py,sha256=RGFaRftEQOg1Mw4FEOmJVRY9DhBncBYSFi5r4MSknTM,7248
-pdoc/web.py,sha256=eIXR0SpU843D-u_xjrXiQ7vH5Zuda_yWOWV8H5nEaMQ,6853
+pdoc/web.py,sha256=9pRpukVWMEoWbthB1E9Yrg86KoSNmXMeBicno_cVcPQ,6933
 pdoc/markdown2/LICENSE,sha256=BfcOT5Iu-7wDaKcbIta8wkP-pFncOu4yXeBlMfbeYGI,1116
 pdoc/markdown2/README.md,sha256=-b2NGwLPzTBnaCGPSqRCzHxSrqArlXxGG5w0c6pOqFk,200
 pdoc/markdown2/__init__.py,sha256=guvOlezAha8NQBH8TFkEwiP4zFy5tsV2NVYiEOWD2jg,159248
@@ -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-15.0.1.dist-info/LICENSE,sha256=LrhIeJ7gKTDPyOX9YVuZGr9mpmyjpkvqH6LjxvE0szM,898
-pdoc-15.0.1.dist-info/METADATA,sha256=3zDOYdosrb75oPuPEsrhFiFzhIMR3_wU8eySzSM9Etw,6775
-pdoc-15.0.1.dist-info/WHEEL,sha256=GV9aMThwP_4oNCtvEC2ec3qUYutgWeAzklro_0m4WJQ,91
-pdoc-15.0.1.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
-pdoc-15.0.1.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
-pdoc-15.0.1.dist-info/RECORD,,
+pdoc-15.0.2.dist-info/LICENSE,sha256=LrhIeJ7gKTDPyOX9YVuZGr9mpmyjpkvqH6LjxvE0szM,898
+pdoc-15.0.2.dist-info/METADATA,sha256=448hBCXQ-y-3rZfozXBq0dbJZG83T24O-pBdooMTsos,6775
+pdoc-15.0.2.dist-info/WHEEL,sha256=P9jw-gEje8ByB7_hXoICnHtVCrEwMQh-630tKvQWehc,91
+pdoc-15.0.2.dist-info/entry_points.txt,sha256=-bK-S1ZvmqCWqi1hGnsl5nayWkzXB1BEs-Cynh5QZaI,43
+pdoc-15.0.2.dist-info/top_level.txt,sha256=rg5eIToBHzwTfZZi1E7NVHgie5joQuSuU1rWV0qKS9k,5
+pdoc-15.0.2.dist-info/RECORD,,

{pdoc-15.0.1.dist-info → pdoc-15.0.2.dist-info}/WHEEL

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