refactor: change option to show_as_alias

Author: watermarkhu

docs/index.md

@@ -50,9 +50,9 @@ hide:
 
 ///
 
-### Serialization Aliases
+### Show as alias
 
-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.
+When the extension is configured with `show_as_alias=True`, fields with a `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:
 
@@ -63,9 +63,20 @@ plugins:
         python:
           extensions:
             - griffe_pydantic:
-                serialize_by_alias: true
+                show_as_alias: true
 ```
 
+Or use the local configuration:
+
+```markdown
+::: model_ext.ExampleModel
+    options:
+      extensions:
+      - griffe_pydantic:
+          show_as_alias: true
+```
+
+
 /// tab | Pydantic model
 
 ```python
@@ -81,7 +92,7 @@ plugins:
     options:
       heading_level: 4
       extensions:
-      - griffe_pydantic: {serialize_by_alias: false}
+      - griffe_pydantic: {show_as_alias: false}
       skip_local_inventory: true
 ```
 
@@ -94,9 +105,8 @@ plugins:
     options:
       heading_level: 4
       extensions:
-      - griffe_pydantic: {serialize_by_alias: true}
+      - griffe_pydantic: {show_as_alias: true}
       skip_local_inventory: true
 ```
 
 ///
-

examples/model_noserialize.py

@@ -5,8 +5,8 @@
 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.
+    When the extension is configured with `show_as_alias=True`, fields with
+    `alias` will appear under their alias names in the documentation.
     """
 
     model_config = ConfigDict(frozen=False)

examples/model_serialize.py

@@ -4,20 +4,20 @@
 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.
+    When the extension is configured with `show_as_alias=True`, fields with
+    `alias` will appear under their alias names in the documentation.
     """
 
     model_config = ConfigDict(frozen=False)
 
-    user_id: int = Field(serialization_alias="id")
+    user_id: int = Field(alias="id")
     """Unique user identifier, serialized as 'id'."""
 
-    full_name: str = Field(default="Anonymous", serialization_alias="name")
+    full_name: str = Field(default="Anonymous", 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")
+    is_active: bool = Field(default=True, alias="active")
     """Whether the user is active, serialized as 'active'."""

src/griffe_pydantic/_internal/dynamic.py

@@ -26,7 +26,7 @@ def _process_attribute(
     cls: Class,
     *,
     processed: set[str],
-    serialize_by_alias: bool = False,
+    show_as_alias: bool = False,
 ) -> None:
     """Handle Pydantic fields."""
     from pydantic.fields import FieldInfo  # noqa: PLC0415
@@ -49,9 +49,9 @@ def _process_attribute(
             constraints[constraint] = value
     attr.extra[common._self_namespace]["constraints"] = constraints
 
-    # Store serialization_alias if present
-    if serialize_by_alias and obj.serialization_alias:
-        attr.extra[common._self_namespace]["serialization_alias"] = obj.serialization_alias
+    # Store alias if present
+    if show_as_alias and obj.alias:
+        attr.extra[common._self_namespace]["alias"] = obj.alias
         attr.extra[common._mkdocstrings_namespace]["template"] = "pydantic_attribute_alias.html.jinja"
 
     # Populate docstring from the field's `description` argument.
@@ -74,7 +74,7 @@ def _process_class(
     *,
     processed: set[str],
     schema: bool = False,
-    serialize_by_alias: bool = False,
+    show_as_alias: bool = False,
 ) -> None:
     """Detect and prepare Pydantic models."""
     common._process_class(cls)
@@ -92,7 +92,26 @@ def _process_class(
                 member,  # ty: ignore[invalid-argument-type]
                 cls,
                 processed=processed,
-                serialize_by_alias=serialize_by_alias,
+                show_as_alias=show_as_alias,
             )
         elif kind is Kind.FUNCTION:
             _process_function(getattr(obj, member.name), member, cls, processed=processed)  # ty: ignore[invalid-argument-type]
+
+    # Process model fields that may not have been discovered by griffe
+    if hasattr(obj, "model_fields") and isinstance(obj.model_fields, dict):
+        for field_name, field_info in obj.model_fields.items():
+            if field_name not in cls.all_members:
+                # Create an Attribute object for this field
+                attr = Attribute(
+                    name=field_name,
+                    lineno=0,
+                    endlineno=0,
+                )
+                cls.members[field_name] = attr  # ty: ignore[invalid-assignment]
+                _process_attribute(
+                    field_info,
+                    attr,
+                    cls,
+                    processed=processed,
+                    show_as_alias=show_as_alias,
+                )

src/griffe_pydantic/_internal/extension.py

@@ -22,17 +22,17 @@
 class PydanticExtension(Extension):
     """Griffe extension for Pydantic."""
 
-    def __init__(self, *, schema: bool = False, serialize_by_alias: bool = False) -> None:
+    def __init__(self, *, schema: bool = False, show_as_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.
+            show_as_alias: Whether to use `alias` as the field name in documentation.
+                When enabled, fields with a `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._show_as_alias = show_as_alias
         self._processed: set[str] = set()
         self._recorded: list[tuple[ObjectNode, Class]] = []
 
@@ -45,13 +45,13 @@ def on_package(self, *, pkg: Module, **kwargs: Any) -> None:  # noqa: ARG002
                 cls,
                 processed=self._processed,
                 schema=self._schema,
-                serialize_by_alias=self._serialize_by_alias,
+                show_as_alias=self._show_as_alias,
             )
         static._process_module(
             pkg,
             processed=self._processed,
             schema=self._schema,
-            serialize_by_alias=self._serialize_by_alias,
+            show_as_alias=self._show_as_alias,
         )
 
     def on_class_instance(self, *, node: ast.AST | ObjectNode, cls: Class, **kwargs: Any) -> None:  # noqa: ARG002

src/griffe_pydantic/_internal/static.py

@@ -96,7 +96,7 @@ def _pydantic_validator(func: Function) -> ExprCall | None:
     return None
 
 
-def _process_attribute(attr: Attribute, cls: Class, *, processed: set[str], serialize_by_alias: bool = False) -> None:
+def _process_attribute(attr: Attribute, cls: Class, *, processed: set[str], show_as_alias: bool = False) -> None:
     """Handle Pydantic fields."""
     if attr.canonical_path in processed:
         return
@@ -189,25 +189,21 @@ def _process_attribute(attr: Attribute, cls: Class, *, processed: set[str], seri
     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", "serialization_alias"}
-    }
+    constraints = {kwarg: value for kwarg, value in kwargs.items() if kwarg not in {"default", "description", "alias"}}
     attr.extra[common._self_namespace]["constraints"] = constraints
 
-    # Store serialization_alias if present
-    if serialize_by_alias and (serialization_alias := kwargs.get("serialization_alias")):
-        if isinstance(serialization_alias, str):
+    # Store alias if present
+    if show_as_alias and (alias := kwargs.get("alias")):
+        if isinstance(alias, str):
             try:
-                attr.extra[common._self_namespace]["serialization_alias"] = ast.literal_eval(serialization_alias)
+                attr.extra[common._self_namespace]["alias"] = ast.literal_eval(alias)
             except ValueError:
-                attr.extra[common._self_namespace]["serialization_alias"] = serialization_alias
-            # Set the attribute template to the custom template, which will use the serialization_alias instead of the attribute name.
+                attr.extra[common._self_namespace]["alias"] = alias
+            # Set the attribute template to the custom template, which will use the alias instead of the attribute name.
             attr.extra[common._mkdocstrings_namespace]["template"] = "pydantic_attribute_alias.html.jinja"
-        elif isinstance(serialization_alias, (ExprName, Expr)):
+        elif isinstance(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}'")
+            _logger.debug(f"Could not resolve alias expression for field '{attr.path}'")
 
     # Populate docstring from the field's `description` argument.
     if not attr.docstring and (description_expr := kwargs.get("description")):
@@ -232,7 +228,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, serialize_by_alias: bool = False) -> None:
+def _process_class(cls: Class, *, processed: set[str], schema: bool = False, show_as_alias: bool = False) -> None:
     """Finalize the Pydantic model data."""
     if cls.canonical_path in processed:
         return
@@ -267,19 +263,19 @@ def _process_class(cls: Class, *, processed: set[str], schema: bool = False, ser
     for member in cls.all_members.values():
         kind = member.kind
         if kind is Kind.ATTRIBUTE:
-            _process_attribute(member, cls, processed=processed, serialize_by_alias=serialize_by_alias)  # ty: ignore[invalid-argument-type]
+            _process_attribute(member, cls, processed=processed, show_as_alias=show_as_alias)  # ty: ignore[invalid-argument-type]
         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, serialize_by_alias=serialize_by_alias)  # ty: ignore[invalid-argument-type]
+            _process_class(member, processed=processed, schema=schema, show_as_alias=show_as_alias)  # ty: ignore[invalid-argument-type]
 
 
 def _process_module(
     mod: Module,
     *,
     processed: set[str],
     schema: bool = False,
-    serialize_by_alias: bool = False,
+    show_as_alias: bool = False,
 ) -> None:
     """Handle Pydantic models in a module."""
     if mod.canonical_path in processed:
@@ -289,9 +285,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, serialize_by_alias=serialize_by_alias)
+            _process_class(cls, processed=processed, schema=schema, show_as_alias=show_as_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, serialize_by_alias=serialize_by_alias)
+            _process_module(submodule, processed=processed, schema=schema, show_as_alias=show_as_alias)

src/griffe_pydantic/templates/material/_base/pydantic_attribute_alias.html.jinja

@@ -33,7 +33,7 @@ Context:
 
     {# {% set attribute_name = attribute.path if show_full_path else attribute.name %} #}
     {# TODO some better way to visualize the alias #}
-    {% set attribute_name = attribute.extra.griffe_pydantic.serialization_alias %}
+    {% set attribute_name = attribute.extra.griffe_pydantic.alias %}
 
     {% if not root or config.show_root_heading %}
       {% filter heading(

tests/test_extension.py

@@ -57,7 +57,7 @@ class RegularClass(object):
         regular_attr = 1
 
     class AliasClass(BaseModel):
-        internal_name: str = Field(default="test", serialization_alias="external_name")
+        internal_name: str = Field(default="test", alias="external_name")
         regular_field: int = Field(default=42)
 """
 
@@ -69,7 +69,7 @@ def test_extension(analysis: str) -> None:
     with loader(
         "package",
         modules={"__init__.py": code},
-        extensions=Extensions(PydanticExtension(schema=True, serialize_by_alias=True)),
+        extensions=Extensions(PydanticExtension(schema=True, show_as_alias=True)),
         search_sys_path=analysis == "dynamic",
     ) as package:
         assert package
@@ -90,9 +90,9 @@ def test_extension(analysis: str) -> None:
         assert package.classes["AliasClass"].labels == {"pydantic-model"}
 
         fields = package.classes["AliasClass"].extra["griffe_pydantic"]["fields"]()
-        assert "internal_name" not in fields
+        assert "internal_name" in fields
         assert "regular_field" in fields
-        assert "external_name" in fields
+        assert "external_name" not in fields
 
 
 def test_imported_models() -> None:
@@ -401,19 +401,19 @@ class Model(BaseModel):
         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."""
+def test_show_as_alias_disabled_static() -> None:
+    """Test that without show_as_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")
+        internal_name: str = Field(default="test", 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)),
+        extensions=Extensions(PydanticExtension(schema=False, show_as_alias=False)),
     ) as package:
         fields = package["Model"].extra["griffe_pydantic"]["fields"]()
         assert "internal_name" in fields