Support defaults from Pydantic fields

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,97 @@
+"""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:
+    pydantic: Optional[ModuleType]
+    try:
+        pydantic = import_module("pydantic")
+    except AnyException:
+        pydantic = None
+
+
+_IGNORED_FIELDS: Final[list[str]] = ["__fields__"]
+"""Fields to ignore when generating docs, e.g. those that emit deprecation warnings."""
+
+T = TypeVar("T")
+
+
+def is_pydantic_model(obj: Any) -> 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:
+        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: Any, field_name: str) -> Optional[str]:
+    if (
+        pydantic is not None
+        and isinstance(parent, type)
+        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
+
+
+def skip_field(
+    *,
+    parent_kind: str,
+    parent_obj: Any,
+    name: str,
+    taken_from: tuple[str, str],
+) -> bool:
+    """For Pydantic models, filter out all methods on the BaseModel
+    class, as they are almost never relevant to the consumers of the
+    inheriting model itself.
+    """
+
+    return (
+        pydantic is not None
+        and parent_kind == "class"
+        and is_pydantic_model(parent_obj)
+        and (name in _IGNORED_FIELDS or taken_from[0].startswith("pydantic"))
+    )

pdoc/doc.py

@@ -44,6 +44,7 @@
 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 +258,15 @@ 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)
+
+            if _pydantic.skip_field(
+                parent_kind=self.kind,
+                parent_obj=self.obj,
+                name=name,
+                taken_from=taken_from,
+            ):
+                continue
+
             doc: Doc[Any]
 
             is_classmethod = isinstance(obj, classmethod)
@@ -314,18 +324,35 @@ def members(self) -> dict[str, Doc]:
                     taken_from=taken_from,
                 )
             else:
+                default_value = obj
+
+                default_value = _pydantic.default_value(self.obj, name, obj)
+
                 doc = Variable(
                     self.modulename,
                     qualname,
                     docstring="",
                     annotation=self._var_annotations.get(name, empty),
-                    default_value=obj,
+                    default_value=default_value,
                     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 (
+                _pydantic.pydantic is not None
+                and self.kind == "class"
+                and _pydantic.is_pydantic_model(self.obj)
+            ):
+                _docstring = _pydantic.get_field_docstring(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):

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,7 @@
+<module with_pydantic  # A small example with…
+    <class with_pydantic.Foo  # Foo class documentat…
+        <var model_config = {'use_attribute_docstrings': True}  # Configuration for th…>
+        <var a: int = 1  # Docstring for a>
+        <var b: int = 2  # Docstring for b.>
+    >
+>