Help with griffe-pydantic: Validators and Config not grouping as expected

[hansen-young]

Hello! 👋

I'm currently trying to integrate griffe-pydantic with mkdocstrings to document my Pydantic classes. I’m aiming for that clean, categorized look shown in the official documentation (where Validators and Config have their own distinct sections and badges).

The Goal:
I’m trying to achieve this layout:

The Current Result:
Unfortunately, mine is rendering as a standard list of attributes and methods without the Pydantic-specific grouping:

Versions:

mkdocs                             1.6.1
mkdocs-autorefs                    1.4.4
mkdocs-get-deps                    0.2.0
mkdocs-material                    9.7.1
mkdocs-material-extensions         1.3.1
mkdocs-static-i18n                 1.3.0
mkdocstrings                       1.0.3
mkdocstrings-python                2.0.2
griffe                             2.0.0
griffe-pydantic                    1.3.0
griffecli                          2.0.0
griffelib                          2.0.0

My Configuration (mkdocs.yml):
I've enabled group_by_category and added the extension, but I might be missing a specific flag.

- mkdocstrings: 
    default_handler: python
    handlers:
      python:
        paths: ["app"]
        inventories:
          - https://docs.python.org/3/objects.inv
          - https://docs.pydantic.dev/latest/objects.inv
        options:
          show_source: false
          show_root_full_path: false
          show_root_heading: true
          # show_signature: false
          show_signature_annotations: true
          modernize_annotations: true
          show_labels: true
          show_symbol_type_heading: true
          show_symbol_type_toc: true
          show_if_no_docstring: true
          show_category_heading: true
          group_by_category: true
          members_order: source
          docstring_style: numpy
          extensions:
            - griffe_pydantic:
                schema: true

Minimal Example

from pydantic import BaseModel, ConfigDict, field_validator

class ExampleModel(BaseModel):
    """Example Model"""

    model_config = ConfigDict(frozen=False)

    field_without_validator: str
    """Field 1"""

    field_with_validator: int
    """Field 2"""

    @field_validator("field_with_validator")
    @classmethod
    def age_must_be_positive(cls, v: int):
        """Validate positive integer"""
        if v <= 0:
            raise ValueError("Must be positive")
        return v

I suspect I might be missing some setttings or perhaps a specific version of griffe, but any guidance would be greatly appreciated! Thanks in advance for the help!

[pawamoy]

I cannot reproduce the issue you describe 😕 And I don't see anything wrong in this setup.

Feel free to open a bug report with a minimal reproduction example packed in a zip file 🙂

[hansen-young]

Hi @pawamoy,

Thanks for taking the time to look into this! After further investigation, I finally tracked down the cause. It wasn't a configuration error, but rather a side effect of how the extension handles modules that fail to import.

The Issue:
If a module contains a runtime error (like an undefined variable) or (in my previous case) a Pydantic BaseSettings class fails to instantiate (e.g., due to missing environment variables), the module fails to be fully imported/resolved.

In these cases, griffe still successfully performs static analysis and renders the class as a standard Python object, but the griffe-pydantic extension doesn't "kick in." This results in the standard attributes list instead of the Pydantic-specific groupings (Validators, Config, etc.).

sample.zip

In my attached example, if I uncomment either the error or the Settings() instantiation (without the ENV var set), the Pydantic-specific formatting disappears in the docs. Once resolved/commented out, the formatting returns.

I'll keep this in mind for my workflow, but I wanted to share this in case it helps others who see the standard layout and wonder why the extension isn't activating.

Thanks again!

[pawamoy]

Ah, thanks for the investigation! In our static analyzer, we indeed only catch ImportError exceptions, not RuntimeError or other ones. I haven't checked the whole call chain, so I'm not sure how high these error bubble up. Building your docs in verbose mode might output some useful logs.

[hansen-young]

I see this in the log when running in verbose mode

DEBUG - griffe_pydantic: Could not import class main.ExampleModel for JSON schema

Since this is currently logged at the DEBUG level, the build appears "successful" to the user, but the Pydantic-specific formatting is silently missing. This makes it quite difficult to troubleshoot without knowing to check verbose logs. If you’re open to it, changing this specific log from DEBUG to WARNING might be a huge help for visibility.

I'll mark this as resolved for now. Thanks again!