pdoc 14.5.1__tar.gz → 14.6.1__tar.gz

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

@@ -4,9 +4,38 @@
 
 ## Unreleased: pdoc next
 
-- **Security:** Documentation generated with math mode (`pdoc --math`) does not include scripts
-  from polyfill.io anymore. See https://sansec.io/research/polyfill-supply-chain-attack for details.
-  Users who produce documentation with math mode should update immediately. All other users are unaffected.
+
+## 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.
+  ([#670](https://github.com/mitmproxy/pdoc/pull/670), @nathanthorpe, @mhils)
+- Add support for [GitHub Markdown Alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).
+  ([#718](https://github.com/mitmproxy/pdoc/pull/718), @mhils)
+- Improve rendering of enums on Python 3.12+.
+  ([#708](https://github.com/mitmproxy/pdoc/pull/708), @mhils)
+- Fix a bug where hyperlinks would get parsed as docstring references.
+  ([#709](https://github.com/mitmproxy/pdoc/pull/709), @mhils)
+- Fix a TypeError when trying to parse modules that implement `__dir__` incorrectly.
+  ([#710](https://github.com/mitmproxy/pdoc/pull/710), @mhils)
+- Fix a bug where a combination of `@dataclass` and `ctypes.Structure` would crash pdoc.
+  ([#711](https://github.com/mitmproxy/pdoc/pull/711), @mhils)
+- Update bundled version of markdown2.
+  ([#717](https://github.com/mitmproxy/pdoc/pull/717), @mhils)
+
+## 2024-06-25: pdoc 14.5.1
+
+- **[CVE-2024-38526](https://github.com/mitmproxy/pdoc/security/advisories/GHSA-5vgj-ggm4-fg62):** Documentation generated with math mode (`pdoc --math`) does not include scripts
+  from polyfill.io anymore. Users who produce documentation with math mode should update immediately. All other users are unaffected.
   ([#703](https://github.com/mitmproxy/pdoc/pull/703), @adhintz)
 
 ## 2024-05-16: pdoc 14.5.0

pdoc-14.6.1/LICENSE

@@ -0,0 +1,5 @@
+Copyright 2024 Maximilian Hils
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.1
 Name: pdoc
-Version: 14.5.1
+Version: 14.6.1
 Summary: API Documentation for Python Projects
 Author-email: Maximilian Hils <pdoc@maximilianhils.com>
-License: Unlicense
+License: MIT-0
 Project-URL: Homepage, https://pdoc.dev
 Project-URL: Source, https://github.com/mitmproxy/pdoc/
 Project-URL: Documentation, https://pdoc.dev/docs/pdoc.html

{pdoc-14.5.1 → pdoc-14.6.1}/pdoc/__init__.py

@@ -194,11 +194,17 @@ In general, we recommend keeping the following conventions:
 - If you want to document a special `__dunder__` method, the recommended way to do so is
   to not document the dunder method specifically, but to add some usage examples in the class documentation.
 
+> [!NOTE]
+> Hiding an item only removes it from documentation.
+> It is still displayed in the source code when clicking the "View Source" button.
+
 As a last resort, you can override pdoc's behavior with a custom module template (see
 [*How can I edit pdoc's HTML template?*](#edit-pdocs-html-template)).
 You can find an example at
 [`examples/custom-template/module.html.jinja2`](https://github.com/mitmproxy/pdoc/blob/main/examples/custom-template/module.html.jinja2).
 
+Hiding an item only removes it from documentation. It is still displayed in the source code when clicking the "View Source" button.
+
 ## ...exclude submodules from being documented?
 
 If you would like to exclude specific submodules from the documentation, the recommended way is to specify `__all__` as
@@ -475,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.5.1"  # this is read from setup.py
+__version__ = "14.6.1"  # this is read from setup.py
 
 from pathlib import Path
 from typing import overload

{pdoc-14.5.1 → pdoc-14.6.1}/pdoc/__main__.py

@@ -265,12 +265,12 @@ def get_dev_version() -> str:
 
 def _nicer_showwarning(message, category, filename, lineno, file=None, line=None):
     """A replacement for `warnings.showwarning` that renders warnings in a more visually pleasing way."""
-    if category == UserWarning:
+    if category is UserWarning:
         print(
             f"{yellow}Warn:{default} {message} {gray}({filename}:{lineno}){default}",
             file=sys.stderr,
         )
-    elif category == RuntimeWarning:
+    elif category is RuntimeWarning:
         print(
             f"{yellow}Warn:{default} {message}",
             file=sys.stderr,

{pdoc-14.5.1 → pdoc-14.6.1}/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.5.1 → pdoc-14.6.1}/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
@@ -587,15 +589,21 @@ class Class(Namespace[type]):
         if doc == dict.__doc__:
             # Don't display default docstring for dict subclasses (primarily TypedDict).
             return ""
-        is_dataclass_with_default_docstring = (
-            dataclasses.is_dataclass(self.obj)
-            # from https://github.com/python/cpython/blob/3.10/Lib/dataclasses.py
-            and doc
-            == self.obj.__name__
-            + str(inspect.signature(self.obj)).replace(" -> None", "")
-        )
-        if is_dataclass_with_default_docstring:
+        if doc in _Enum_default_docstrings:
+            # Don't display default docstring for enum subclasses.
             return ""
+        if dataclasses.is_dataclass(self.obj) and doc.startswith(self.obj.__name__):
+            try:
+                sig = inspect.signature(self.obj)
+            except Exception:
+                pass
+            else:
+                # from https://github.com/python/cpython/blob/3.10/Lib/dataclasses.py
+                is_dataclass_with_default_docstring = doc == self.obj.__name__ + str(
+                    sig
+                ).replace(" -> None", "")
+                if is_dataclass_with_default_docstring:
+                    return ""
         return doc
 
     @cached_property
@@ -649,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.
@@ -1306,6 +1321,15 @@ def _safe_getdoc(obj: Any) -> str:
         return doc.strip()
 
 
+_Enum_default_docstrings = tuple(
+    {
+        _safe_getdoc(enum.Enum),
+        _safe_getdoc(enum.IntEnum),
+        _safe_getdoc(_safe_getattr(enum, "StrEnum", enum.Enum)),
+    }
+)
+
+
 def _remove_memory_addresses(x: str) -> str:
     """Remove memory addresses from repr() output"""
     return re.sub(r" at 0x[0-9a-fA-F]+(?=>)", "", x)

{pdoc-14.5.1 → pdoc-14.6.1}/pdoc/doc_ast.py

@@ -245,7 +245,7 @@ def _parse_class(source: str) -> ast.ClassDef:
         t = tree.body[0]
         assert isinstance(t, ast.ClassDef)
         return t
-    return ast.ClassDef(body=[], decorator_list=[])
+    return ast.ClassDef(body=[], decorator_list=[])  # type: ignore
 
 
 @cache
@@ -265,7 +265,7 @@ 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(body=[], decorator_list=[])  # type: ignore
 
 
 def _parse(

{pdoc-14.5.1 → pdoc-14.6.1}/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.5.1 → pdoc-14.6.1}/pdoc/docstrings.py

@@ -427,7 +427,7 @@ def _rst_admonitions(contents: str, source_file: Path | None) -> str:
             else:
                 heading = ""
             return (
-                f'{ind}<div class="pdoc-alert pdoc-alert-{type}" markdown="1">\n'
+                f'{ind}<div class="alert {type}" markdown="1">\n'
                 f"{heading}"
                 f"{indent(contents, ind)}\n"
                 f"{ind}</div>\n"

{pdoc-14.5.1 → pdoc-14.6.1}/pdoc/extract.py

@@ -253,7 +253,7 @@ def iter_modules2(module: types.ModuleType) -> dict[str, pkgutil.ModuleInfo]:
     # This is a hacky workaround to register them.
     members = dir(module) if mod_all is None else mod_all
     for name in members:
-        if name in submodules or name == "__main__":
+        if name in submodules or name == "__main__" or not isinstance(name, str):
             continue
         member = getattr(module, name, None)
         is_wild_child_module = (