refactor: use custom template

Author: watermarkhu

examples/model_noserialize.py

@@ -20,5 +20,5 @@ class UserModel(BaseModel):
     email_address: str
     """User's email address."""
 
-    is_active: bool = Field(default=TRUE)
+    is_active: bool = Field(default=True)
     """Whether the user is active, serialized as 'active'."""

src/griffe_pydantic/_internal/common.py

@@ -29,36 +29,7 @@
 
 
 def _model_fields(cls: Class) -> dict[str, Attribute]:
-    """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
+    return {name: attr for name, attr in cls.all_members.items() if "pydantic-field" in attr.labels}  # ty: ignore[invalid-return-type]
 
 
 def _model_validators(cls: Class) -> dict[str, Function]:
@@ -77,15 +48,13 @@ def _json_schema(model: type[BaseModel]) -> str:
     return json.dumps(model.model_json_schema(), indent=2)
 
 
-def _process_class(cls: Class, *, serialize_by_alias: bool = False) -> None:
+def _process_class(cls: Class) -> 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

@@ -20,7 +20,14 @@
 _logger = get_logger("griffe_pydantic")
 
 
-def _process_attribute(obj: Any, attr: Attribute, cls: Class, *, processed: set[str]) -> None:
+def _process_attribute(
+    obj: Any,
+    attr: Attribute,
+    cls: Class,
+    *,
+    processed: set[str],
+    serialize_by_alias: bool = False,
+) -> None:
     """Handle Pydantic fields."""
     from pydantic.fields import FieldInfo  # noqa: PLC0415
 
@@ -43,9 +50,9 @@ def _process_attribute(obj: Any, attr: Attribute, cls: Class, *, processed: set[
     attr.extra[common._self_namespace]["constraints"] = constraints
 
     # Store serialization_alias if present
-    if obj.serialization_alias:
+    if serialize_by_alias and obj.serialization_alias:
         attr.extra[common._self_namespace]["serialization_alias"] = obj.serialization_alias
-        attr.name = obj.serialization_alias
+        attr.extra[common._mkdocstrings_namespace]["template"] = "pydantic_attribute_alias.html.jinja"
 
     # Populate docstring from the field's `description` argument.
     if not attr.docstring and (docstring := obj.description):
@@ -70,7 +77,7 @@ def _process_class(
     serialize_by_alias: bool = False,
 ) -> None:
     """Detect and prepare Pydantic models."""
-    common._process_class(cls, serialize_by_alias=serialize_by_alias)
+    common._process_class(cls)
     if schema:
         try:
             cls.extra[common._self_namespace]["schema"] = common._json_schema(obj)  # ty: ignore[invalid-argument-type]
@@ -80,25 +87,12 @@ def _process_class(
     for member in cls.all_members.values():
         kind = member.kind
         if kind is Kind.ATTRIBUTE:
-            _process_attribute(getattr(obj, member.name), member, cls, processed=processed)  # ty: ignore[invalid-argument-type]
+            _process_attribute(
+                getattr(obj, member.name),
+                member,  # ty: ignore[invalid-argument-type]
+                cls,
+                processed=processed,
+                serialize_by_alias=serialize_by_alias,
+            )
         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/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]) -> None:
+def _process_attribute(attr: Attribute, cls: Class, *, processed: set[str], serialize_by_alias: bool = False) -> None:
     """Handle Pydantic fields."""
     if attr.canonical_path in processed:
         return
@@ -197,13 +197,14 @@ def _process_attribute(attr: Attribute, cls: Class, *, processed: set[str]) -> N
     attr.extra[common._self_namespace]["constraints"] = constraints
 
     # Store serialization_alias if present
-    if serialization_alias := kwargs.get("serialization_alias"):
+    if serialize_by_alias and (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
-            attr.name = attr.extra[common._self_namespace]["serialization_alias"]
+            # Set the attribute template to the custom template, which will use the serialization_alias instead of the attribute name.
+            attr.extra[common._mkdocstrings_namespace]["template"] = "pydantic_attribute_alias.html.jinja"
         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}'")
@@ -241,7 +242,7 @@ def _process_class(cls: Class, *, processed: set[str], schema: bool = False, ser
 
     processed.add(cls.canonical_path)
 
-    common._process_class(cls, serialize_by_alias=serialize_by_alias)
+    common._process_class(cls)
 
     if schema:
         import_path: Path | list[Path] = cls.package.filepath
@@ -266,7 +267,7 @@ 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)  # ty: ignore[invalid-argument-type]
+            _process_attribute(member, cls, processed=processed, serialize_by_alias=serialize_by_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:

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

@@ -0,0 +1,130 @@
+{#- Template for Python attributes.
+
+This template renders a Python attribute (or variable).
+This can be a module attribute or a class attribute.
+
+Context:
+  attribute (griffe.Attribute): The attribute to render.
+  root (bool): Whether this is the root object, injected with `:::` in a Markdown page.
+  heading_level (int): The HTML heading level to use.
+  config (dict): The configuration options.
+-#}
+
+{% block logs scoped %}
+  {#- Logging block.
+
+  This block can be used to log debug messages, deprecation messages, warnings, etc.
+  -#}
+  {{ log.debug("Rendering " + attribute.path) }}
+{% endblock logs %}
+
+<div class="doc doc-object doc-attribute">
+  {% with obj = attribute, html_id = attribute.path %}
+
+    {% if root %}
+      {% set show_full_path = config.show_root_full_path %}
+      {% set root_members = True %}
+    {% elif root_members %}
+      {% set show_full_path = config.show_root_members_full_path or config.show_object_full_path %}
+      {% set root_members = False %}
+    {% else %}
+      {% set show_full_path = config.show_object_full_path %}
+    {% endif %}
+
+    {# {% 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 %}
+
+    {% if not root or config.show_root_heading %}
+      {% filter heading(
+          heading_level,
+          role="data" if attribute.parent.kind.value == "module" else "attr",
+          id=html_id,
+          class="doc doc-heading",
+          toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute.name),
+          skip_inventory=config.skip_local_inventory,
+        ) %}
+
+        {% block heading scoped %}
+          {#- Heading block.
+
+          This block renders the heading for the attribute.
+          -#}
+          {% if config.show_symbol_type_heading %}<code class="doc-symbol doc-symbol-heading doc-symbol-attribute"></code>{% endif %}
+          {% if config.heading and root %}
+            {{ config.heading }}
+          {% elif config.separate_signature %}
+            <span class="doc doc-object-name doc-attribute-name">{{ attribute_name }}</span>
+          {% else %}
+            {%+ filter highlight(language="python", inline=True) %}
+              {{ attribute_name }}{% if attribute.annotation and config.show_signature_annotations %}: {{ attribute.annotation }}{% endif %}
+              {% if config.show_attribute_values and attribute.value %} = {{ attribute.value }}{% endif %}
+            {% endfilter %}
+          {% endif %}
+        {% endblock heading %}
+
+        {% block labels scoped %}
+          {#- Labels block.
+
+          This block renders the labels for the attribute.
+          -#}
+          {% with labels = attribute.labels %}
+            {% include "labels.html.jinja" with context %}
+          {% endwith %}
+        {% endblock labels %}
+
+      {% endfilter %}
+
+      {% block signature scoped %}
+        {#- Signature block.
+
+        This block renders the signature for the attribute.
+        -#}
+        {% if config.separate_signature %}
+          {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs, show_value=config.show_attribute_values) %}
+            {{ attribute.name }}
+          {% endfilter %}
+        {% endif %}
+      {% endblock signature %}
+
+    {% else %}
+
+      {% if config.show_root_toc_entry %}
+        {% filter heading(heading_level,
+            role="data" if attribute.parent.kind.value == "module" else "attr",
+            id=html_id,
+            toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute_name),
+            hidden=True,
+            skip_inventory=config.skip_local_inventory,
+          ) %}
+        {% endfilter %}
+      {% endif %}
+      {% set heading_level = heading_level - 1 %}
+    {% endif %}
+
+    <div class="doc doc-contents {% if root %}first{% endif %}">
+      {% block contents scoped %}
+        {#- Contents block.
+
+        This block renders the contents of the attribute.
+        It contains other blocks that users can override.
+        Overriding the contents block allows to rearrange the order of the blocks.
+        -#}
+        {% block docstring scoped %}
+          {#- Docstring block.
+
+          This block renders the docstring for the attribute.
+          -#}
+          {% with docstring_sections = attribute.docstring.parsed %}
+            {% include "docstring.html.jinja" with context %}
+          {% endwith %}
+        {% endblock docstring %}
+
+        {% if config.backlinks %}
+          <backlinks identifier="{{ html_id }}" handler="python" />
+        {% endif %}
+      {% endblock contents %}
+    </div>
+
+  {% endwith %}
+</div>

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

@@ -0,0 +1 @@
+{% extends "_base/pydantic_attribute_alias.html.jinja" %}