Add FutureWarning for upcoming ruff default formatters

docs/formatting.md

@@ -6,6 +6,14 @@ Generated code is automatically formatted using code formatters. By default, `bl
 
 ## 🎯 Default Behavior
 
+!!! warning "Future Change"
+    In a future version, the default formatters will change from `black` and `isort` to `ruff`.
+    To prepare for this change, consider switching to ruff now using `--formatters ruff-format ruff-check`.
+
+    **CLI users**: To suppress this warning, use `--disable-warnings` or explicitly specify `--formatters black isort`.
+
+    **Library users**: Explicitly pass `formatters=[Formatter.BLACK, Formatter.ISORT]` to suppress this warning.
+
 ```bash
 datamodel-codegen --input schema.yaml --output model.py
 ```
@@ -28,6 +36,12 @@ This runs the following formatters in order:
 
 [Ruff](https://github.com/astral-sh/ruff) is a fast Python linter and formatter. To use it:
 
+!!! note "Installation Required"
+    ruff is an optional dependency. Install it with:
+    ```bash
+    pip install 'datamodel-code-generator[ruff]'
+    ```
+
 ```bash
 # Use ruff for both linting and formatting
 datamodel-codegen --formatters ruff-check ruff-format --input schema.yaml --output model.py

pyproject.toml

@@ -223,6 +223,7 @@ filterwarnings = [
   "ignore:^.*No schemas found in components/schemas.*",
   "ignore:^.*Dataclass .* has a field ordering conflict due to inheritance.*:UserWarning",
   "ignore:^.*is empty or not a dict. Skipping this file.*:UserWarning",
+  "ignore:^.*The default formatters.*:FutureWarning",
 ]
 norecursedirs = [ "tests/data/*", ".tox" ]
 verbosity_assertions = 2

src/datamodel_code_generator/__init__.py

@@ -879,7 +879,11 @@ def get_header_and_first_line(csv_file: IO[str]) -> dict[str, Any]:
 
         file.close()
 
-    if defer_formatting and (Formatter.RUFF_CHECK in config.formatters or Formatter.RUFF_FORMAT in config.formatters):
+    if (
+        defer_formatting
+        and config.formatters
+        and (Formatter.RUFF_CHECK in config.formatters or Formatter.RUFF_FORMAT in config.formatters)
+    ):
         code_formatter = CodeFormatter(
             config.target_python_version,
             config.settings_path,

src/datamodel_code_generator/__main__.py

@@ -74,7 +74,6 @@
 )
 from datamodel_code_generator.arguments import DEFAULT_ENCODING, arg_parser, namespace
 from datamodel_code_generator.format import (
-    DEFAULT_FORMATTERS,
     DateClassType,
     DatetimeClassType,
     Formatter,
@@ -595,7 +594,7 @@ def validate_class_name_affix_scope(cls, v: str | ClassNameAffixScope | None) ->
     no_alias: bool = False
     use_frozen_field: bool = False
     use_default_factory_for_optional_nested_models: bool = False
-    formatters: list[Formatter] = DEFAULT_FORMATTERS
+    formatters: list[Formatter] | None = None
     parent_scoped_naming: bool = False
     naming_strategy: Optional[NamingStrategy] = None  # noqa: UP045
     duplicate_name_suffix: Optional[dict[str, str]] = None  # noqa: UP045

src/datamodel_code_generator/_types/generate_config_dict.py

@@ -147,7 +147,7 @@ class GenerateConfigDict(TypedDict):
     no_alias: NotRequired[bool]
     use_frozen_field: NotRequired[bool]
     use_default_factory_for_optional_nested_models: NotRequired[bool]
-    formatters: NotRequired[list[Formatter]]
+    formatters: NotRequired[list[Formatter] | None]
     settings_path: NotRequired[Path | None]
     parent_scoped_naming: NotRequired[bool]
     naming_strategy: NotRequired[NamingStrategy | None]

src/datamodel_code_generator/_types/parser_config_dicts.py

@@ -136,7 +136,7 @@ class ParserConfigDict(TypedDict):
     no_alias: NotRequired[bool]
     use_frozen_field: NotRequired[bool]
     use_default_factory_for_optional_nested_models: NotRequired[bool]
-    formatters: NotRequired[list[Formatter]]
+    formatters: NotRequired[list[Formatter] | None]
     defer_formatting: NotRequired[bool]
     parent_scoped_naming: NotRequired[bool]
     naming_strategy: NotRequired[NamingStrategy | None]

src/datamodel_code_generator/config.py

@@ -30,7 +30,6 @@
     TargetPydanticVersion,
 )
 from datamodel_code_generator.format import (
-    DEFAULT_FORMATTERS,
     DateClassType,
     DatetimeClassType,
     Formatter,
@@ -185,7 +184,7 @@ class Config:
     no_alias: bool = False
     use_frozen_field: bool = False
     use_default_factory_for_optional_nested_models: bool = False
-    formatters: list[Formatter] = DEFAULT_FORMATTERS
+    formatters: list[Formatter] | None = None
     settings_path: Path | None = None
     parent_scoped_naming: bool = False
     naming_strategy: NamingStrategy | None = None
@@ -318,7 +317,7 @@ class Config:
     no_alias: bool = False
     use_frozen_field: bool = False
     use_default_factory_for_optional_nested_models: bool = False
-    formatters: list[Formatter] = DEFAULT_FORMATTERS
+    formatters: list[Formatter] | None = None
     defer_formatting: bool = False
     parent_scoped_naming: bool = False
     naming_strategy: NamingStrategy | None = None

src/datamodel_code_generator/format.py

@@ -193,10 +193,21 @@ def __init__(  # noqa: PLR0912, PLR0913, PLR0915, PLR0917
         custom_formatters: list[str] | None = None,
         custom_formatters_kwargs: dict[str, Any] | None = None,
         encoding: str = "utf-8",
-        formatters: list[Formatter] = DEFAULT_FORMATTERS,
+        formatters: list[Formatter] | None = None,
         defer_formatting: bool = False,  # noqa: FBT001, FBT002
     ) -> None:
         """Initialize code formatter with configuration for black, isort, ruff, and custom formatters."""
+        if formatters is None:
+            warn(
+                "The default formatters (black, isort) will be replaced by ruff in a future version. "
+                "To prepare for this change, consider using: formatters=[Formatter.RUFF_FORMAT, Formatter.RUFF_CHECK]. "
+                "Install ruff with: pip install 'datamodel-code-generator[ruff]'. "
+                "To suppress this warning, specify formatters explicitly.",
+                FutureWarning,
+                stacklevel=2,
+            )
+            formatters = list(DEFAULT_FORMATTERS)
+
         if not settings_path:
             settings_path = Path.cwd()
         elif settings_path.is_file():

src/datamodel_code_generator/parser/base.py

@@ -928,7 +928,7 @@ def __init__(  # noqa: PLR0912, PLR0915
         self.custom_formatters_kwargs = config.custom_formatters_kwargs
         self.treat_dot_as_module = config.treat_dot_as_module
         self.default_field_extras: dict[str, Any] | None = config.default_field_extras
-        self.formatters: list[Formatter] = config.formatters
+        self.formatters: list[Formatter] | None = config.formatters
         self.defer_formatting: bool = config.defer_formatting
         self.type_mappings: dict[tuple[str, str], str] = Parser._parse_type_mappings(config.type_mappings)
         self.type_overrides: dict[str, str] = config.type_overrides or {}

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

@@ -222,7 +222,7 @@ class GenerateConfig(TypedDict):
     no_alias: NotRequired[bool]
     use_frozen_field: NotRequired[bool]
     use_default_factory_for_optional_nested_models: NotRequired[bool]
-    formatters: NotRequired[list[Formatter]]
+    formatters: NotRequired[list[Formatter] | None]
     settings_path: NotRequired[str | None]
     parent_scoped_naming: NotRequired[bool]
     naming_strategy: NotRequired[NamingStrategy | None]

tests/main/test_public_api_signature_baseline.py

@@ -10,7 +10,7 @@
 import pytest
 from typing_extensions import NotRequired
 
-from datamodel_code_generator import DEFAULT_FORMATTERS, DEFAULT_SHARED_MODULE_NAME, generate
+from datamodel_code_generator import DEFAULT_SHARED_MODULE_NAME, generate
 from datamodel_code_generator.enums import (
     AllExportsCollisionStrategy,
     AllExportsScope,
@@ -166,7 +166,7 @@ def _baseline_generate(
     no_alias: bool = False,
     use_frozen_field: bool = False,
     use_default_factory_for_optional_nested_models: bool = False,
-    formatters: list[Formatter] = DEFAULT_FORMATTERS,
+    formatters: list[Formatter] | None = None,
     settings_path: Path | None = None,
     parent_scoped_naming: bool = False,
     naming_strategy: NamingStrategy | None = None,
@@ -293,7 +293,7 @@ def __init__(
         no_alias: bool = False,
         use_frozen_field: bool = False,
         use_default_factory_for_optional_nested_models: bool = False,
-        formatters: list[Formatter] = DEFAULT_FORMATTERS,
+        formatters: list[Formatter] | None = None,
         defer_formatting: bool = False,
         parent_scoped_naming: bool = False,
         naming_strategy: NamingStrategy | None = None,

tests/test_format.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import sys
+import warnings
 from pathlib import Path
 from unittest import mock
 
@@ -48,7 +49,11 @@ def test_format_code_with_skip_string_normalization(
 ) -> None:
     """Test code formatting with skip string normalization option."""
     monkeypatch.chdir(tmp_path)
-    formatter = CodeFormatter(PythonVersionMin, skip_string_normalization=skip_string_normalization)
+    formatter = CodeFormatter(
+        PythonVersionMin,
+        skip_string_normalization=skip_string_normalization,
+        formatters=[Formatter.BLACK, Formatter.ISORT],
+    )
 
     formatted_code = formatter.format_code("a = 'b'")
 
@@ -61,6 +66,7 @@ def test_format_code_un_exist_custom_formatter() -> None:
         _ = CodeFormatter(
             PythonVersionMin,
             custom_formatters=[UN_EXIST_FORMATTER],
+            formatters=[Formatter.BLACK, Formatter.ISORT],
         )
 
 
@@ -70,6 +76,7 @@ def test_format_code_invalid_formatter_name() -> None:
         _ = CodeFormatter(
             PythonVersionMin,
             custom_formatters=[WRONG_FORMATTER],
+            formatters=[Formatter.BLACK, Formatter.ISORT],
         )
 
 
@@ -79,6 +86,7 @@ def test_format_code_is_not_subclass() -> None:
         _ = CodeFormatter(
             PythonVersionMin,
             custom_formatters=[NOT_SUBCLASS_FORMATTER],
+            formatters=[Formatter.BLACK, Formatter.ISORT],
         )
 
 
@@ -88,6 +96,7 @@ def test_format_code_with_custom_formatter_without_kwargs(tmp_path: Path, monkey
     formatter = CodeFormatter(
         PythonVersionMin,
         custom_formatters=[ADD_COMMENT_FORMATTER],
+        formatters=[Formatter.BLACK, Formatter.ISORT],
     )
 
     formatted_code = formatter.format_code("x = 1\ny = 2")
@@ -102,6 +111,7 @@ def test_format_code_with_custom_formatter_with_kwargs(tmp_path: Path, monkeypat
         PythonVersionMin,
         custom_formatters=[ADD_LICENSE_FORMATTER],
         custom_formatters_kwargs={"license_file": EXAMPLE_LICENSE_FILE},
+        formatters=[Formatter.BLACK, Formatter.ISORT],
     )
 
     formatted_code = formatter.format_code("x = 1\ny = 2")
@@ -128,6 +138,7 @@ def test_format_code_with_two_custom_formatters(tmp_path: Path, monkeypatch: pyt
             ADD_LICENSE_FORMATTER,
         ],
         custom_formatters_kwargs={"license_file": EXAMPLE_LICENSE_FILE},
+        formatters=[Formatter.BLACK, Formatter.ISORT],
     )
 
     formatted_code = formatter.format_code("x = 1\ny = 2")
@@ -190,7 +201,9 @@ def test_settings_path_with_existing_file(tmp_path: Path) -> None:
     existing_file = tmp_path / "existing.py"
     existing_file.write_text("", encoding="utf-8")
 
-    formatter = CodeFormatter(PythonVersionMin, settings_path=existing_file)
+    formatter = CodeFormatter(
+        PythonVersionMin, settings_path=existing_file, formatters=[Formatter.BLACK, Formatter.ISORT]
+    )
 
     assert formatter.settings_path == str(tmp_path)
 
@@ -201,7 +214,9 @@ def test_settings_path_with_nonexistent_file(tmp_path: Path) -> None:
     pyproject.write_text("[tool.black]\nline-length = 60\n", encoding="utf-8")
     nonexistent_file = tmp_path / "nonexistent.py"
 
-    formatter = CodeFormatter(PythonVersionMin, settings_path=nonexistent_file)
+    formatter = CodeFormatter(
+        PythonVersionMin, settings_path=nonexistent_file, formatters=[Formatter.BLACK, Formatter.ISORT]
+    )
 
     assert formatter.settings_path == str(tmp_path)
 
@@ -212,7 +227,9 @@ def test_settings_path_with_deeply_nested_nonexistent_path(tmp_path: Path) -> No
     pyproject.write_text("[tool.black]\nline-length = 60\n", encoding="utf-8")
     nested_path = tmp_path / "a" / "b" / "c" / "nonexistent.py"
 
-    formatter = CodeFormatter(PythonVersionMin, settings_path=nested_path)
+    formatter = CodeFormatter(
+        PythonVersionMin, settings_path=nested_path, formatters=[Formatter.BLACK, Formatter.ISORT]
+    )
 
     assert formatter.settings_path == str(tmp_path)
 
@@ -338,3 +355,26 @@ def test_generate_with_ruff_batch_formatting(tmp_path: Path) -> None:
         check=False,
         cwd=mock.ANY,
     )
+
+
+def test_code_formatter_warns_when_formatters_is_none(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test that FutureWarning is emitted when formatters is None (default)."""
+    monkeypatch.chdir(tmp_path)
+    with pytest.warns(FutureWarning, match="default formatters"):
+        CodeFormatter(PythonVersionMin)
+
+
+def test_code_formatter_no_warning_when_formatters_explicit(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test that no warning is emitted when formatters is explicitly specified."""
+    monkeypatch.chdir(tmp_path)
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        CodeFormatter(PythonVersionMin, formatters=[Formatter.BLACK, Formatter.ISORT])
+
+
+def test_code_formatter_no_warning_when_formatters_empty(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test that no warning is emitted when formatters is empty list."""
+    monkeypatch.chdir(tmp_path)
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        CodeFormatter(PythonVersionMin, formatters=[])