"""Load schema example payloads from JSON files."""

from functools import lru_cache
from importlib.resources import files
import json
from typing import Any


@lru_cache(maxsize=None)
def with_example(name: str) -> dict[str, Any]:
    """
    Helper utility that will pull JSON examples from the `examples` directory
    and return them as dictionaries. This is used to populate the `json_schema_extra`
    field of our Pydantic models, which allows the examples to be included in the
    generated OpenAPI schema.

    Returns:
        A dictionary containing the example payload for the specified schema.
    """
    path = files("contributor.api.schemas").joinpath("examples", f"{name}.json")
    payload = json.loads(path.read_text(encoding="utf-8"))
    if not isinstance(payload, dict):
        raise TypeError(f"Schema example '{name}' must be a JSON object.")
    return payload