fixup! show alias

Author: pawamoy

docs/index.md

@@ -49,64 +49,3 @@ hide:
 ```
 
 ///
-
-### Show as alias
-
-When the extension is configured with `show_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:
-
-```yaml
-plugins:
-  - mkdocstrings:
-      handlers:
-        python:
-          extensions:
-            - griffe_pydantic:
-                show_alias: true
-```
-
-Or use the local configuration:
-
-```markdown
-::: model_ext.ExampleModel
-    options:
-      extensions:
-      - griffe_pydantic:
-          show_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: {show_alias: false}
-      skip_local_inventory: true
-```
-
-///
-
-/// tab | With alias
-
-```md exec="true" updatetoc="false"
-::: model_serialize.UserModel
-    options:
-      heading_level: 4
-      extensions:
-      - griffe_pydantic: {show_alias: true}
-      skip_local_inventory: true
-```
-
-///

examples/model_ext.py

@@ -20,6 +20,15 @@ class ExampleModel(BaseModel):
         default=5, ge=0, le=100, description="Shows constraints within doc string."
     )
 
+    field_with_alias: int = Field(alias="alias_field")
+    """Shows the field with its (validation and serialization) alias."""
+
+    field_with_validation_alias: int = Field(validation_alias="validation_alias_field")
+    """Shows the field with its validation alias."""
+
+    field_with_serialization_alias: int = Field(field_with_serialization_aliasalias="serialization_alias_field")
+    """Shows the field with its serialization alias."""
+
     @field_validator("field_with_validator_and_alias", "field_without_default", mode="before")
     @classmethod
     def check_max_length_ten(cls, v) -> str:

examples/model_noserialize.py

@@ -20,14 +20,7 @@
 _logger = get_logger("griffe_pydantic")
 
 
-def _process_attribute(
-    obj: Any,
-    attr: Attribute,
-    cls: Class,
-    *,
-    processed: set[str],
-    show_alias: bool = False,
-) -> None:
+def _process_attribute(obj: Any, attr: Attribute, cls: Class, *, processed: set[str]) -> None:
     """Handle Pydantic fields."""
     from pydantic.fields import FieldInfo  # noqa: PLC0415
 
@@ -50,9 +43,10 @@ def _process_attribute(
     attr.extra[common._self_namespace]["constraints"] = constraints
 
     # Store alias if present
-    if show_alias and obj.alias:
-        attr.extra[common._self_namespace]["alias"] = obj.alias
-        attr.extra[common._mkdocstrings_namespace]["template"] = "pydantic_attribute_alias.html.jinja"
+    if obj.alias:
+        attr.extra[common._self_namespace]["validation_alias"] = obj.alias
+        attr.extra[common._self_namespace]["serialization_alias"] = obj.alias
+        attr.extra[common._mkdocstrings_namespace]["template"] = "pydantic_field.html.jinja"
 
     # Populate docstring from the field's `description` argument.
     if not attr.docstring and (docstring := obj.description):
@@ -68,14 +62,7 @@ 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,
-    show_alias: bool = False,
-) -> None:
+def _process_class(obj: type, cls: Class, *, processed: set[str], schema: bool = False) -> None:
     """Detect and prepare Pydantic models."""
     common._process_class(cls)
     if schema:
@@ -92,7 +79,6 @@ def _process_class(
                 member,  # ty: ignore[invalid-argument-type]
                 cls,
                 processed=processed,
-                show_alias=show_alias,
             )
         elif kind is Kind.FUNCTION:
             _process_function(getattr(obj, member.name), member, cls, processed=processed)  # ty: ignore[invalid-argument-type]
@@ -108,10 +94,4 @@ def _process_class(
                     endlineno=0,
                 )
                 cls.members[field_name] = attr  # ty: ignore[invalid-assignment]
-                _process_attribute(
-                    field_info,
-                    attr,
-                    cls,
-                    processed=processed,
-                    show_alias=show_alias,
-                )
+                _process_attribute(field_info, attr, cls, processed=processed)

examples/model_serialize.py

@@ -22,37 +22,23 @@
 class PydanticExtension(Extension):
     """Griffe extension for Pydantic."""
 
-    def __init__(self, *, schema: bool = False, show_alias: bool = False) -> None:
+    def __init__(self, *, schema: bool = False) -> None:
         """Initialize the extension.
 
         Parameters:
             schema: Whether to compute and store the JSON schema of models.
-            show_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._show_alias = show_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,
-                show_alias=self._show_alias,
-            )
-        static._process_module(
-            pkg,
-            processed=self._processed,
-            schema=self._schema,
-            show_alias=self._show_alias,
-        )
+            dynamic._process_class(node.obj, cls, processed=self._processed, schema=self._schema)
+        static._process_module(pkg, processed=self._processed, schema=self._schema)
 
     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/dynamic.py

@@ -96,7 +96,21 @@ def _pydantic_validator(func: Function) -> ExprCall | None:
     return None
 
 
-def _process_attribute(attr: Attribute, cls: Class, *, processed: set[str], show_alias: bool = False) -> None:
+def _literal_or_debug(value: Expr | str | None, /, *, path: str) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        try:
+            return ast.literal_eval(value)
+        except ValueError:
+            return value
+    elif isinstance(value, (ExprName, Expr)):
+        _logger.debug(f"Could not resolve expression '{value}' as a literal for field {path}")
+        return None
+    return None
+
+
+def _process_attribute(attr: Attribute, cls: Class, *, processed: set[str]) -> None:
     """Handle Pydantic fields."""
     if attr.canonical_path in processed:
         return
@@ -191,19 +205,16 @@ def _process_attribute(attr: Attribute, cls: Class, *, processed: set[str], show
     attr.value = kwargs.get("default")
     constraints = {kwarg: value for kwarg, value in kwargs.items() if kwarg not in {"default", "description", "alias"}}
     attr.extra[common._self_namespace]["constraints"] = constraints
+    attr.extra[common._mkdocstrings_namespace]["template"] = "pydantic_field.html.jinja"
 
-    # Store alias if present
-    if show_alias and (alias := kwargs.get("alias")):
-        if isinstance(alias, str):
-            try:
-                attr.extra[common._self_namespace]["alias"] = ast.literal_eval(alias)
-            except ValueError:
-                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(alias, (ExprName, Expr)):
-            # For now, we can't resolve expressions at static analysis time
-            _logger.debug(f"Could not resolve alias expression for field '{attr.path}'")
+    # Store validation/serialization aliases if defined.
+    if alias := _literal_or_debug(kwargs.get("alias"), path=attr.path):
+        attr.extra[common._self_namespace]["validation_alias"] = alias
+        attr.extra[common._self_namespace]["serialization_alias"] = alias
+    elif validation_alias := _literal_or_debug(kwargs.get("validation_alias"), path=attr.path):
+        attr.extra[common._self_namespace]["validation_alias"] = validation_alias
+    elif serialization_alias := _literal_or_debug(kwargs.get("serialization_alias"), path=attr.path):
+        attr.extra[common._self_namespace]["serialization_alias"] = serialization_alias
 
     # Populate docstring from the field's `description` argument.
     if not attr.docstring and (description_expr := kwargs.get("description")):
@@ -228,7 +239,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, show_alias: bool = False) -> None:
+def _process_class(cls: Class, *, processed: set[str], schema: bool = False) -> None:
     """Finalize the Pydantic model data."""
     if cls.canonical_path in processed:
         return
@@ -263,20 +274,14 @@ def _process_class(cls: Class, *, processed: set[str], schema: bool = False, sho
     for member in cls.all_members.values():
         kind = member.kind
         if kind is Kind.ATTRIBUTE:
-            _process_attribute(member, cls, processed=processed, show_alias=show_alias)  # ty: ignore[invalid-argument-type]
+            _process_attribute(member, cls, processed=processed)  # 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, show_alias=show_alias)  # ty: ignore[invalid-argument-type]
+            _process_class(member, processed=processed, schema=schema)  # ty: ignore[invalid-argument-type]
 
 
-def _process_module(
-    mod: Module,
-    *,
-    processed: set[str],
-    schema: bool = False,
-    show_alias: bool = False,
-) -> None:
+def _process_module(mod: Module, *, processed: set[str], schema: bool = False) -> None:
     """Handle Pydantic models in a module."""
     if mod.canonical_path in processed:
         return
@@ -285,9 +290,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, show_alias=show_alias)
+            _process_class(cls, processed=processed, schema=schema)
 
     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, show_alias=show_alias)
+            _process_module(submodule, processed=processed, schema=schema)

src/griffe_pydantic/_internal/extension.py

@@ -0,0 +1,15 @@
+{% extends "_base/attribute.html.jinja" %}
+
+{% block contents scoped %}
+  {% if attribute.extra.griffe_pydantic.validation_alias or attribute.extra.griffe_pydantic.serialization_alias %}
+    <ul>
+      {% if attribute.extra.griffe_pydantic.validation_alias %}
+        <li>Input / Validation alias: <code>{{ attribute.extra.griffe_pydantic.validation_alias }}</code></li>
+      {% endif %}
+      {% if attribute.extra.griffe_pydantic.serialization_alias %}
+        <li>Output / Serialization alias: <code>{{ attribute.extra.griffe_pydantic.serialization_alias }}</code></li>
+      {% endif %}
+    </ul>
+  {% endif %}
+  {{ super() }}
+{% endblock contents %}