refactor: Move code to internal API, update docs accordingly

Author: pawamoy

docs/reference/griffe_pydantic.md

@@ -0,0 +1,3 @@
+# ::: griffe_pydantic
+    options:
+        show_submodules: true

mkdocs.yml

@@ -19,8 +19,7 @@ nav:
   - Changelog: changelog.md
   - Credits: credits.md
   - License: license.md
-# defer to gen-files + literate-nav
-- API reference: reference/
+- API reference: reference/griffe_pydantic.md
 - Development:
   - Contributing: contributing.md
   - Code of Conduct: code_of_conduct.md
@@ -109,11 +108,6 @@ plugins:
 - search
 - markdown-exec
 - section-index
-- gen-files:
-    scripts:
-    - scripts/gen_api_ref.py
-- literate-nav:
-    nav_file: SUMMARY.txt
 - coverage
 - mkdocstrings:
     handlers:

pyproject.toml

@@ -97,9 +97,7 @@ ci = [
     "markdown-exec>=1.8",
     "mkdocs>=1.6",
     "mkdocs-coverage>=1.0",
-    "mkdocs-gen-files>=0.5",
     "mkdocs-git-revision-date-localized-plugin>=1.2",
-    "mkdocs-literate-nav>=0.6",
     "mkdocs-llmstxt>=0.1",
     "mkdocs-material>=9.5",
     "mkdocs-minify-plugin>=0.8",

scripts/make.py

@@ -14,7 +14,7 @@
     from collections.abc import Iterator
 
 
-PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.9 3.10 3.11 3.12 3.13 3.14").split()
+PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.9 3.10 3.11 3.12 3.13").split()
 
 
 def shell(cmd: str, *, capture_output: bool = False, **kwargs: Any) -> str | None:

src/griffe_pydantic/__init__.py

@@ -7,7 +7,7 @@
 
 from pathlib import Path
 
-from griffe_pydantic.extension import PydanticExtension
+from griffe_pydantic._internal.extension import PydanticExtension
 
 
 def get_templates_path() -> Path:

src/griffe_pydantic/_internal/common.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+from functools import partial
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from griffe import Attribute, Class, Function
+    from pydantic import BaseModel
+
+_self_namespace = "griffe_pydantic"
+_mkdocstrings_namespace = "mkdocstrings"
+
+_field_constraints = {
+    "gt",
+    "ge",
+    "lt",
+    "le",
+    "multiple_of",
+    "min_length",
+    "max_length",
+    "pattern",
+    "allow_inf_nan",
+    "max_digits",
+    "decimal_place",
+}
+
+
+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}  # type: ignore[misc]
+
+
+def _model_validators(cls: Class) -> dict[str, Function]:
+    return {name: func for name, func in cls.all_members.items() if "pydantic-validator" in func.labels}  # type: ignore[misc]
+
+
+def _json_schema(model: type[BaseModel]) -> str:
+    """Produce a model schema as JSON.
+
+    Parameters:
+        model: A Pydantic model.
+
+    Returns:
+        A schema as JSON.
+    """
+    return json.dumps(model.model_json_schema(), indent=2)
+
+
+def _process_class(cls: Class) -> None:
+    """Set metadata on a Pydantic model.
+
+    Parameters:
+        cls: The Griffe class representing the Pydantic model.
+    """
+    cls.labels.add("pydantic-model")
+    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"
+
+
+def _process_function(func: Function, cls: Class, fields: Sequence[str]) -> None:
+    """Set metadata on a Pydantic validator.
+
+    Parameters:
+        cls: A Griffe function representing the Pydantic validator.
+    """
+    func.labels = {"pydantic-validator"}
+    targets = [cls.all_members[field] for field in fields]
+
+    func.extra[_self_namespace].setdefault("targets", [])
+    func.extra[_self_namespace]["targets"].extend(targets)
+    for target in targets:
+        target.extra[_self_namespace].setdefault("validators", [])
+        target.extra[_self_namespace]["validators"].append(func)

src/griffe_pydantic/_internal/dynamic.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from griffe import (
+    Attribute,
+    Class,
+    Docstring,
+    Function,
+    Kind,
+    get_logger,
+)
+from pydantic.fields import FieldInfo
+
+from griffe_pydantic._internal import common
+
+_logger = get_logger(__name__)
+
+
+def _process_attribute(obj: Any, attr: Attribute, cls: Class, *, processed: set[str]) -> None:
+    """Handle Pydantic fields."""
+    if attr.canonical_path in processed:
+        return
+    processed.add(attr.canonical_path)
+    if attr.name == "model_config":
+        cls.extra[common._self_namespace]["config"] = obj
+        return
+
+    if not isinstance(obj, FieldInfo):
+        return
+
+    attr.labels = {"pydantic-field"}
+    attr.value = obj.default
+    constraints = {}
+    for constraint in common._field_constraints:
+        if (value := getattr(obj, constraint, None)) is not None:
+            constraints[constraint] = value
+    attr.extra[common._self_namespace]["constraints"] = constraints
+
+    # Populate docstring from the field's `description` argument.
+    if not attr.docstring and (docstring := obj.description):
+        attr.docstring = Docstring(docstring, parent=attr)
+
+
+def _process_function(obj: Callable, func: Function, cls: Class, *, processed: set[str]) -> None:
+    """Handle Pydantic field validators."""
+    if func.canonical_path in processed:
+        return
+    processed.add(func.canonical_path)
+    if dec_info := getattr(obj, "decorator_info", None):
+        common._process_function(func, cls, dec_info.fields)
+
+
+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:
+        cls.extra[common._self_namespace]["schema"] = common._json_schema(obj)
+    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)  # type: ignore[arg-type]
+        elif kind is Kind.FUNCTION:
+            _process_function(getattr(obj, member.name), member, cls, processed=processed)  # type: ignore[arg-type]

src/griffe_pydantic/_internal/extension.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import ast
+from typing import TYPE_CHECKING, Any
+
+from griffe import (
+    Class,
+    Extension,
+    Module,
+    get_logger,
+)
+
+from griffe_pydantic._internal import dynamic, static
+
+if TYPE_CHECKING:
+    from griffe import ObjectNode
+
+
+_logger = get_logger(__name__)
+
+
+class PydanticExtension(Extension):
+    """Griffe extension for Pydantic."""
+
+    def __init__(self, *, schema: bool = False) -> None:
+        """Initialize the extension.
+
+        Parameters:
+            schema: Whether to compute and store the JSON schema of models.
+        """
+        super().__init__()
+        self._schema = schema
+        self._processed: set[str] = set()
+        self._recorded: list[tuple[ObjectNode, Class]] = []
+
+    def on_package_loaded(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)
+
+    def on_class_instance(self, *, node: ast.AST | ObjectNode, cls: Class, **kwargs: Any) -> None:  # noqa: ARG002
+        """Detect and prepare Pydantic models."""
+        # Prevent running during static analysis.
+        if isinstance(node, ast.AST):
+            return
+
+        try:
+            import pydantic
+        except ImportError:
+            _logger.warning("could not import pydantic - models will not be detected")
+            return
+
+        if issubclass(node.obj, pydantic.BaseModel):
+            self._recorded.append((node, cls))