feat: serialize on alias

Author: watermarkhu

docs/index.md

@@ -50,3 +50,53 @@ hide:
 
 ///
 
+### Serialization Aliases
+
+When the extension is configured with `serialize_by_alias=True`, fields with a `serialization_alias` will appear under their alias names in the documentation. This is useful for APIs where the serialized output uses different field names than the Python attribute names. See [Pydantic's alias documentation](https://docs.pydantic.dev/latest/concepts/alias/) for more information.
+
+To enable this feature in your documentation configuration, configure the extension as follows:
+
+```yaml
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          extensions:
+            - griffe_pydantic:
+                serialize_by_alias: true
+```
+
+/// tab | Pydantic model
+
+```python
+--8<-- "examples/model_serialize.py"
+```
+
+///
+
+/// tab | Without alias
+
+```md exec="true" updatetoc="false"
+::: model_noserialize.UserModel
+    options:
+      heading_level: 4
+      extensions:
+      - griffe_pydantic: {serialize_by_alias: false}
+      skip_local_inventory: true
+```
+
+///
+
+/// tab | With alias
+
+```md exec="true" updatetoc="false"
+::: model_serialize.UserModel
+    options:
+      heading_level: 4
+      extensions:
+      - griffe_pydantic: {serialize_by_alias: true}
+      skip_local_inventory: true
+```
+
+///
+

examples/model_noserialize.py

@@ -0,0 +1,24 @@
+from pickle import TRUE
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class UserModel(BaseModel):
+    """A user model with serialization aliases.
+
+    When the extension is configured with `serialize_by_alias=True`, fields with
+    `serialization_alias` will appear under their alias names in the documentation.
+    """
+
+    model_config = ConfigDict(frozen=False)
+
+    user_id: int = Field()
+    """Unique user identifier, serialized as 'id'."""
+
+    full_name: str = Field(default="Anonymous")
+    """User's full name, serialized as 'name'."""
+
+    email_address: str
+    """User's email address."""
+
+    is_active: bool = Field(default=TRUE)
+    """Whether the user is active, serialized as 'active'."""

examples/model_serialize.py

@@ -0,0 +1,23 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class UserModel(BaseModel):
+    """A user model with serialization aliases.
+
+    When the extension is configured with `serialize_by_alias=True`, fields with
+    `serialization_alias` will appear under their alias names in the documentation.
+    """
+
+    model_config = ConfigDict(frozen=False)
+
+    user_id: int = Field(serialization_alias="id")
+    """Unique user identifier, serialized as 'id'."""
+
+    full_name: str = Field(default="Anonymous", serialization_alias="name")
+    """User's full name, serialized as 'name'."""
+
+    email_address: str
+    """User's email address."""
+
+    is_active: bool = Field(default=True, serialization_alias="active")
+    """Whether the user is active, serialized as 'active'."""

src/griffe_pydantic/_internal/common.py

@@ -29,7 +29,36 @@
 
 
 def _model_fields(cls: Class) -> dict[str, Attribute]:
-    return {name: attr for name, attr in cls.all_members.items() if "pydantic-field" in attr.labels}  # ty: ignore[invalid-return-type]
+    """Get model fields, using serialization_alias when configured.
+
+    Parameters:
+        cls: The Griffe class representing the Pydantic model.
+
+    Returns:
+        A dictionary of field name to Attribute, using serialization_alias as keys when appropriate.
+    """
+    fields = {name: attr for name, attr in cls.all_members.items() if "pydantic-field" in attr.labels}
+
+    ext_namespace = cls.extra.get(_self_namespace, {})
+    serialize_by_alias = ext_namespace.get("serialize_by_alias", False)
+
+    if not serialize_by_alias:
+        return fields  # ty: ignore[invalid-return-type]
+
+    # Re-key fields with their serialization_alias if present.
+    # For dynamic analysis, Pydantic fields don't appear as labeled members so we fall back
+    # to _pydantic_model_fields (populated from model_fields in dynamic._process_class).
+    pydantic_fields = ext_namespace.get("_pydantic_model_fields", {})
+    source = fields or dict.fromkeys(pydantic_fields)
+    remapped_fields = {}
+    for name, attr in source.items():
+        if attr is not None:
+            serialization_alias = attr.extra.get(_self_namespace, {}).get("serialization_alias")
+        else:
+            field_info = pydantic_fields.get(name)
+            serialization_alias = getattr(field_info, "serialization_alias", None) if field_info else None
+        remapped_fields[serialization_alias or name] = attr
+    return remapped_fields
 
 
 def _model_validators(cls: Class) -> dict[str, Function]:
@@ -48,13 +77,15 @@ def _json_schema(model: type[BaseModel]) -> str:
     return json.dumps(model.model_json_schema(), indent=2)
 
 
-def _process_class(cls: Class) -> None:
+def _process_class(cls: Class, *, serialize_by_alias: bool = False) -> None:
     """Set metadata on a Pydantic model.
 
     Parameters:
         cls: The Griffe class representing the Pydantic model.
+        serialize_by_alias: Whether to use serialization_alias as the field name.
     """
     cls.labels.add("pydantic-model")
+    cls.extra[_self_namespace]["serialize_by_alias"] = serialize_by_alias
     cls.extra[_self_namespace]["fields"] = partial(_model_fields, cls)
     cls.extra[_self_namespace]["validators"] = partial(_model_validators, cls)
     cls.extra[_mkdocstrings_namespace]["template"] = "pydantic_model.html.jinja"

src/griffe_pydantic/_internal/dynamic.py

@@ -42,6 +42,10 @@ def _process_attribute(obj: Any, attr: Attribute, cls: Class, *, processed: set[
             constraints[constraint] = value
     attr.extra[common._self_namespace]["constraints"] = constraints
 
+    # Store serialization_alias if present
+    if obj.serialization_alias:
+        attr.extra[common._self_namespace]["serialization_alias"] = obj.serialization_alias
+
     # Populate docstring from the field's `description` argument.
     if not attr.docstring and (docstring := obj.description):
         attr.docstring = Docstring(docstring, parent=attr)
@@ -56,9 +60,16 @@ def _process_function(obj: Callable, func: Function, cls: Class, *, processed: s
         common._process_function(func, cls, dec_info.fields)
 
 
-def _process_class(obj: type, cls: Class, *, processed: set[str], schema: bool = False) -> None:
+def _process_class(
+    obj: type,
+    cls: Class,
+    *,
+    processed: set[str],
+    schema: bool = False,
+    serialize_by_alias: bool = False,
+) -> None:
     """Detect and prepare Pydantic models."""
-    common._process_class(cls)
+    common._process_class(cls, serialize_by_alias=serialize_by_alias)
     if schema:
         try:
             cls.extra[common._self_namespace]["schema"] = common._json_schema(obj)  # ty: ignore[invalid-argument-type]
@@ -71,3 +82,22 @@ def _process_class(obj: type, cls: Class, *, processed: set[str], schema: bool =
             _process_attribute(getattr(obj, member.name), member, cls, processed=processed)  # ty: ignore[invalid-argument-type]
         elif kind is Kind.FUNCTION:
             _process_function(getattr(obj, member.name), member, cls, processed=processed)  # ty: ignore[invalid-argument-type]
+
+    # Also process Pydantic model fields directly from model_fields
+    # These are FieldInfo objects that may not appear as regular member attributes
+    if model_fields := getattr(obj, "model_fields", None):
+        pydantic_fields = {}
+        for field_name, field_info in model_fields.items():
+            pydantic_fields[field_name] = field_info
+            # If the field has a serialization_alias and serialize_by_alias is enabled,
+            # we want to use the alias in the output
+            if hasattr(field_info, "serialization_alias") and field_info.serialization_alias:
+                from pydantic.fields import FieldInfo  # noqa: PLC0415
+
+                if isinstance(field_info, FieldInfo):
+                    # Create a synthetic field entry with the alias
+                    # Store the FieldInfo in a place where _model_fields can access it
+                    pass
+
+        # Store model fields for later use
+        cls.extra[common._self_namespace]["_pydantic_model_fields"] = pydantic_fields

src/griffe_pydantic/_internal/extension.py

@@ -22,23 +22,37 @@
 class PydanticExtension(Extension):
     """Griffe extension for Pydantic."""
 
-    def __init__(self, *, schema: bool = False) -> None:
+    def __init__(self, *, schema: bool = False, serialize_by_alias: bool = False) -> None:
         """Initialize the extension.
 
         Parameters:
             schema: Whether to compute and store the JSON schema of models.
+            serialize_by_alias: Whether to use `serialization_alias` as the field name in documentation.
+                When enabled, fields with a `serialization_alias` will be keyed by that alias instead of their Python attribute name.
         """
         super().__init__()
         self._schema = schema
+        self._serialize_by_alias = serialize_by_alias
         self._processed: set[str] = set()
         self._recorded: list[tuple[ObjectNode, Class]] = []
 
     def on_package(self, *, pkg: Module, **kwargs: Any) -> None:  # noqa: ARG002
         """Detect models once the whole package is loaded."""
         for node, cls in self._recorded:
             self._processed.add(cls.canonical_path)
-            dynamic._process_class(node.obj, cls, processed=self._processed, schema=self._schema)
-        static._process_module(pkg, processed=self._processed, schema=self._schema)
+            dynamic._process_class(
+                node.obj,
+                cls,
+                processed=self._processed,
+                schema=self._schema,
+                serialize_by_alias=self._serialize_by_alias,
+            )
+        static._process_module(
+            pkg,
+            processed=self._processed,
+            schema=self._schema,
+            serialize_by_alias=self._serialize_by_alias,
+        )
 
     def on_class_instance(self, *, node: ast.AST | ObjectNode, cls: Class, **kwargs: Any) -> None:  # noqa: ARG002
         """Detect and prepare Pydantic models."""

src/griffe_pydantic/_internal/static.py

@@ -189,9 +189,24 @@ def _process_attribute(attr: Attribute, cls: Class, *, processed: set[str]) -> N
     attr.labels.discard("instance-attribute")
 
     attr.value = kwargs.get("default")
-    constraints = {kwarg: value for kwarg, value in kwargs.items() if kwarg not in {"default", "description"}}
+    constraints = {
+        kwarg: value
+        for kwarg, value in kwargs.items()
+        if kwarg not in {"default", "description", "serialization_alias"}
+    }
     attr.extra[common._self_namespace]["constraints"] = constraints
 
+    # Store serialization_alias if present
+    if serialization_alias := kwargs.get("serialization_alias"):
+        if isinstance(serialization_alias, str):
+            try:
+                attr.extra[common._self_namespace]["serialization_alias"] = ast.literal_eval(serialization_alias)
+            except ValueError:
+                attr.extra[common._self_namespace]["serialization_alias"] = serialization_alias
+        elif isinstance(serialization_alias, (ExprName, Expr)):
+            # For now, we can't resolve expressions at static analysis time
+            _logger.debug(f"Could not resolve serialization_alias expression for field '{attr.path}'")
+
     # Populate docstring from the field's `description` argument.
     if not attr.docstring and (description_expr := kwargs.get("description")):
         if description_text := _extract_description(description_expr):
@@ -215,7 +230,7 @@ def _process_function(func: Function, cls: Class, *, processed: set[str]) -> Non
         common._process_function(func, cls, fields)
 
 
-def _process_class(cls: Class, *, processed: set[str], schema: bool = False) -> None:
+def _process_class(cls: Class, *, processed: set[str], schema: bool = False, serialize_by_alias: bool = False) -> None:
     """Finalize the Pydantic model data."""
     if cls.canonical_path in processed:
         return
@@ -225,7 +240,7 @@ def _process_class(cls: Class, *, processed: set[str], schema: bool = False) ->
 
     processed.add(cls.canonical_path)
 
-    common._process_class(cls)
+    common._process_class(cls, serialize_by_alias=serialize_by_alias)
 
     if schema:
         import_path: Path | list[Path] = cls.package.filepath
@@ -240,7 +255,9 @@ def _process_class(cls: Class, *, processed: set[str], schema: bool = False) ->
             _logger.debug(f"Could not import class {cls.path} for JSON schema")
             return
         try:
-            cls.extra[common._self_namespace]["schema"] = common._json_schema(true_class)
+            cls.extra[common._self_namespace]["schema"] = common._json_schema(
+                true_class,
+            )
         except Exception as exc:  # noqa: BLE001
             # Schema generation can fail and raise Pydantic errors.
             _logger.debug("Failed to generate schema for %s: %s", cls.path, exc)
@@ -252,14 +269,15 @@ def _process_class(cls: Class, *, processed: set[str], schema: bool = False) ->
         elif kind is Kind.FUNCTION:
             _process_function(member, cls, processed=processed)  # ty: ignore[invalid-argument-type]
         elif kind is Kind.CLASS:
-            _process_class(member, processed=processed, schema=schema)  # ty: ignore[invalid-argument-type]
+            _process_class(member, processed=processed, schema=schema, serialize_by_alias=serialize_by_alias)  # ty: ignore[invalid-argument-type]
 
 
 def _process_module(
     mod: Module,
     *,
     processed: set[str],
     schema: bool = False,
+    serialize_by_alias: bool = False,
 ) -> None:
     """Handle Pydantic models in a module."""
     if mod.canonical_path in processed:
@@ -269,9 +287,9 @@ def _process_module(
     for cls in mod.classes.values():
         # Don't process aliases, real classes will be processed at some point anyway.
         if not cls.is_alias:
-            _process_class(cls, processed=processed, schema=schema)
+            _process_class(cls, processed=processed, schema=schema, serialize_by_alias=serialize_by_alias)
 
     for submodule in mod.modules.values():
         # Same for modules, don't process aliased ones.
         if not submodule.is_alias:
-            _process_module(submodule, processed=processed, schema=schema)
+            _process_module(submodule, processed=processed, schema=schema, serialize_by_alias=serialize_by_alias)

tests/test_extension.py

@@ -387,3 +387,49 @@ class Model(BaseModel):
         assert package["Model.field1"].docstring is not None
         assert "This is a multiline description." in package["Model.field1"].docstring.value
         assert "With multiple lines." in package["Model.field1"].docstring.value
+
+
+def test_serialize_by_alias_disabled_static() -> None:
+    """Test that without serialize_by_alias, static analysis uses Python attribute names."""
+    code = """
+    from pydantic import BaseModel, Field
+
+    class Model(BaseModel):
+        internal_name: str = Field(default="test", serialization_alias="external_name")
+        regular_field: int = Field(default=42)
+    """
+    with temporary_visited_package(
+        "package",
+        modules={"__init__.py": code},
+        extensions=Extensions(PydanticExtension(schema=False, serialize_by_alias=False)),
+    ) as package:
+        fields = package["Model"].extra["griffe_pydantic"]["fields"]()
+        assert "internal_name" in fields
+        assert "regular_field" in fields
+        assert "external_name" not in fields
+
+
+@pytest.mark.parametrize("analysis", ["static", "dynamic"])
+def test_serialize_by_alias_enabled(analysis: str) -> None:
+    """Test that serialize_by_alias extension setting uses serialization_alias as the field name."""
+    code = """
+    from pydantic import BaseModel, Field
+
+    class Model(BaseModel):
+        internal_name: str = Field(default="test", serialization_alias="external_name")
+        regular_field: int = Field(default=42)
+    """
+    loader = {"static": temporary_visited_package, "dynamic": temporary_inspected_package}[analysis]
+    with loader(
+        "package",
+        modules={"__init__.py": code},
+        extensions=Extensions(PydanticExtension(schema=False, serialize_by_alias=True)),
+        search_sys_path=analysis == "dynamic",
+    ) as package:
+        model = package["Model"]
+        assert model.labels == {"pydantic-model"}
+
+        fields = model.extra["griffe_pydantic"]["fields"]()
+        assert "internal_name" not in fields
+        assert "regular_field" in fields
+        assert "external_name" in fields