Support Pydantic model defaults + field descriptions

CHANGELOG.md

@@ -10,6 +10,9 @@
   ([#831](https://github.com/mitmproxy/pdoc/issues/831), @iFreilicht)
 - Replace vendored version of `markdown2` with the [official
   upstream](https://github.com/trentm/python-markdown2)
+- 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,81 @@
+"""Work with Pydantic models."""
+
+from importlib import import_module
+from types import ModuleType
+from typing import TYPE_CHECKING
+from typing import Any
+from typing import Final
+from typing import Optional
+from typing import TypeVar
+from typing import cast
+
+from pdoc.docstrings import AnyException
+
+if TYPE_CHECKING:
+    import pydantic
+else:  # pragma: no cover
+    pydantic: Optional[ModuleType]
+    try:
+        pydantic = import_module("pydantic")
+    except AnyException:
+        pydantic = None
+
+
+_IGNORED_FIELDS: Final[list[str]] = (
+    [
+        "__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."""
+
+T = TypeVar("T")
+
+
+def is_pydantic_model(obj: type) -> bool:
+    """Returns whether an object is a Pydantic model.
+
+    Raises:
+        ModuleNotFoundError: when function is called but Pydantic is not on the PYTHONPATH.
+
+    """
+    if pydantic is None:  # pragma: no cover
+        raise ModuleNotFoundError(
+            "_pydantic.is_pydantic_model() needs Pydantic installed"
+        )
+
+    return pydantic.BaseModel in obj.__bases__
+
+
+def default_value(parent: Any, name: str, obj: T) -> T:
+    """Determine the default value of obj.
+
+    If pydantic is not installed or the parent type is not a Pydantic model,
+    simply returns obj.
+
+    """
+    if (
+        pydantic is not None
+        and isinstance(parent, type)
+        and issubclass(parent, pydantic.BaseModel)
+    ):
+        _parent = cast(pydantic.BaseModel, 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: type, field_name: str) -> Optional[str]:
+    if pydantic is not None and issubclass(parent, pydantic.BaseModel):
+        pydantic_fields = parent.__pydantic_fields__
+        return (
+            pydantic_fields[field_name].description
+            if field_name in pydantic_fields
+            else None
+        )
+
+    return None

pdoc/doc.py

@@ -41,9 +41,11 @@
 from typing import TypedDict
 from typing import TypeVar
 from typing import Union
+from typing import cast
 from typing import get_origin
 import warnings
 
+from pdoc import _pydantic
 from pdoc import doc_ast
 from pdoc import doc_pyi
 from pdoc import extract
@@ -257,6 +259,7 @@ def members(self) -> dict[str, Doc]:
         for name, obj in self._member_objects.items():
             qualname = f"{self.qualname}.{name}".lstrip(".")
             taken_from = self._taken_from(name, obj)
+
             doc: Doc[Any]
 
             is_classmethod = isinstance(obj, classmethod)
@@ -319,13 +322,22 @@ 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):
-                doc.docstring = self._var_docstrings[name]
-            if self._func_docstrings.get(name) and not doc.docstring:
-                doc.docstring = self._func_docstrings[name]
+
+            _docstring: str | None = None
+            if self.kind == "class":
+                _docstring = _pydantic.get_field_docstring(cast(type, self.obj), name)
+
+            if _docstring is None:
+                if self._var_docstrings.get(name):
+                    doc.docstring = self._var_docstrings[name]
+                if self._func_docstrings.get(name) and not doc.docstring:
+                    doc.docstring = self._func_docstrings[name]
+            else:
+                doc.docstring = _docstring
+
             members[doc.name] = doc
 
         if isinstance(self, Module):
@@ -775,6 +787,11 @@ 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.pydantic is not None and _pydantic.is_pydantic_model(self.obj):
+            for field in _pydantic._IGNORED_FIELDS:
+                sorted.pop(field, None)
+
         return sorted
 
     @cached_property

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]

test/test_snapshot.py

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

test/testdata/with_pydantic.py

@@ -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.txt

@@ -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.>
+    >
+>