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,68 @@
+"""Work with Pydantic models."""
+
+from __future__ import annotations
+
+from typing import Any
+from typing import Optional
+from typing import TypeVar
+
+from typing_extensions import TypeGuard
+
+_HAVE_PYDANTIC: bool = False
+try:
+    import pydantic
+
+    _HAVE_PYDANTIC = True
+except ImportError:  # pragma: no cover
+    _HAVE_PYDANTIC = False
+
+_IGNORED_FIELDS: frozenset[str] = frozenset(
+    [
+        "__fields__",
+    ]
+    + list(pydantic.BaseModel.__dict__.keys())
+    if _HAVE_PYDANTIC
+    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) -> TypeGuard[pydantic.BaseModel]:
+    """Returns whether an object is a Pydantic model.
+
+    If Pydantic is not isntalled, returns False unconditionally.
+
+    """
+    if not _HAVE_PYDANTIC:  # pragma: no cover
+        return False
+
+    return isinstance(obj, type) and issubclass(obj, pydantic.BaseModel)
+
+
+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 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: type, field_name: str) -> Optional[str]:
+    if is_pydantic_model(parent):
+        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
@@ -319,13 +321,24 @@ 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]
+
+            doc.docstring = next(
+                (
+                    d
+                    for d in [
+                        _pydantic.get_field_docstring(cast(type, self.obj), name),
+                        self._var_docstrings.get(name),
+                        doc.docstring,
+                        self._func_docstrings.get(name),
+                    ]
+                    if d
+                ),
+                doc.docstring,
+            )
+
             members[doc.name] = doc
 
         if isinstance(self, Module):
@@ -775,6 +788,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

pyproject.toml

@@ -12,6 +12,7 @@ dependencies = [
     "pygments >= 2.12.0",
     "MarkupSafe >= 1.1.1",
     "markdown2>=2.5.4",
+    "typing-extensions>=4.15.0",
 ]
 
 classifiers = [
@@ -52,6 +53,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.>
+    >
+>