Support Pydantic model defaults + field descriptions (#802)

* Support defaults from Pydantic fields

* gate specifically on pydantic

* do not include importerror block in test coverage

* extend pragma no cover

* WIP: Convert to snapshot test

* remove dataclass import

* create _pydantic module

* [autofix.ci] apply automated fixes

* fix lint

* fix importlib import

* mark generated files

* suppress BaseModel fields

* harden

* update snapshot

* add note

* changelog

* [autofix.ci] apply automated fixes

* add docs

* [autofix.ci] apply automated fixes

* undo gitattributes

* Update pdoc/__init__.py

Co-authored-by: Maximilian Hils <[email protected]>

* render docstring

* [autofix.ci] apply automated fixes

* _pydantic.skip_field

* [autofix.ci] apply automated fixes

* fix lint

* refining pydantic-installed detection logic

* fix lint

* support 3.9 type checking

* expand type annotations

* cleanup

* [autofix.ci] apply automated fixes

* typecast

* move field exclusion to `Class._member_objects`

* rm defunct fn

* [autofix.ci] apply automated fixes

* simplify

* refine type annotations

* reuse is_pydantic_model logic

* simplify

* use frozenset

* rm unused

* [autofix.ci] apply automated fixes

* is_pydantic_model return False if pydantic not installed

* simplify (ish) conditional import logic

* simplify field-pruning

* localize more logic to _pydantic

* import TypeGuard from typing_extensions

* simplify docstring logic

* Update pdoc/doc.py

* simplify

* Update pdoc/_pydantic.py

Co-authored-by: Maximilian Hils <[email protected]>

* Revert "import TypeGuard from typing_extensions"

This reverts commit efaafcd.

* add typing.cast back in

* simplify

* fix nits

* update lockfile

* add BaseModel test

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Maximilian Hils <[email protected]>
Co-authored-by: Maximilian Hils <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -17,6 +17,9 @@
   upstream](https://github.com/trentm/python-markdown2)
 - Add support for keyword args for Google flavor docs.
   ([#840](https://github.com/mitmproxy/pdoc/pull/840), @aleksslitvinovs)
+- Add support for Pydantic-style field docstrings,
+  e.g. `pydantic.Field(description="...")`
+  ([#802](https://github.com/mitmproxy/pdoc/pull/802), @jinnovation)
 
 ## 2025-06-04: pdoc 15.0.4
 

pdoc/__init__.py

@@ -260,6 +260,25 @@ class GoldenRetriever(Dog):
 Adding additional syntax elements is usually easy. If you feel that pdoc doesn't parse a docstring element properly,
 please amend `pdoc.docstrings` and send us a pull request!
 
+## ...document Pydantic models?
+
+For [Pydantic models](https://docs.pydantic.dev/latest/concepts/models/), pdoc
+will extract [field](https://docs.pydantic.dev/latest/concepts/fields/)
+descriptions and treat them just like [documented
+variables](#document-variables). For example, the following two Pydantic models
+would have identical pdoc-rendered documentation:
+
+```python
+from pydantic import BaseModel, Field
+
+class Foo(BaseModel):
+    a: int = Field(description="Docs for field a.")
+
+class OtherFoo(BaseModel):
+    a: int
+    """Docs for field a."""
+
+```
 
 ## ...render math formulas?
 

pdoc/_pydantic.py

@@ -0,0 +1,54 @@
+"""Work with Pydantic models."""
+
+from __future__ import annotations
+
+import types
+from typing import Any
+from typing import TypeAlias
+from typing import TypeGuard
+
+try:
+    import pydantic
+except ImportError:  # pragma: no cover
+    pydantic = None  # type: ignore
+
+ClassOrModule: TypeAlias = type | types.ModuleType
+"""Type alias for the type of `Namespace.obj`."""
+
+IGNORED_FIELDS: frozenset[str] = frozenset(
+    (["__fields__"] + list(pydantic.BaseModel.__dict__.keys()))
+    if pydantic is not None
+    else []
+)
+"""Fields to ignore when generating docs, e.g. those that emit deprecation
+warnings or that are not relevant to users of BaseModel-derived classes."""
+
+
+def is_pydantic_model(obj: ClassOrModule) -> TypeGuard[pydantic.BaseModel]:
+    """Returns whether an object is a Pydantic model."""
+    if pydantic is None:  # pragma: no cover
+        # classes that subclass pydantic.BaseModel can only be instantiated if pydantic is importable
+        # => if we cannot import pydantic, the passed object cannot be a subclass of BaseModel.
+        return False
+
+    return isinstance(obj, type) and issubclass(obj, pydantic.BaseModel)
+
+
+def default_value(parent: ClassOrModule, name: str, obj: Any) -> Any:
+    """Determine the default value of obj.
+
+    For pydantic BaseModels, extract the default value from field metadata.
+    For all other objects, return `obj` as-is.
+    """
+    if is_pydantic_model(parent):
+        pydantic_fields = parent.__pydantic_fields__
+        return pydantic_fields[name].default if name in pydantic_fields else obj
+
+    return obj
+
+
+def get_field_docstring(parent: ClassOrModule, field_name: str) -> str | None:
+    if is_pydantic_model(parent):
+        if field := parent.__pydantic_fields__.get(field_name, None):
+            return field.description
+    return None

pdoc/doc.py

@@ -41,10 +41,12 @@
 from typing import TypeAlias
 from typing import TypedDict
 from typing import TypeVar
+from typing import cast
 from typing import get_origin
 from typing import is_typeddict
 import warnings
 
+from pdoc import _pydantic
 from pdoc import doc_ast
 from pdoc import doc_pyi
 from pdoc import extract
@@ -209,7 +211,10 @@ def __lt__(self, other):
         )
 
 
-class Namespace(Doc[T], metaclass=ABCMeta):
+U = TypeVar("U", bound=types.ModuleType | type)
+
+
+class Namespace(Doc[U], metaclass=ABCMeta):
     """
     A documentation object that can have children. In other words, either a module or a class.
     """
@@ -318,13 +323,17 @@ def members(self) -> dict[str, Doc]:
                     qualname,
                     docstring="",
                     annotation=self._var_annotations.get(name, empty),
-                    default_value=obj,
+                    default_value=_pydantic.default_value(self.obj, name, obj),
                     taken_from=taken_from,
                 )
-            if self._var_docstrings.get(name):
+
+            if _doc := _pydantic.get_field_docstring(cast(type, self.obj), name):
+                doc.docstring = _doc
+            elif self._var_docstrings.get(name):
                 doc.docstring = self._var_docstrings[name]
-            if self._func_docstrings.get(name) and not doc.docstring:
+            elif self._func_docstrings.get(name) and not doc.docstring:
                 doc.docstring = self._func_docstrings[name]
+
             members[doc.name] = doc
 
         if isinstance(self, Module):
@@ -774,6 +783,12 @@ def _member_objects(self) -> dict[str, Any]:
         for cls in self._bases:
             sorted, unsorted = doc_ast.sort_by_source(cls, sorted, unsorted)
         sorted.update(unsorted)
+
+        if _pydantic.is_pydantic_model(self.obj):
+            sorted = {
+                k: v for k, v in sorted.items() if k not in _pydantic.IGNORED_FIELDS
+            }
+
         return sorted
 
     @cached_property
@@ -904,7 +919,7 @@ def __init__(
         else:
             unwrapped = func
         super().__init__(modulename, qualname, unwrapped, taken_from)
-        self.wrapped = func
+        self.wrapped = func  # type: ignore
 
     @cache
     @_include_fullname_in_traceback

pyproject.toml

@@ -52,6 +52,7 @@ dev-dependencies = [
     "pytest-timeout>=2.3.1",
     "hypothesis>=6.113.0",
     "pdoc-pyo3-sample-library>=1.0.11",
+    "pydantic>=2.12.0",
 ]
 
 [build-system]
@@ -103,6 +104,11 @@ select = ["E", "F", "I"]
 ignore = ["E501"]
 isort = { force-single-line = true, force-sort-within-sections = true }
 
+[tool.ruff.per-file-target-version]
+"test/testdata/misc_py312.py" = "py312"
+"test/testdata/misc_py313.py" = "py313"
+"test/testdata/misc_py314.py" = "py314"
+
 [tool.tox]
 legacy_tox_ini = """
 [tox]

test/test__pydantic.py

@@ -0,0 +1,26 @@
+import pydantic
+
+from pdoc import _pydantic
+import pdoc.doc
+
+
+def test_no_pydantic(monkeypatch):
+    monkeypatch.setattr(_pydantic, "pydantic", None)
+
+    assert not _pydantic.is_pydantic_model(pdoc.doc.Module)
+    assert _pydantic.get_field_docstring(pdoc.doc.Module, "kind") is None
+    assert _pydantic.default_value(pdoc.doc.Module, "kind", "module") == "module"
+
+
+def test_with_pydantic(monkeypatch):
+    class User(pydantic.BaseModel):
+        id: int
+        name: str = pydantic.Field(description="desc", default="Jane Doe")
+
+    assert _pydantic.is_pydantic_model(User)
+    assert _pydantic.get_field_docstring(User, "name") == "desc"
+    assert _pydantic.default_value(User, "name", None) == "Jane Doe"
+
+    assert not _pydantic.is_pydantic_model(pdoc.doc.Module)
+    assert _pydantic.get_field_docstring(pdoc.doc.Module, "kind") is None
+    assert _pydantic.default_value(pdoc.doc.Module, "kind", "module") == "module"

test/test_snapshot.py

@@ -164,6 +164,7 @@ def outfile(self, format: str) -> Path:
             "include_undocumented": False,
         },
     ),
+    Snapshot("with_pydantic"),
 ]
 
 

test/testdata/with_pydantic.html

@@ -0,0 +1,18 @@
+"""
+A small example with Pydantic entities.
+"""
+
+import pydantic
+
+
+class Foo(pydantic.BaseModel):
+    """Foo class documentation."""
+
+    model_config = pydantic.ConfigDict(
+        use_attribute_docstrings=True,
+    )
+
+    a: int = pydantic.Field(default=1, description="Docstring for a")
+
+    b: int = 2
+    """Docstring for b."""

test/testdata/with_pydantic.py

@@ -0,0 +1,6 @@
+<module with_pydantic  # A small example with…
+    <class with_pydantic.Foo  # Foo class documentat…
+        <var a: int = 1  # Docstring for a>
+        <var b: int = 2  # Docstring for b.>
+    >
+>