pdoc 15.0.1__tar.gz → 15.0.3__tar.gz

{pdoc-15.0.1 → pdoc-15.0.3}/CHANGELOG.md

@@ -5,6 +5,24 @@
 ## Unreleased: pdoc next
 
 
+## 2025-04-21: pdoc 15.0.3
+
+- Add missing styles for Github's markdown alerts.
+  ([#796](https://github.com/mitmproxy/pdoc/pull/796), @Steve-Tech)
+
+## 2025-04-17: pdoc 15.0.2
+
+- Fix a bug where type aliases wouldn't be linked.
+  ([#798](https://github.com/mitmproxy/pdoc/pull/798), @mhils)
+- Fix a bug where invalid Numpydoc docstrings would raise an exception.
+  ([#789](https://github.com/mitmproxy/pdoc/pull/789), @tobiscode, @mhils)
+- Improve debuggability of docstring processing
+  ([#784](https://github.com/mitmproxy/pdoc/pull/784), @tobiscode)
+- Fix handling of URL-escaped module names
+  ([#787](https://github.com/mitmproxy/pdoc/pull/787), @iFreilicht)
+- Embed local images referenced in docstrings with an HTML image tag (`<img src="./image.png">`) in addition to Markdown (`![image](./image.png)`) 
+  ([#785](https://github.com/mitmproxy/pdoc/pull/785), @earshinov)
+
 ## 2024-12-12: pdoc 15.0.1
 
 - Update Mermaid.js version.

{pdoc-15.0.1/pdoc.egg-info → pdoc-15.0.3}/PKG-INFO

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

{pdoc-15.0.1 → pdoc-15.0.3}/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.3"  # this is read from setup.py
 
 from pathlib import Path
 from typing import overload

{pdoc-15.0.1 → pdoc-15.0.3}/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-15.0.1 → pdoc-15.0.3}/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-15.0.1 → pdoc-15.0.3}/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-15.0.1 → pdoc-15.0.3}/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-15.0.1 → pdoc-15.0.3}/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-15.0.1 → pdoc-15.0.3}/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-15.0.1 → pdoc-15.0.3}/pdoc/templates/content.css

@@ -45,13 +45,27 @@ This makes sure that the pdoc styling doesn't leak to the rest of the page when
 }
 
 /* Admonitions are currently not stylable via theme.css */
-.pdoc .alert.note  {
+.pdoc .alert.note {
     color: #084298;
     background-color: #cfe2ff;
     border-color: #b6d4fe;
     background-image: url("data:image/svg+xml,{% filter urlencode %}{% include 'resources/info-circle-fill.svg' %}{% endfilter %}");
 }
 
+.pdoc .alert.tip {
+    color: #0a3622;
+    background-color: #d1e7dd;
+    border-color: #a3cfbb;
+    background-image: url("data:image/svg+xml,{% filter urlencode %}{% include 'resources/lightbulb.svg' %}{% endfilter %}");
+}
+
+.pdoc .alert.important {
+    color: #055160;
+    background-color: #cff4fc;
+    border-color: #9eeaf9;
+    background-image: url("data:image/svg+xml,{% filter urlencode %}{% include 'resources/exclamation-square-fill.svg' %}{% endfilter %}");
+}
+
 .pdoc .alert.warning {
     color: #664d03;
     background-color: #fff3cd;
@@ -59,6 +73,13 @@ This makes sure that the pdoc styling doesn't leak to the rest of the page when
     background-image: url("data:image/svg+xml,{% filter urlencode %}{% include 'resources/exclamation-triangle-fill.svg' %}{% endfilter %}");
 }
 
+.pdoc .alert.caution {
+    color: #842029;
+    background-color: #f8d7da;
+    border-color: #f5c2c7;
+    background-image: url("data:image/svg+xml,{% filter urlencode %}{% include 'resources/exclamation-octagon-fill.svg' %}{% endfilter %}");
+}
+
 .pdoc .alert.danger {
     color: #842029;
     background-color: #f8d7da;

pdoc-15.0.3/pdoc/templates/resources/exclamation-octagon-fill.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="#842029" viewBox="0 0 16 16"><path d="M11.46.146A.5.5 0 0 0 11.107 0H4.893a.5.5 0 0 0-.353.146L.146 4.54A.5.5 0 0 0 0 4.893v6.214a.5.5 0 0 0 .146.353l4.394 4.394a.5.5 0 0 0 .353.146h6.214a.5.5 0 0 0 .353-.146l4.394-4.394a.5.5 0 0 0 .146-.353V4.893a.5.5 0 0 0-.146-.353zM8 4c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 4.995A.905.905 0 0 1 8 4m.002 6a1 1 0 1 1 0 2 1 1 0 0 1 0-2"/></svg>

pdoc-15.0.3/pdoc/templates/resources/exclamation-square-fill.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="#055160" viewBox="0 0 16 16"><path d="M2 0a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V2a2 2 0 0 0-2-2zm6 4c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 0 1-1.1 0L7.1 4.995A.905.905 0 0 1 8 4m.002 6a1 1 0 1 1 0 2 1 1 0 0 1 0-2"/></svg>

pdoc-15.0.3/pdoc/templates/resources/lightbulb.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="#0a3622" viewBox="0 0 16 16"><path d="M2 6a6 6 0 1 1 10.174 4.31c-.203.196-.359.4-.453.619l-.762 1.769A.5.5 0 0 1 10.5 13a.5.5 0 0 1 0 1 .5.5 0 0 1 0 1l-.224.447a1 1 0 0 1-.894.553H6.618a1 1 0 0 1-.894-.553L5.5 15a.5.5 0 0 1 0-1 .5.5 0 0 1 0-1 .5.5 0 0 1-.46-.302l-.761-1.77a2 2 0 0 0-.453-.618A5.98 5.98 0 0 1 2 6m6-5a5 5 0 0 0-3.479 8.592c.263.254.514.564.676.941L5.83 12h4.342l.632-1.467c.162-.377.413-.687.676-.941A5 5 0 0 0 8 1"/></svg>

{pdoc-15.0.1 → pdoc-15.0.3}/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 → pdoc-15.0.3/pdoc.egg-info}/PKG-INFO

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

{pdoc-15.0.1 → pdoc-15.0.3}/pdoc.egg-info/SOURCES.txt

@@ -53,8 +53,11 @@ pdoc/templates/deprecated/resources/favicon.svg
 pdoc/templates/resources/bootstrap-reboot.min.css
 pdoc/templates/resources/box-arrow-in-left.svg
 pdoc/templates/resources/elasticlunr.min.js
+pdoc/templates/resources/exclamation-octagon-fill.svg
+pdoc/templates/resources/exclamation-square-fill.svg
 pdoc/templates/resources/exclamation-triangle-fill.svg
 pdoc/templates/resources/info-circle-fill.svg
+pdoc/templates/resources/lightbulb.svg
 pdoc/templates/resources/lightning-fill.svg
 pdoc/templates/resources/navtoggle.svg
 pdoc/templates/resources/pdoc-logo.svg

{pdoc-15.0.1 → pdoc-15.0.3}/test/test_docstrings.py

@@ -37,6 +37,19 @@ def test_rst_extract_options_fuzz(s):
     assert not s or content or options
 
 
+def test_convert_exception(monkeypatch):
+    def raise_(*_):
+        raise Exception
+
+    monkeypatch.setattr(docstrings, "rst", raise_)
+    with pytest.raises(RuntimeError, match="Docstring processing failed"):
+        docstrings.convert(
+            "Valid minimal docstring without in- or output.",
+            "numpy",
+            None,
+        )
+
+
 def test_rst_extract_options():
     content = (
         ":alpha: beta\n"
@@ -49,7 +62,7 @@ def test_rst_extract_options():
         "alpha": "beta",
         "charlie": "delta:foxtrot",
     }
-    assert content == ("\nrest of content\n" ":option ignored: as follows content\n")
+    assert content == ("\nrest of content\n:option ignored: as follows content\n")
 
 
 def test_rst_include_trim_lines():

{pdoc-15.0.1 → pdoc-15.0.3}/test/test_smoke.py

@@ -22,7 +22,7 @@ def test_smoke(module):
     try:
         with pdoc.extract.mock_some_common_side_effects():
             importlib.import_module(module)
-    except pdoc.extract.AnyException:
+    except pdoc.docstrings.AnyException:
         pass
     else:
         try:

{pdoc-15.0.1 → pdoc-15.0.3}/test/test_web.py

@@ -69,6 +69,12 @@ def test_get_module():
     )
 
 
+def test_get_module_url_escape_sequences():
+    assert b"make_dataclass" in handle_request(
+        b"GET /%64atac%6Ca%73se%73.html HTTP/1.1\r\n\r\n"
+    )
+
+
 def test_get_dependency():
     assert b"a template engine written in pure Python" in handle_request(
         b"GET /jinja2.html HTTP/1.1\r\n\r\n"