Add TypedDict closed and extra_items support (PEP 728) (#2922)

* Add TypedDict closed and extra_items support (PEP 728)

* Add pragma no branch for unreachable coverage branches

* Remove inline comments

Author: koxudaxi

src/datamodel_code_generator/_types/generate_config_dict.py

@@ -5,7 +5,7 @@
 
 from typing import TYPE_CHECKING, Any, TypedDict
 
-from typing_extensions import NotRequired
+from typing_extensions import NotRequired, TypedDict
 
 if TYPE_CHECKING:
     from collections import defaultdict
@@ -38,7 +38,7 @@
     from datamodel_code_generator.validators import ModelValidators, ValidatorMode
 
 
-class GenerateConfigDict(TypedDict):
+class GenerateConfigDict(TypedDict, closed=True):
     input_filename: NotRequired[str | None]
     input_file_type: NotRequired[InputFileType]
     output: NotRequired[Path | None]

src/datamodel_code_generator/_types/parse_config_dict.py

@@ -3,17 +3,17 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, TypedDict
+from typing import TYPE_CHECKING
 
-from typing_extensions import NotRequired
+from typing_extensions import NotRequired, TypedDict
 
 if TYPE_CHECKING:
     from pathlib import Path
 
     from datamodel_code_generator.enums import AllExportsCollisionStrategy, AllExportsScope, ModuleSplitMode
 
 
-class ParseConfigDict(TypedDict):
+class ParseConfigDict(TypedDict, closed=True):
     with_import: NotRequired[bool | None]
     format_: NotRequired[bool | None]
     settings_path: NotRequired[Path | None]

src/datamodel_code_generator/_types/parser_config_dicts.py

@@ -5,7 +5,7 @@
 
 from typing import TYPE_CHECKING, Any, TypeAlias, TypedDict
 
-from typing_extensions import NotRequired
+from typing_extensions import NotRequired, TypedDict
 
 if TYPE_CHECKING:
     from collections import defaultdict
@@ -160,7 +160,7 @@ class ParserConfigDict(TypedDict):
     default_value_overrides: NotRequired[Mapping[str, Any] | None]
 
 
-class GraphQLParserConfigDict(ParserConfigDict):
+class GraphQLParserConfigDict(ParserConfigDict, closed=True):
     data_model_scalar_type: NotRequired[type[DataModel]]
     data_model_union_type: NotRequired[type[DataModel]]
     graphql_no_typename: NotRequired[bool]
@@ -170,7 +170,7 @@ class JSONSchemaParserConfigDict(ParserConfigDict):
     pass
 
 
-class OpenAPIParserConfigDict(JSONSchemaParserConfigDict):
+class OpenAPIParserConfigDict(JSONSchemaParserConfigDict, closed=True):
     openapi_scopes: NotRequired[list[OpenAPIScope] | None]
     include_path_parameters: NotRequired[bool]
     use_status_code_in_response_name: NotRequired[bool]

src/datamodel_code_generator/format.py

@@ -128,6 +128,14 @@ def has_typed_dict_read_only(self) -> bool:
         """Check if Python version supports TypedDict ReadOnly (PEP 705)."""
         return self._is_py_313_or_later
 
+    @property
+    def has_typed_dict_closed(self) -> bool:
+        """Check if Python version supports TypedDict closed/extra_items (PEP 728).
+
+        PEP 728 is targeted for Python 3.15. Until then, typing_extensions is required.
+        """
+        return False
+
     @property
     def has_kw_only_dataclass(self) -> bool:
         """Check if Python version supports kw_only in dataclasses."""

src/datamodel_code_generator/input_model.py

@@ -653,6 +653,7 @@ def _transform_single_model_to_inheritance(
         defs.update(parent_defs)
 
     parent_def = {k: v for k, v in parent_schema.items() if k != "$defs"}
+    parent_def["x-is-base-class"] = True
     defs[parent_name] = parent_def
 
     original_props = cast("dict[str, object]", schema.get("properties", {}))
@@ -801,7 +802,10 @@ def load_model_schema(  # noqa: PLR0912, PLR0914, PLR0915
         if "$defs" in schema:
             schema_defs = cast("dict[str, object]", schema["$defs"])
             for k, v in schema_defs.items():
-                if k not in merged_defs:
+                new_is_base = isinstance(v, dict) and v.get("x-is-base-class")
+                existing = merged_defs.get(k)
+                existing_is_base = isinstance(existing, dict) and existing.get("x-is-base-class") if existing else False
+                if k not in merged_defs or (new_is_base and not existing_is_base):
                     merged_defs[k] = v
 
         model_def = {k: v for k, v in schema.items() if k != "$defs"}

src/datamodel_code_generator/model/template/TypedDictFunction.jinja2

@@ -20,5 +20,5 @@
 {% endif %}
     {%- endif %}
 {%- endfor -%}
-})
+}{{ typed_dict_kwargs_suffix|default('') }})
 

src/datamodel_code_generator/model/typed_dict.py

@@ -16,6 +16,7 @@
     IMPORT_READ_ONLY,
     IMPORT_READ_ONLY_BACKPORT,
     IMPORT_TYPED_DICT,
+    IMPORT_TYPED_DICT_BACKPORT,
 )
 from datamodel_code_generator.types import NOT_REQUIRED_PREFIX, READ_ONLY_PREFIX
 
@@ -88,6 +89,68 @@ def __init__(  # noqa: PLR0913
             keyword_only=keyword_only,
             treat_dot_as_module=treat_dot_as_module,
         )
+        self._setup_closed_extra_items()
+
+    def _setup_closed_extra_items(self) -> None:
+        """Set up closed and extra_items kwargs based on additionalProperties.
+
+        For PEP 728 TypedDict support:
+        - additionalProperties: false -> closed=True
+        - additionalProperties: { type: X } -> extra_items=X
+
+        Note: closed=True is not applied to TypedDicts used as base classes,
+        as PEP 728 doesn't allow child TypedDicts to add new fields when
+        parent has closed=True.
+        """
+        additional_props = self.extra_template_data.get("additionalProperties")
+        additional_props_type = self.extra_template_data.get("additionalPropertiesType")
+        is_base_class = self.extra_template_data.get("is_base_class", False)
+
+        typed_dict_kwargs: dict[str, str] = {}
+
+        if additional_props is False and not is_base_class:
+            typed_dict_kwargs["closed"] = "True"
+        elif additional_props_type and not is_base_class:
+            typed_dict_kwargs["extra_items"] = additional_props_type
+
+        if typed_dict_kwargs:
+            self.extra_template_data["typed_dict_kwargs"] = typed_dict_kwargs
+            kwargs_str = ", ".join(f"{k}={v}" for k, v in typed_dict_kwargs.items())
+            self.extra_template_data["typed_dict_kwargs_suffix"] = f", {kwargs_str}"
+
+    @property
+    def _has_typed_dict_kwargs(self) -> bool:
+        """Check if this TypedDict has closed or extra_items kwargs."""
+        return bool(self.extra_template_data.get("typed_dict_kwargs"))
+
+    @property
+    def _use_typeddict_backport(self) -> bool:
+        """Check if this TypedDict needs typing_extensions.TypedDict for closed/extra_items."""
+        return bool(self.extra_template_data.get("use_typeddict_backport"))
+
+    @property
+    def base_class(self) -> str:
+        """Get base class string with kwargs if needed.
+
+        For PEP 728 support, includes closed=True or extra_items=X in the base class.
+        """
+        base = super().base_class
+        typed_dict_kwargs = self.extra_template_data.get("typed_dict_kwargs")
+        if typed_dict_kwargs:
+            kwargs_str = ", ".join(f"{k}={v}" for k, v in typed_dict_kwargs.items())
+            return f"{base}, {kwargs_str}"
+        return base
+
+    @property
+    def imports(self) -> tuple[Import, ...]:
+        """Get imports, using backport TypedDict when closed/extra_items are used on Python < 3.13."""
+        base_imports = list(super().imports)
+
+        if self._use_typeddict_backport and self._has_typed_dict_kwargs:
+            base_imports = [i for i in base_imports if i != IMPORT_TYPED_DICT]
+            base_imports.append(IMPORT_TYPED_DICT_BACKPORT)
+
+        return tuple(base_imports)
 
     @property
     def is_functional_syntax(self) -> bool:

src/datamodel_code_generator/parser/jsonschema.py

@@ -1136,9 +1136,22 @@ def get_ref_data_type(self, ref: str) -> DataType:
         return self.data_type(reference=reference, is_optional=is_optional)
 
     def set_additional_properties(self, path: str, obj: JsonSchemaObject) -> None:
-        """Set additional properties flag in extra template data."""
+        """Set additional properties flag in extra template data.
+
+        For TypedDict with PEP 728 support:
+        - additionalProperties: false -> closed=True
+        - additionalProperties: { type: X } -> extra_items=X
+        """
         if isinstance(obj.additionalProperties, bool):
             self.extra_template_data[path]["additionalProperties"] = obj.additionalProperties
+            if obj.additionalProperties is False and not self.target_python_version.has_typed_dict_closed:
+                self.extra_template_data[path]["use_typeddict_backport"] = True
+        elif isinstance(obj.additionalProperties, JsonSchemaObject):
+            additional_props_type = self._build_lightweight_type(obj.additionalProperties)
+            if additional_props_type:  # pragma: no branch
+                self.extra_template_data[path]["additionalPropertiesType"] = additional_props_type.type_hint
+                if not self.target_python_version.has_typed_dict_closed:  # pragma: no branch
+                    self.extra_template_data[path]["use_typeddict_backport"] = True
 
     def set_unevaluated_properties(self, path: str, obj: JsonSchemaObject) -> None:
         """Set unevaluated properties flag in extra template data."""
@@ -1168,6 +1181,9 @@ def set_schema_extensions(self, path: str, obj: JsonSchemaObject) -> None:
         if extensions:
             self.extra_template_data[path]["extensions"] = extensions
 
+        if obj.extras.get("x-is-base-class"):
+            self.extra_template_data[path]["is_base_class"] = True
+
         # Process model_extra_keys for json_schema_extra in ConfigDict
         if self.model_extra_keys or self.model_extra_keys_without_x_prefix:
             model_extras: dict[str, Any] = {}
@@ -2167,6 +2183,7 @@ def _parse_all_of_item(  # noqa: PLR0912, PLR0913, PLR0915, PLR0917
                     ref = self.model_resolver.add_ref(all_of_item.ref)
                     if ref.path not in {b.path for b in base_classes}:
                         base_classes.append(ref)
+                        self.extra_template_data[ref.path]["is_base_class"] = True
             else:
                 # Merge child properties with parent constraints before processing
                 merged_item = self._merge_properties_with_parent_constraints(all_of_item, parent_refs)

tests/data/expected/main/input_model/config_class.py

@@ -10,7 +10,7 @@
 
 from datamodel_code_generator.enums import StrictTypes
 from datamodel_code_generator.validators import ModelValidators
-from typing_extensions import NotRequired
+from typing_extensions import NotRequired, TypedDict
 
 AllExportsCollisionStrategy: TypeAlias = Literal[
     'error', 'minimal-prefix', 'full-prefix'
@@ -42,7 +42,7 @@
 ]
 
 
-class DataclassArguments(TypedDict):
+class DataclassArguments(TypedDict, closed=True):
     init: NotRequired[bool]
     repr: NotRequired[bool]
     eq: NotRequired[bool]
@@ -114,7 +114,7 @@ class DataclassArguments(TypedDict):
 ValidatorMode: TypeAlias = Literal['before', 'after', 'wrap', 'plain']
 
 
-class GenerateConfig(TypedDict):
+class GenerateConfig(TypedDict, closed=True):
     input_filename: NotRequired[str | None]
     input_file_type: NotRequired[InputFileType]
     output: NotRequired[str | None]

tests/data/expected/main/jsonschema/typed_dict_closed.py

@@ -0,0 +1,12 @@
+# generated by datamodel-codegen:
+#   filename:  typed_dict_closed.json
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from typing_extensions import NotRequired, TypedDict
+
+
+class ClosedModel(TypedDict, closed=True):
+    name: str
+    age: NotRequired[int]