π The fast, Pythonic way to build MCP servers and clients.
Build client schema types with create_model and bounded caches (#5413)
Jeremiah Lowin35bb8b9e0785
diff --git a/fastmcp_slim/fastmcp/client/mixins/tools.py b/fastmcp_slim/fastmcp/client/mixins/tools.pyindex 1a7ed104a..10043d7cc 100644--- a/fastmcp_slim/fastmcp/client/mixins/tools.py+++ b/fastmcp_slim/fastmcp/client/mixins/tools.py@@ -16,10 +16,9 @@ from fastmcp.client.progress import ProgressHandlerfrom fastmcp.client.telemetry import client_spanfrom fastmcp.exceptions import ToolErrorfrom fastmcp.telemetry import inject_trace_context-from fastmcp.utilities.json_schema_type import json_schema_to_type+from fastmcp.utilities.json_schema_type import json_schema_to_type_adapterfrom fastmcp.utilities.logging import get_loggerfrom fastmcp.utilities.timeout import normalize_timeout_to_seconds-from fastmcp.utilities.types import get_cached_typeadapterlogger = get_logger(__name__)@@ -405,8 +404,7 @@ async def _parse_call_tool_result(output_schema = output_schema.get("properties", {}).get("result", output_schema)- output_type = json_schema_to_type(output_schema)- type_adapter = get_cached_typeadapter(output_type)+ type_adapter = json_schema_to_type_adapter(output_schema)data = type_adapter.validate_python(structured_content)else:data = structured_contentdiff --git a/fastmcp_slim/fastmcp/utilities/json_schema_type.py b/fastmcp_slim/fastmcp/utilities/json_schema_type.pyindex a16fa65a8..8aaf58988 100644--- a/fastmcp_slim/fastmcp/utilities/json_schema_type.py+++ b/fastmcp_slim/fastmcp/utilities/json_schema_type.py@@ -57,17 +57,22 @@ import jsonimport keywordimport reimport sys+import threadingimport warnings-from collections.abc import Callable, Mapping+from collections import OrderedDict+from collections.abc import Callable, Hashable, Mapping+from contextvars import ContextVarfrom copy import deepcopy-from dataclasses import MISSING, field, make_dataclass+from dataclasses import MISSING, dataclass, field, make_dataclassfrom datetime import date, datetimefrom functools import lru_cachefrom typing import (Annotated,Any,ForwardRef,+ Generic,Literal,+ TypeVar,Union,cast,)@@ -82,8 +87,10 @@ from pydantic import (Json,StringConstraints,TypeAdapter,+ create_model,model_validator,)+from pydantic.fields import FieldInfofrom pydantic_core import SchemaError as _PydanticSchemaErrorfrom typing_extensions import NotRequired, TypedDict@@ -127,7 +134,86 @@ FORMAT_TYPES: dict[str, Any] = {"json": Json,}-_classes: dict[tuple[str, Any], type | None] = {}+_V = TypeVar("_V")+++class _LRUCache(Generic[_V]):+ """Least recently used cache bounded by entry count and total weight.++ Each entry's weight is the serialized size of the whole schema the+ conversion started from. A generated class refers to the classes of its+ properties and keeps the schema it was built from, so it retains as much+ as the root schema describes. Charging that size keeps the total memory+ held by the cache within `max_weight`. An entry heavier than `max_weight`+ is not stored.+ """++ def __init__(self, max_entries: int, max_weight: int) -> None:+ self.max_entries = max_entries+ self.max_weight = max_weight+ self._items: OrderedDict[Hashable, tuple[_V, int]] = OrderedDict()+ self._weight = 0+ self._lock = threading.Lock()++ def get(self, key: Hashable) -> _V | None:+ with self._lock:+ item = self._items.get(key)+ if item is None:+ return None+ self._items.move_to_end(key)+ return item[0]++ def put(self, key: Hashable, value: _V, weight: int) -> None:+ with self._lock:+ previous = self._items.pop(key, None)+ if previous is not None:+ self._weight -= previous[1]+ if weight > self.max_weight:+ return+ self._items[key] = (value, weight)+ self._weight += weight+ while len(self._items) > self.max_entries or self._weight > self.max_weight:+ _, (_, evicted_weight) = self._items.popitem(last=False)+ self._weight -= evicted_weight++ def clear(self) -> None:+ with self._lock:+ self._items.clear()+ self._weight = 0++ def __len__(self) -> int:+ return len(self._items)+++# Generated classes keyed by (schema hash + root schema hash, class name). Each+# class is weighted by the size of its root schema, so a conversion whose root+# is larger than the weight limit adds nothing to the cache.+_classes: _LRUCache[type] = _LRUCache(max_entries=5000, max_weight=4_000_000)+# TypeAdapters for whole schemas, keyed by schema hash. They hold their+# classes, so they are bounded the same way.+_adapters: _LRUCache[TypeAdapter[Any]] = _LRUCache(+ max_entries=1000, max_weight=4_000_000+)++# Limits on a single conversion. Depth counts nested schemas and `$ref` hops;+# steps count every schema visited.+_MAX_CONVERSION_DEPTH = 64+_MAX_CONVERSION_STEPS = 50_000+++@dataclass+class _Conversion:+ """State for one `json_schema_to_type` call."""++ root_hash: str+ root_size: int+ resolved_refs: dict[str, Any] = field(default_factory=dict)+ building: set[tuple[str, str]] = field(default_factory=set)+ depth: int = 0+ steps: int = 0+++_conversion: ContextVar[_Conversion] = ContextVar("json_schema_conversion")class JSONSchema(TypedDict):@@ -180,7 +266,8 @@ def json_schema_to_type(A Python type (typically a dataclass for objects) with Pydantic validationRaises:- ValueError: If a name is provided for a non-object schema+ ValueError: If a name is provided for a non-object schema, or if the+ schema is too deeply nested or too large to convert.Examples:Create a dataclass from an object schema:@@ -232,17 +319,41 @@ def json_schema_to_type(# so that downstream json.dumps/hashing and default values work correctly.schema = _normalize_yaml_types(schema)- # Always use the top-level schema for references- if schema.get("type") == "object":- return _object_schema_to_type(schema, schemas=schema, name=name)- elif name:- raise ValueError(f"Can not apply name to non-object schema: {name}")- result = _schema_to_type(schema, schemas=schema)- return result # type: ignore[return-value] # ty:ignore[invalid-return-type]+ root_hash, root_size = _schema_digest(schema)+ token = _conversion.set(_Conversion(root_hash=root_hash, root_size=root_size))+ try:+ # Always use the top-level schema for references+ if schema.get("type") == "object":+ return _object_schema_to_type(schema, schemas=schema, name=name)+ elif name:+ raise ValueError(f"Can not apply name to non-object schema: {name}")+ result = _schema_to_type(schema, schemas=schema)+ return result # type: ignore[return-value] # ty:ignore[invalid-return-type]+ finally:+ _conversion.reset(token)+++def json_schema_to_type_adapter(schema: Mapping[str, Any] | bool) -> TypeAdapter[Any]:+ """Return a cached `TypeAdapter` for `json_schema_to_type(schema)`.++ Adapters are cached by schema content in a bounded cache, so the classes+ they hold are released when they are evicted.+ """+ key, size = _schema_digest(schema)+ adapter = _adapters.get(key)+ if adapter is None:+ adapter = TypeAdapter(json_schema_to_type(schema))+ _adapters.put(key, adapter, size)+ return adapterdef _hash_schema(schema: Mapping[str, Any]) -> str:- """Generate a deterministic hash for schema caching.+ """Generate a deterministic hash for schema caching."""+ return _schema_digest(schema)[0]+++def _schema_digest(schema: Mapping[str, Any] | bool) -> tuple[str, int]:+ """Return a deterministic hash of the schema and its serialized size.Handles non-JSON-native types (datetime, date, bool keys) that canappear in schemas loaded from YAML, which auto-parses date strings.@@ -254,7 +365,8 @@ def _hash_schema(schema: Mapping[str, Any]) -> str:except TypeError:# Mixed key types (bool + str) can't be sorted; fall backraw = json.dumps(schema, default=str)- return hashlib.sha256(raw.encode()).hexdigest()+ encoded = raw.encode()+ return hashlib.sha256(encoded).hexdigest(), len(encoded)def _resolve_ref(ref: str, schemas: Mapping[str, Any]) -> Mapping[str, Any]:@@ -489,7 +601,25 @@ def _schema_to_type(schemas: Mapping[str, Any],resolving_refs: frozenset[str] = frozenset(),) -> type | ForwardRef:- """Convert schema to appropriate Python type."""+ """Convert schema to appropriate Python type, within the conversion limits."""+ conversion = _conversion.get()+ conversion.steps += 1+ if conversion.depth >= _MAX_CONVERSION_DEPTH:+ raise ValueError("JSON schema is too deeply nested to convert")+ if conversion.steps > _MAX_CONVERSION_STEPS:+ raise ValueError("JSON schema is too large to convert")+ conversion.depth += 1+ try:+ return _convert_schema(schema, schemas, resolving_refs)+ finally:+ conversion.depth -= 1+++def _convert_schema(+ schema: Mapping[str, Any] | bool,+ schemas: Mapping[str, Any],+ resolving_refs: frozenset[str],+) -> type | ForwardRef:# Boolean schemas are valid in JSON Schema draft-06+:# true means "any value is valid" (equivalent to {}),# false means "no value is valid" (unsatisfiable).@@ -509,7 +639,7 @@ def _schema_to_type(ref = schema["$ref"]# Handle self-referenceif ref == "#":- return ForwardRef(schema.get("title", "Root"))+ return ForwardRef(_sanitize_name(schema.get("title", "Root")))if ref in resolving_refs:resolved = _resolve_ref(ref, schemas)if isinstance(resolved, Mapping) and (@@ -517,9 +647,14 @@ def _schema_to_type():return _schema_to_type(resolved, schemas, resolving_refs)return Any- return _schema_to_type(- _resolve_ref(ref, schemas), schemas, resolving_refs | {ref}- )+ # Convert each reference once per conversion, so a definition shared+ # by many references is not expanded again for every path to it.+ resolved_refs = _conversion.get().resolved_refs+ if ref not in resolved_refs:+ resolved_refs[ref] = _schema_to_type(+ _resolve_ref(ref, schemas), schemas, resolving_refs | {ref}+ )+ return resolved_refs[ref]if "const" in schema:return Literal[schema["const"]] # type: ignore@@ -542,7 +677,7 @@ def _schema_to_type(return type(None)elif len(types) == 1:if has_null:- return types[0] | None # type: ignore+ return Union[types[0], type(None)] # type: ignore # noqa: UP007else:return types[0]else:@@ -566,7 +701,7 @@ def _schema_to_type(types = [t for t in types if t is not type(None)]if has_null:if len(types) == 1:- return types[0] | None # type: ignore+ return Union[types[0], type(None)] # type: ignore # noqa: UP007else:return Union[(*types, type(None))] # type: ignorereturn Union[tuple(types)] # type: ignore # noqa: UP007@@ -595,6 +730,58 @@ def _sanitize_name(name: str) -> str:return cleaned+_BASE_MODEL_MEMBERS = frozenset(dir(BaseModel))+++def _is_reserved_field_name(name: str) -> bool:+ """Whether a property name would act as a class or Pydantic control name.++ Leading underscores cover dunders, Pydantic private attributes, and the+ `create_model` keyword arguments. Members in the `model_` namespace are+ Pydantic's own API.+ """+ return name.startswith("_") or (+ name.startswith("model_") and name in _BASE_MODEL_MEMBERS+ )+++def safe_create_model(+ name: str,+ field_definitions: Mapping[str, tuple[Any, Any]],+ *,+ config: ConfigDict | None = None,+) -> type[BaseModel]:+ """Create a Pydantic model whose field names come from untrusted input.++ Each property name only ever becomes a field. A reserved name is stored+ under a generated field name with the original name as its alias, so it+ validates and dumps (with `by_alias=True`) under its original name.++ Args:+ name: The model class name.+ field_definitions: Maps each property name to `(annotation, default)`,+ where `default` may be a `FieldInfo` or `...` for required fields.+ config: Optional model configuration.+ """+ fields: dict[str, Any] = {}+ for prop_name, (annotation, default) in field_definitions.items():+ field_name = prop_name+ if _is_reserved_field_name(prop_name):+ base = f"field_{_sanitize_name(prop_name).lstrip('_')}"+ field_name = base+ counter = 2+ while field_name in fields or field_name in field_definitions:+ field_name = f"{base}_{counter}"+ counter += 1+ if isinstance(default, FieldInfo):+ annotation = Annotated[annotation, default]+ default = Field(alias=prop_name)+ else:+ default = Field(default=default, alias=prop_name)+ fields[field_name] = (annotation, default)+ return create_model(name, __config__=config, **fields)++def _get_default_value(schema: dict[str, Any],prop_name: str,@@ -635,58 +822,58 @@ def _create_pydantic_model(if name is None:raise ValueError("Name is required")sanitized_name = _sanitize_name(name)+ conversion = _conversion.get()schema_hash = _hash_schema(schema)- cache_key = (schema_hash, sanitized_name)+ cache_key = (schema_hash + conversion.root_hash, sanitized_name)# Return existing class if already built- if cache_key in _classes:- existing = _classes[cache_key]- if existing is None:- return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]+ existing = _classes.get(cache_key)+ if existing is not None:return existing+ # A recursive reference to a class that is still being built+ if cache_key in conversion.building:+ return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]++ conversion.building.add(cache_key)+ try:+ cls = _build_pydantic_model(+ schema, sanitized_name, schemas or {}, resolving_refs+ )+ finally:+ conversion.building.discard(cache_key)+ _classes.put(cache_key, cls, conversion.root_size)+ return cls- # Place placeholder for recursive references- _classes[cache_key] = None+def _build_pydantic_model(+ schema: Mapping[str, Any],+ name: str,+ schemas: Mapping[str, Any],+ resolving_refs: frozenset[str],+) -> type:properties = schema.get("properties", {})required = schema.get("required", [])- # Build field annotations and defaults- annotations = {}- defaults = {}-+ field_definitions: dict[str, tuple[Any, Any]] = {}for prop_name, prop_schema in properties.items():# Boolean schemas (JSON Schema draft-06+): resolve type directly,# then use an empty dict for .get() calls below.if isinstance(prop_schema, bool):- field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)+ field_type = _schema_to_type(prop_schema, schemas, resolving_refs)prop_schema = {}else:- field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)+ field_type = _schema_to_type(prop_schema, schemas, resolving_refs)# Handle defaultsdefault_value = prop_schema.get("default", MISSING)if default_value is not MISSING:- defaults[prop_name] = default_value- annotations[prop_name] = field_type+ field_definitions[prop_name] = (field_type, default_value)elif prop_name in required:- annotations[prop_name] = field_type+ field_definitions[prop_name] = (field_type, ...)else:- annotations[prop_name] = Union[field_type, type(None)] # type: ignore[misc] # noqa: UP007 # ty:ignore[invalid-type-form]- defaults[prop_name] = None-- # Create Pydantic model class- cls_dict = {- "__annotations__": annotations,- "model_config": ConfigDict(extra="allow"),- **defaults,- }+ field_definitions[prop_name] = (Union[field_type, type(None)], None) # type: ignore[misc] # noqa: UP007 # ty:ignore[invalid-type-form]- cls = type(sanitized_name, (BaseModel,), cls_dict)-- # Store completed class- _classes[cache_key] = cls- return cls+ return safe_create_model(name, field_definitions, config=ConfigDict(extra="allow"))def _create_dataclass(@@ -701,27 +888,43 @@ def _create_dataclass(if name is None:raise ValueError("Name is required")sanitized_name = _sanitize_name(name)+ conversion = _conversion.get()schema_hash = _hash_schema(schema)- cache_key = (schema_hash, sanitized_name)- original_schema = dict(schema) # Store copy for validator+ cache_key = (schema_hash + conversion.root_hash, sanitized_name)# Return existing class if already built- if cache_key in _classes:- existing = _classes[cache_key]- if existing is None:- return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]+ existing = _classes.get(cache_key)+ if existing is not None:return existing+ # A recursive reference to a class that is still being built+ if cache_key in conversion.building:+ return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]++ conversion.building.add(cache_key)+ try:+ cls = _build_dataclass(schema, sanitized_name, schemas or {}, resolving_refs)+ finally:+ conversion.building.discard(cache_key)+ if isinstance(cls, type):+ _classes.put(cache_key, cls, conversion.root_size)+ return cls- # Place placeholder for recursive references- _classes[cache_key] = None++def _build_dataclass(+ schema: Mapping[str, Any],+ sanitized_name: str,+ schemas: Mapping[str, Any],+ resolving_refs: frozenset[str],+) -> Any:+ original_schema = dict(schema) # Store copy for validatorif "$ref" in schema:ref = schema["$ref"]if ref == "#":- return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]+ return ForwardRef(sanitized_name)if ref in resolving_refs:return Any- schema = _resolve_ref(ref, schemas or {})+ schema = _resolve_ref(ref, schemas)resolving_refs = resolving_refs | {ref}properties = schema.get("properties", {})@@ -743,13 +946,13 @@ def _create_dataclass(# Boolean schemas (JSON Schema draft-06+): resolve type directly,# then use an empty dict for .get() calls below.if isinstance(prop_schema, bool):- field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)+ field_type = _schema_to_type(prop_schema, schemas, resolving_refs)prop_schema = {}elif prop_schema.get("$ref") == "#":# Check for self-reference in propertyfield_type = ForwardRef(sanitized_name)else:- field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)+ field_type = _schema_to_type(prop_schema, schemas, resolving_refs)default_val = prop_schema.get("default", MISSING)is_required = prop_name in required@@ -786,9 +989,6 @@ def _create_dataclass(return datacls._apply_defaults = _apply_defaults # type: ignore[attr-defined] # ty:ignore[unresolved-attribute]-- # Store completed class- _classes[cache_key] = clsreturn clsdiff --git a/loq.toml b/loq.tomlindex 654c59997..fb31aebe9 100644--- a/loq.toml+++ b/loq.toml@@ -65,3 +65,7 @@ max_lines = 1185[[rules]]path = "tests/utilities/openapi/test_director.py"max_lines = 1154++[[rules]]+path = "fastmcp_slim/fastmcp/utilities/json_schema_type.py"+max_lines = 1059diff --git a/tests/utilities/json_schema_type/test_generated_classes.py b/tests/utilities/json_schema_type/test_generated_classes.pynew file mode 100644index 000000000..a685a8c96--- /dev/null+++ b/tests/utilities/json_schema_type/test_generated_classes.py@@ -0,0 +1,710 @@+"""Generated class names, field aliases, conversion limits, and the class cache."""++import gc+import json+import keyword+import weakref+from typing import Any++import pytest+from pydantic import BaseModel, Field, TypeAdapter, ValidationError+from pydantic.fields import FieldInfo++from fastmcp import Client, Context, FastMCP+from fastmcp.client.elicitation import ElicitResult+from fastmcp.tools import ToolResult+from fastmcp.utilities import json_schema_type+from fastmcp.utilities.json_schema_type import (+ json_schema_to_type,+ json_schema_to_type_adapter,+ safe_create_model,+)++TITLE = "Order Item (v2)"+++def order_item_schema(children: dict[str, Any], title: str = TITLE) -> dict[str, Any]:+ return {+ "type": "object",+ "title": title,+ "properties": {"name": {"type": "string"}, "children": children},+ }+++def nested_items_schema(title: str) -> dict[str, Any]:+ self_reference = {"$ref": "#", "title": title}+ return order_item_schema({"type": "array", "items": self_reference}, title)+++NESTED_ITEMS_VALUE = {"name": "a", "children": [{"name": "b"}]}++AWKWARD_TITLES = {+ "parenthesized_version": "Order Item (v2)",+ "double_quotes": 'Item "A"',+ "apostrophe": "it's an item",+ "dot_and_slash": "a.b/c",+ "keyword": "class",+ "none_keyword": "None",+ "leading_digit": "3d model",+ "non_ascii": "εε",+ "empty": "",+ "very_long": "Item " * 60,+ "newline_and_tab": "Item\nOne\tTwo",+ "dunder": "__init__",+ "call_syntax": "Item(1)",+ "subscript_syntax": "list[str]",+ "boolean_words": "a or b",+ "conditional_words": "x if y else z",+ "lambda_words": "lambda: 0",+ "semicolon": "a; b",+ "hash_sign": "item#1",+ "trailing_backslash": "Item\\",+ "only_punctuation": "!!!",+}+++SELF_REFERENCE = {"$ref": "#", "title": TITLE}+NESTED_ORDER_ITEMS = order_item_schema({"type": "array", "items": SELF_REFERENCE})+RESERVED_PROPERTIES = {+ "type": "object",+ "additionalProperties": True,+ "properties": {+ "model_config": {"type": "string"},+ "_private": {"type": "string"},+ "name": {"type": "string"},+ },+}+++class TestDescriptiveTitles:+ def test_title_becomes_valid_class_name(self):+ generated = json_schema_to_type(NESTED_ORDER_ITEMS)++ assert generated.__name__ == "Order_Item_v2"++ @pytest.mark.parametrize("title", AWKWARD_TITLES.values(), ids=AWKWARD_TITLES)+ def test_any_title_becomes_valid_class_name(self, title: str):+ generated = json_schema_to_type(nested_items_schema(title))++ assert generated.__name__.isidentifier()+ assert not keyword.iskeyword(generated.__name__)++ @pytest.mark.parametrize("title", AWKWARD_TITLES.values(), ids=AWKWARD_TITLES)+ def test_any_title_supports_nested_self_reference(self, title: str):+ generated = json_schema_to_type(nested_items_schema(title))++ item = TypeAdapter(generated).validate_python(NESTED_ITEMS_VALUE)++ child = item.children[0] # ty: ignore[unresolved-attribute]+ assert isinstance(child, generated)+ assert child.name == "b"++ @pytest.mark.parametrize(+ "title,expected",+ [+ ("class", "class_"),+ ("None", "None_"),+ ("3d model", "field_3d_model"),+ ("", "field"),+ ("!!!", "field"),+ ("list[str]", "list_str"),+ ("Item(1)", "Item_1"),+ ],+ )+ def test_title_class_names(self, title: str, expected: str):+ generated = json_schema_to_type(nested_items_schema(title))++ assert generated.__name__ == expected++ @pytest.mark.parametrize(+ "children,value",+ [+ ({"type": "array", "items": SELF_REFERENCE}, [{"name": "b"}]),+ ({"anyOf": [SELF_REFERENCE, {"type": "null"}]}, {"name": "b"}),+ (+ {"type": "object", "additionalProperties": SELF_REFERENCE},+ {"first": {"name": "b"}},+ ),+ ({"type": ["array", "null"], "items": SELF_REFERENCE}, [{"name": "b"}]),+ ],+ ids=["array", "union", "map", "type_list"],+ )+ def test_nested_self_reference_validates(+ self, children: dict[str, Any], value: Any+ ):+ generated = json_schema_to_type(order_item_schema(children))++ item = TypeAdapter(generated).validate_python({"name": "a", "children": value})++ nested = item.children # ty: ignore[unresolved-attribute]+ child = nested["first"] if isinstance(nested, dict) else nested+ child = child[0] if isinstance(child, list) else child+ assert isinstance(child, generated)+ assert child.name == "b"+++class TestClientSchemas:+ async def test_tool_output_with_self_reference(self):+ server = FastMCP("Orders")++ @server.tool(output_schema=NESTED_ORDER_ITEMS)+ def order() -> ToolResult:+ return ToolResult(+ structured_content={"name": "a", "children": [{"name": "b"}]}+ )++ async with Client(server) as client:+ result = await client.call_tool("order", {})++ assert type(result.data).__name__ == "Order_Item_v2"+ assert result.data.children[0].name == "b"++ @pytest.mark.parametrize("title", AWKWARD_TITLES.values(), ids=AWKWARD_TITLES)+ async def test_tool_output_with_any_title(self, title: str):+ server = FastMCP("Orders")++ @server.tool(output_schema=nested_items_schema(title))+ def order() -> ToolResult:+ return ToolResult(structured_content=NESTED_ITEMS_VALUE)++ async with Client(server) as client:+ result = await client.call_tool("order", {})++ assert type(result.data).__name__.isidentifier()+ assert not keyword.iskeyword(type(result.data).__name__)+ child = result.data.children[0]+ assert isinstance(child, type(result.data))+ assert child.name == "b"++ async def test_tool_output_with_reserved_property_names(self):+ server = FastMCP("Settings")+ content = {"model_config": "strict", "_private": "x", "name": "a"}++ @server.tool(output_schema=RESERVED_PROPERTIES)+ def settings() -> ToolResult:+ return ToolResult(structured_content=content)++ async with Client(server) as client:+ result = await client.call_tool("settings", {})++ assert isinstance(result.data, BaseModel)+ assert result.data.model_dump(by_alias=True) == content++ @pytest.mark.parametrize(+ "schema,content",+ [+ (NESTED_ORDER_ITEMS, {"name": "a", "children": [{"name": "b"}]}),+ (RESERVED_PROPERTIES, {"model_config": "strict", "name": "a"}),+ ],+ ids=["self_reference", "reserved_property_names"],+ )+ async def test_elicitation_schema(+ self, schema: dict[str, Any], content: dict[str, Any]+ ):+ server = FastMCP("Forms")+ validated: list[Any] = []++ @server.tool+ async def ask(ctx: Context) -> str:+ response = await ctx.session.elicit_form(+ message="Provide data",+ requested_schema=schema,+ related_request_id=ctx.request_id,+ )+ return response.action++ async def handler(+ message: str, response_type: Any, params: Any, context: Any+ ) -> ElicitResult[dict[str, Any]]:+ validated.append(TypeAdapter(response_type).validate_python(content))+ return ElicitResult(action="accept", content={"name": "a"})++ async with Client(server, mode="legacy", elicitation_handler=handler) as client:+ result = await client.call_tool("ask", {})++ assert result.data == "accept"+ assert len(validated) == 1++ @pytest.mark.parametrize("title", AWKWARD_TITLES.values(), ids=AWKWARD_TITLES)+ async def test_elicitation_schema_with_any_title(self, title: str):+ server = FastMCP("Forms")+ validated: list[Any] = []++ @server.tool+ async def ask(ctx: Context) -> str:+ response = await ctx.session.elicit_form(+ message="Provide data",+ requested_schema=nested_items_schema(title),+ related_request_id=ctx.request_id,+ )+ return response.action++ async def handler(+ message: str, response_type: Any, params: Any, context: Any+ ) -> ElicitResult[dict[str, Any]]:+ validated.append(+ TypeAdapter(response_type).validate_python(NESTED_ITEMS_VALUE)+ )+ return ElicitResult(action="accept", content={"name": "a"})++ async with Client(server, mode="legacy", elicitation_handler=handler) as client:+ result = await client.call_tool("ask", {})++ assert result.data == "accept"+ assert len(validated) == 1+ child = validated[0].children[0]+ assert isinstance(child, type(validated[0]))+ assert child.name == "b"+++class TestPropertyNamesAreFields:+ @pytest.mark.parametrize(+ "name",+ [+ "__annotations__",+ "__base__",+ "__config__",+ "__validators__",+ "__slots__",+ "_private",+ "model_config",+ "model_dump",+ "model_fields",+ "__class__",+ "__dict__",+ "__init__",+ "__module__",+ "__qualname__",+ "__doc__",+ "__eq__",+ "model_post_init",+ "model_validate",+ "model_copy",+ "_1",+ ],+ )+ def test_reserved_names_become_aliased_fields(self, name: str):+ generated = json_schema_to_type(+ {+ "type": "object",+ "additionalProperties": True,+ "properties": {+ name: {"type": "string", "default": "default"},+ "ordinary": {"type": "integer"},+ },+ "required": ["ordinary"],+ }+ )++ assert issubclass(generated, BaseModel)+ assert generated.model_config.get("extra") == "allow"+ instance = generated.model_validate({name: "data", "ordinary": 3, "other": 1})+ assert instance.model_dump(by_alias=True) == {+ name: "data",+ "ordinary": 3,+ "other": 1,+ }+ defaulted = generated.model_validate({"ordinary": 3})+ assert defaulted.model_dump(by_alias=True)[name] == "default"++ @pytest.mark.parametrize("name", ["ordinary", "foo-bar", "json", "class"])+ def test_other_names_keep_their_field_name(self, name: str):+ generated = json_schema_to_type(+ {+ "type": "object",+ "additionalProperties": True,+ "properties": {name: {"type": "string"}},+ }+ )++ assert issubclass(generated, BaseModel)+ assert list(generated.model_fields) == [name]+ assert generated.model_validate({name: "v"}).model_dump() == {name: "v"}++ def test_renamed_field_does_not_collide_with_existing_property(self):+ generated = json_schema_to_type(+ {+ "type": "object",+ "additionalProperties": True,+ "properties": {+ "model_config": {"type": "string"},+ "field_model_config": {"type": "integer"},+ },+ }+ )++ assert issubclass(generated, BaseModel)+ instance = generated.model_validate(+ {"model_config": "a", "field_model_config": 1}+ )+ assert instance.model_dump(by_alias=True) == {+ "model_config": "a",+ "field_model_config": 1,+ }++ def test_safe_create_model_keeps_field_metadata(self):+ model = safe_create_model(+ "Form",+ {"__base__": (str, Field(description="Required input"))},+ )++ field_info = next(iter(model.model_fields.values()))+ assert isinstance(field_info, FieldInfo)+ assert field_info.alias == "__base__"+ assert field_info.description == "Required input"+ assert field_info.is_required()+ with pytest.raises(ValidationError):+ model.model_validate({})+ assert model.model_validate({"__base__": "ok"}).model_dump(by_alias=True) == {+ "__base__": "ok"+ }+++DICTIONARY_DEFAULT = {"name": "text", "count": "int"}+ANNOTATIONS_PROPERTY = {+ "type": "object",+ "title": "Result",+ "additionalProperties": True,+ "properties": {+ "ok": {"type": "boolean"},+ "__annotations__": {"default": DICTIONARY_DEFAULT},+ },+}+ANNOTATIONS_CONTENTS = {+ "default_applied": {"ok": True},+ "value_provided": {"ok": True, "__annotations__": {"name": "other"}},+}+ANNOTATIONS_EXPECTED = {+ "default_applied": {"ok": True, "__annotations__": DICTIONARY_DEFAULT},+ "value_provided": {"ok": True, "__annotations__": {"name": "other"}},+}+++class TestDictionaryDefaults:+ def test_dictionary_defaults_are_kept_as_field_data(self):+ generated = json_schema_to_type(ANNOTATIONS_PROPERTY)++ assert issubclass(generated, BaseModel)+ instance = generated.model_validate({"ok": True})+ assert instance.model_dump(by_alias=True) == {+ "ok": True,+ "__annotations__": DICTIONARY_DEFAULT,+ }++ def test_dictionary_defaults_leave_class_annotations_unchanged(self):+ generated = json_schema_to_type(ANNOTATIONS_PROPERTY)++ assert issubclass(generated, BaseModel)+ assert set(generated.__annotations__) == set(generated.model_fields)+ assert set(generated.__annotations__).isdisjoint(DICTIONARY_DEFAULT)++ @pytest.mark.parametrize("case", ANNOTATIONS_CONTENTS)+ async def test_dictionary_defaults_in_tool_results(self, case: str):+ server = FastMCP("Remote")++ @server.tool(output_schema=ANNOTATIONS_PROPERTY)+ def lookup() -> ToolResult:+ return ToolResult(structured_content=ANNOTATIONS_CONTENTS[case])++ async with Client(server) as client:+ result = await client.call_tool("lookup", {})++ assert isinstance(result.data, BaseModel)+ assert result.data.model_dump(by_alias=True) == ANNOTATIONS_EXPECTED[case]+ assert set(type(result.data).__annotations__) == set(+ type(result.data).model_fields+ )++ @pytest.mark.parametrize("case", ANNOTATIONS_CONTENTS)+ async def test_dictionary_defaults_in_elicitation_schemas(self, case: str):+ server = FastMCP("Forms")+ validated: list[BaseModel] = []++ @server.tool+ async def ask(ctx: Context) -> str:+ response = await ctx.session.elicit_form(+ message="Provide data",+ requested_schema=ANNOTATIONS_PROPERTY,+ related_request_id=ctx.request_id,+ )+ return response.action++ async def handler(+ message: str, response_type: Any, params: Any, context: Any+ ) -> ElicitResult[dict[str, Any]]:+ validated.append(+ TypeAdapter(response_type).validate_python(ANNOTATIONS_CONTENTS[case])+ )+ return ElicitResult(action="accept", content={"ok": True})++ async with Client(server, mode="legacy", elicitation_handler=handler) as client:+ result = await client.call_tool("ask", {})++ assert result.data == "accept"+ assert len(validated) == 1+ assert validated[0].model_dump(by_alias=True) == ANNOTATIONS_EXPECTED[case]+ assert set(type(validated[0]).__annotations__) == set(+ type(validated[0]).model_fields+ )+++def fanout_schema(depth: int, fanout: int) -> dict[str, Any]:+ defs: dict[str, Any] = {"L0": {"type": "string"}}+ for i in range(1, depth + 1):+ defs[f"L{i}"] = {"anyOf": [{"$ref": f"#/$defs/L{i - 1}"}] * fanout}+ return {+ "type": "object",+ "title": "SharedGraph",+ "properties": {"x": {"$ref": f"#/$defs/L{depth}"}},+ "$defs": defs,+ }+++def flat_chain_schema(length: int) -> dict[str, Any]:+ defs: dict[str, Any] = {+ f"L{i}": {"$ref": f"#/$defs/L{i + 1}"} for i in range(length)+ }+ defs[f"L{length}"] = {"type": "string"}+ return {+ "type": "object",+ "title": "FlatChain",+ "properties": {"x": {"$ref": "#/$defs/L0"}},+ "$defs": defs,+ }+++def wrapped_definition_schema(+ title: str, *, additional_properties: bool, description_size: int = 3_000+) -> dict[str, Any]:+ wrapper: dict[str, Any] = {+ "type": "object",+ "title": "Wrapper",+ "properties": {"child": {"$ref": "#/$defs/Large"}},+ "required": ["child"],+ }+ if additional_properties:+ wrapper["additionalProperties"] = True+ return {+ "type": "object",+ "title": title,+ "properties": {"wrapper": wrapper},+ "required": ["wrapper"],+ "$defs": {+ "Large": {+ "type": "object",+ "title": "Large",+ "description": "x" * description_size,+ "properties": {"x": {"type": "string"}},+ }+ },+ }+++class TestConversionLimits:+ def test_shared_references_are_converted_once(+ self, monkeypatch: pytest.MonkeyPatch+ ):+ calls = 0+ original = json_schema_type._resolve_ref++ def counting_resolve(ref: str, schemas: Any) -> Any:+ nonlocal calls+ calls += 1+ return original(ref, schemas)++ monkeypatch.setattr(json_schema_type, "_resolve_ref", counting_resolve)+ generated = json_schema_to_type(fanout_schema(depth=8, fanout=3))++ assert TypeAdapter(generated).validate_python({"x": "ok"}).x == "ok" # ty: ignore[unresolved-attribute]+ assert calls <= 9++ def test_long_reference_chain_is_rejected(self):+ with pytest.raises(ValueError, match="too deeply nested"):+ json_schema_to_type(flat_chain_schema(400))++ def test_repeated_type_lists_are_rejected(self, monkeypatch: pytest.MonkeyPatch):+ monkeypatch.setattr(+ json_schema_type, "_MAX_CONVERSION_STEPS", 200, raising=False+ )+ schema: dict[str, Any] = {"type": "string"}+ for _ in range(8):+ schema = {"type": ["array", "array"], "items": schema}++ with pytest.raises(ValueError, match="too large"):+ json_schema_to_type(schema)++ def test_deeply_nested_models_still_convert(self):+ depth = 20+ defs: dict[str, Any] = {+ f"M{i}": {+ "type": "object",+ "properties": {+ "child": {+ "anyOf": [{"$ref": f"#/$defs/M{i + 1}"}, {"type": "null"}]+ }+ },+ }+ for i in range(depth)+ }+ defs[f"M{depth}"] = {+ "type": "object",+ "properties": {"leaf": {"type": "string"}},+ }+ schema = {+ "type": "object",+ "title": "Deep",+ "properties": {"child": {"$ref": "#/$defs/M0"}},+ "$defs": defs,+ }+ value: dict[str, Any] = {"leaf": "ok"}+ for _ in range(depth):+ value = {"child": value}++ instance = TypeAdapter(json_schema_to_type(schema)).validate_python(+ {"child": value}+ )++ node: Any = instance.child # ty: ignore[unresolved-attribute]+ for _ in range(depth):+ node = node.child+ assert node.leaf == "ok"+++class TestClassCache:+ def test_failed_conversion_can_be_retried(self):+ schema = {"type": "object", "title": "RetryInvalid", "properties": {"x": 123}}++ for _ in range(2):+ with pytest.raises(AttributeError):+ json_schema_to_type(schema)++ def test_rejected_conversion_leaves_cache_unchanged(self):+ before = len(json_schema_type._classes)++ with pytest.raises(ValueError):+ json_schema_to_type(flat_chain_schema(400))++ assert len(json_schema_type._classes) == before++ def test_cache_is_bounded(self, monkeypatch: pytest.MonkeyPatch):+ monkeypatch.setattr(json_schema_type._classes, "max_entries", 3)+ json_schema_type._classes.clear()++ for i in range(5):+ json_schema_to_type(+ {+ "type": "object",+ "title": f"Unique{i}",+ "properties": {"x": {"type": "string"}},+ }+ )++ assert len(json_schema_type._classes) == 3++ def test_size_budget_evicts_large_schemas(self, monkeypatch: pytest.MonkeyPatch):+ def schema(i: int) -> dict[str, Any]:+ return {+ "type": "object",+ "title": f"Large{i}",+ "description": "x" * 1000,+ "properties": {"x": {"type": "string"}},+ }++ weight = len(json.dumps(schema(0), sort_keys=True))+ monkeypatch.setattr(json_schema_type._classes, "max_weight", weight * 3 // 2)+ json_schema_type._classes.clear()++ json_schema_to_type(schema(0))+ json_schema_to_type(schema(1))++ assert len(json_schema_type._classes) == 1++ def test_schema_over_size_budget_is_not_cached(+ self, monkeypatch: pytest.MonkeyPatch+ ):+ monkeypatch.setattr(json_schema_type._classes, "max_weight", 10)+ json_schema_type._classes.clear()++ json_schema_to_type(+ {"type": "object", "title": "Big", "properties": {"x": {"type": "string"}}}+ )++ assert len(json_schema_type._classes) == 0++ def test_evicted_classes_are_released(self, monkeypatch: pytest.MonkeyPatch):+ monkeypatch.setattr(json_schema_type._classes, "max_entries", 2)+ monkeypatch.setattr(json_schema_type._adapters, "max_entries", 2)+ json_schema_type._classes.clear()+ json_schema_type._adapters.clear()+ refs: list[weakref.ref[type]] = []++ for i in range(4):+ schema = {+ "type": "object",+ "title": f"Released{i}",+ "properties": {"x": {"type": "string"}},+ }+ value = json_schema_to_type_adapter(schema).validate_python({"x": "a"})+ refs.append(weakref.ref(type(value)))+ del value+ gc.collect()++ assert [ref() is not None for ref in refs] == [False, False, True, True]++ def test_nested_classes_depend_on_root_definitions(self):+ def schema(value_type: str) -> dict[str, Any]:+ return {+ "type": "object",+ "properties": {+ "nested": {+ "type": "object",+ "properties": {"value": {"$ref": "#/$defs/Value"}},+ }+ },+ "$defs": {"Value": {"type": value_type}},+ }++ as_string = TypeAdapter(json_schema_to_type(schema("string")))+ as_integer = TypeAdapter(json_schema_to_type(schema("integer")))++ string_value = as_string.validate_python({"nested": {"value": "a"}})+ integer_value = as_integer.validate_python({"nested": {"value": 3}})+ assert string_value.nested.value == "a" # ty: ignore[unresolved-attribute]+ assert integer_value.nested.value == 3 # ty: ignore[unresolved-attribute]++ def test_classes_from_one_conversion_are_charged_for_its_root_schema(+ self, monkeypatch: pytest.MonkeyPatch+ ):+ schema = wrapped_definition_schema("Charged", additional_properties=True)+ root_size = len(json.dumps(schema, sort_keys=True))+ monkeypatch.setattr(json_schema_type._classes, "max_weight", root_size * 3 // 2)+ json_schema_type._classes.clear()++ json_schema_to_type(schema)++ assert len(json_schema_type._classes) == 1++ @pytest.mark.parametrize("additional_properties", [False, True])+ def test_classes_referencing_a_large_definition_are_charged_for_it(+ self, monkeypatch: pytest.MonkeyPatch, additional_properties: bool+ ):+ monkeypatch.setattr(json_schema_type._classes, "max_weight", 2_000)+ monkeypatch.setattr(json_schema_type._adapters, "max_weight", 2_000)+ json_schema_type._classes.clear()+ json_schema_type._adapters.clear()+ large_classes: list[weakref.ref[type]] = []++ for i in range(4):+ schema = wrapped_definition_schema(+ f"Referencing{i}", additional_properties=additional_properties+ )+ value = json_schema_to_type_adapter(schema).validate_python(+ {"wrapper": {"child": {"x": "a"}}}+ )+ large_classes.append(weakref.ref(type(value.wrapper.child)))+ del value+ gc.collect()++ assert [ref() for ref in large_classes] == [None] * 4+ assert len(json_schema_type._classes) == 0+ assert len(json_schema_type._adapters) == 0