Add validation error for --use-specialized-enum when target Python version < 3.11 (#2651)

* Fix --use-specialized-enum option to require Python 3.11+ and update help text

* docs: update command help in README

🤖 Generated by GitHub Actions

* Update help text for --use-specialized-enum option to clarify Python version requirement

* docs: update command help in README

🤖 Generated by GitHub Actions

* test: skip test for black version 22 due to StrEnum formatting issue

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: koxudaxi

README.md

@@ -397,8 +397,8 @@ Typing customization:
                         Use pydantic.SerializeAsAny for fields with types that have subtypes
                         (Pydantic v2 only)
   --use-specialized-enum, --no-use-specialized-enum
-                        Don''t use specialized Enum class (StrEnum, IntEnum) even if the
-                        target Python version supports it
+                        Use specialized Enum class (StrEnum, IntEnum). Requires --target-
+                        python-version 3.11+
   --use-standard-collections
                         Use standard collections for type hinting (list, dict)
   --use-subclass-enum   Define generic Enum class as subclass with field type when enum has

docs/index.md

@@ -389,8 +389,8 @@ Typing customization:
                         Use pydantic.SerializeAsAny for fields with types that have subtypes
                         (Pydantic v2 only)
   --use-specialized-enum, --no-use-specialized-enum
-                        Don''t use specialized Enum class (StrEnum, IntEnum) even if the
-                        target Python version supports it
+                        Use specialized Enum class (StrEnum, IntEnum). Requires --target-
+                        python-version 3.11+
   --use-standard-collections
                         Use standard collections for type hinting (list, dict)
   --use-subclass-enum   Define generic Enum class as subclass with field type when enum has

src/datamodel_code_generator/__main__.py

@@ -733,6 +733,20 @@ def main(args: Sequence[str] | None = None) -> Exit:  # noqa: PLR0911, PLR0912,
             file=sys.stderr,
         )
 
+    if (
+        config.use_specialized_enum
+        and namespace.use_specialized_enum is not False  # CLI didn't disable it
+        and (namespace.use_specialized_enum is True or pyproject_config.get("use_specialized_enum") is True)
+        and not config.target_python_version.has_strenum
+    ):
+        print(  # noqa: T201
+            f"Error: --use-specialized-enum requires --target-python-version 3.11 or later.\n"
+            f"Current target version: {config.target_python_version.value}\n"
+            f"StrEnum is only available in Python 3.11+.",
+            file=sys.stderr,
+        )
+        return Exit.ERROR
+
     extra_template_data: defaultdict[str, dict[str, Any]] | None
     if config.extra_template_data is None:
         extra_template_data = None

src/datamodel_code_generator/arguments.py

@@ -399,7 +399,7 @@ def start_section(self, heading: str | None) -> None:
 )
 typing_options.add_argument(
     "--use-specialized-enum",
-    help="Don't use specialized Enum class (StrEnum, IntEnum) even if the target Python version supports it",
+    help="Use specialized Enum class (StrEnum, IntEnum). Requires --target-python-version 3.11+",
     action=BooleanOptionalAction,
     default=None,
 )

tests/data/expected/main/no_use_specialized_enum.py

@@ -0,0 +1,12 @@
+# generated by datamodel-codegen:
+#   filename:  string_enum.json
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Model(Enum):
+    A = 'A'
+    B = 'B'

tests/data/expected/main/use_specialized_enum_py311.py

@@ -0,0 +1,12 @@
+# generated by datamodel-codegen:
+#   filename:  string_enum.json
+#   timestamp: 2019-07-26T00:00:00+00:00
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class Model(StrEnum):
+    A = 'A'
+    B = 'B'

tests/data/jsonschema/string_enum.json

@@ -0,0 +1 @@
+{"type": "string", "enum": ["A", "B"]}

tests/main/test_main_general.py

@@ -5,6 +5,7 @@
 from argparse import ArgumentTypeError, Namespace
 from typing import TYPE_CHECKING
 
+import black
 import pytest
 
 from datamodel_code_generator import (
@@ -864,3 +865,88 @@ def test_check_respects_pyproject_toml_settings(tmp_path: Path) -> None:
         extra_args=["--disable-timestamp", "--check"],
         expected_exit=Exit.OK,
     )
+
+
+def test_use_specialized_enum_requires_python_311(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Test --use-specialized-enum requires --target-python-version 3.11+."""
+    input_json = tmp_path / "input.json"
+    input_json.write_text(
+        '{"type": "string", "enum": ["A", "B"]}',
+        encoding="utf-8",
+    )
+
+    run_main_and_assert(
+        input_path=input_json,
+        output_path=tmp_path / "output.py",
+        input_file_type="jsonschema",
+        extra_args=["--use-specialized-enum"],
+        expected_exit=Exit.ERROR,
+        capsys=capsys,
+        expected_stderr_contains="--use-specialized-enum requires --target-python-version 3.11 or later",
+    )
+
+
+@pytest.mark.skipif(
+    black.__version__.split(".")[0] == "22",
+    reason="Installed black doesn't support StrEnum formatting",
+)
+def test_use_specialized_enum_with_python_311_ok(output_file: Path) -> None:
+    """Test --use-specialized-enum works with --target-python-version 3.11."""
+    run_main_and_assert(
+        input_path=JSON_SCHEMA_DATA_PATH / "string_enum.json",
+        output_path=output_file,
+        input_file_type="jsonschema",
+        extra_args=["--use-specialized-enum", "--target-python-version", "3.11"],
+        assert_func=assert_file_content,
+        expected_file="use_specialized_enum_py311.py",
+    )
+
+
+def test_use_specialized_enum_pyproject_requires_python_311(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """Test use_specialized_enum in pyproject.toml requires target_python_version 3.11+."""
+    pyproject_toml = tmp_path / "pyproject.toml"
+    pyproject_toml.write_text(
+        "[tool.datamodel-codegen]\nuse_specialized_enum = true\n",
+        encoding="utf-8",
+    )
+
+    input_json = tmp_path / "input.json"
+    input_json.write_text(
+        '{"type": "string", "enum": ["A", "B"]}',
+        encoding="utf-8",
+    )
+
+    with chdir(tmp_path):
+        run_main_and_assert(
+            input_path=input_json,
+            output_path=tmp_path / "output.py",
+            input_file_type="jsonschema",
+            expected_exit=Exit.ERROR,
+            capsys=capsys,
+            expected_stderr_contains="--use-specialized-enum requires --target-python-version 3.11 or later",
+        )
+
+
+def test_use_specialized_enum_pyproject_override_with_cli(output_file: Path, tmp_path: Path) -> None:
+    """Test --no-use-specialized-enum CLI can override pyproject.toml use_specialized_enum=true."""
+    pyproject_toml = tmp_path / "pyproject.toml"
+    pyproject_toml.write_text(
+        "[tool.datamodel-codegen]\nuse_specialized_enum = true\n",
+        encoding="utf-8",
+    )
+
+    with chdir(tmp_path):
+        run_main_and_assert(
+            input_path=JSON_SCHEMA_DATA_PATH / "string_enum.json",
+            output_path=output_file,
+            input_file_type="jsonschema",
+            extra_args=["--no-use-specialized-enum"],
+            assert_func=assert_file_content,
+            expected_file="no_use_specialized_enum.py",
+        )