Render enum fields as concrete Field instances in migrations

The migration writer rendered IntEnumField/CharEnumField using their public
factory-function names. Those factories are typed to return the enum type
(so model attributes resolve to the enum), not a Field, so the generated
migration failed mypy with 'incompatible type "tuple[str, ...]"' in
CreateModel and 'incompatible type' in AddField.

Emit the concrete IntEnumFieldInstance/CharEnumFieldInstance classes instead;
these are real Field subclasses, so the generated code type-checks while
producing an identical field at runtime. Export the instance classes from
tortoise.fields so the 'from tortoise import fields' alias resolves them.

Fixes #2155.

Author: apoorvdarshan

CHANGELOG.rst

@@ -20,6 +20,7 @@ Added
 
 Fixed
 ^^^^^
+- ``makemigrations`` now renders ``IntEnumField``/``CharEnumField`` as their concrete ``IntEnumFieldInstance``/``CharEnumFieldInstance`` classes, so generated migrations type-check under ``mypy`` instead of failing with ``incompatible type "tuple[str, ...]"``. (#2155)
 - ``MigrationRecorder`` now uses parameterized queries; fixes MariaDB/MySQL rejecting ISO-8601 ``applied_at`` values. (#2132)
 - ``db_default`` on ``ForeignKeyField``/``OneToOneField`` now propagates to the underlying ``<fk>_id`` column, so ``CREATE TABLE`` emits the ``DEFAULT`` clause for FK columns. (#2199)
 - ``MigrationRecorder`` no longer emits tortoise's own ``pk`` field ``DeprecationWarning`` when applying migrations; it now builds its bookkeeping model with ``primary_key=True``. (#2203)

tests/migrations/test_writer.py

@@ -12,6 +12,7 @@
 from tortoise.migrations.constraints import UniqueConstraint
 from tortoise.migrations.operations import (
     AddConstraint,
+    AddField,
     AddIndex,
     AlterField,
     CreateModel,
@@ -485,7 +486,14 @@ class Migration(migrations.Migration):
 
 
 def test_writer_handles_enum_fields(tmp_path: Path, monkeypatch) -> None:
-    """Test that IntEnumField and CharEnumField are rendered correctly (not as FieldInstance)."""
+    """Test that IntEnumField and CharEnumField render as their concrete Field instances.
+
+    The public ``IntEnumField``/``CharEnumField`` names are factory functions typed to
+    return the enum type (so model attributes resolve to the enum), not a ``Field``.
+    Rendering them into a migration produced code that failed ``mypy`` (see #2155), so
+    the writer emits the concrete ``*FieldInstance`` classes, which are real ``Field``
+    subclasses and therefore type-check inside migration operations.
+    """
     operations = [
         CreateModel(
             name="Entity",
@@ -496,8 +504,6 @@ def test_writer_handles_enum_fields(tmp_path: Path, monkeypatch) -> None:
             ],
         ),
     ]
-    # The migration should use fields.IntEnumField and fields.CharEnumField
-    # NOT fields.IntEnumFieldInstance or fields.CharEnumFieldInstance
     expected = textwrap.dedent(
         """\
         from tortoise import migrations
@@ -511,8 +517,8 @@ class Migration(migrations.Migration):
                     name='Entity',
                     fields=[
                         ('id', fields.IntField(generated=True, primary_key=True, unique=True, db_index=True)),
-                        ('status', fields.IntEnumField(default=Status.ACTIVE, description='ACTIVE: 1\\nINACTIVE: 2', enum_type=Status, generated=False)),
-                        ('role', fields.CharEnumField(description='ADMIN: admin\\nUSER: user', enum_type=Role, max_length=5)),
+                        ('status', fields.IntEnumFieldInstance(default=Status.ACTIVE, description='ACTIVE: 1\\nINACTIVE: 2', enum_type=Status, generated=False)),
+                        ('role', fields.CharEnumFieldInstance(description='ADMIN: admin\\nUSER: user', enum_type=Role, max_length=5)),
                     ],
                 ),
             ]
@@ -521,6 +527,42 @@ class Migration(migrations.Migration):
     _write_migration(tmp_path, monkeypatch, "0010_enum_fields", operations, expected)
 
 
+def test_writer_enum_field_render_is_field_instance(tmp_path: Path, monkeypatch) -> None:
+    """Regression test for #2155.
+
+    ``AddField`` (and ``CreateModel``) previously rendered enum fields via the public
+    ``fields.CharEnumField``/``fields.IntEnumField`` factory functions, whose declared
+    return type is the enum type rather than a ``Field``. The generated migration then
+    failed ``mypy`` with ``incompatible type "tuple[str, ExampleEnum]"``. The writer now
+    emits the concrete ``*FieldInstance`` classes so the generated code type-checks.
+    """
+    operations = [
+        AddField(
+            model_name="Entity",
+            name="role",
+            field=fields.CharEnumField(Role),  # type: ignore[arg-type]
+        ),
+    ]
+    expected = textwrap.dedent(
+        """\
+        from tortoise import migrations
+        from tortoise.migrations import operations as ops
+        from tests.migrations.test_writer import Role
+        from tortoise import fields
+
+        class Migration(migrations.Migration):
+            operations = [
+                ops.AddField(
+                    model_name='Entity',
+                    name='role',
+                    field=fields.CharEnumFieldInstance(description='ADMIN: admin\\nUSER: user', enum_type=Role, max_length=5),
+                ),
+            ]
+        """
+    )
+    _write_migration(tmp_path, monkeypatch, "0011_add_enum_field", operations, expected)
+
+
 def _runpython_forward(apps, schema_editor) -> None:
     _ = (apps, schema_editor)
 

tortoise/fields/__init__.py

@@ -12,12 +12,14 @@
     BinaryField,
     BooleanField,
     CharEnumField,
+    CharEnumFieldInstance,
     CharField,
     DateField,
     DatetimeField,
     DecimalField,
     FloatField,
     IntEnumField,
+    IntEnumFieldInstance,
     IntField,
     JSONField,
     SmallIntField,
@@ -56,13 +58,15 @@
     "BinaryField",
     "BooleanField",
     "CharEnumField",
+    "CharEnumFieldInstance",
     "CharField",
     "DateField",
     "DatetimeField",
     "TimeField",
     "DecimalField",
     "FloatField",
     "IntEnumField",
+    "IntEnumFieldInstance",
     "IntField",
     "JSONField",
     "SmallIntField",

tortoise/migrations/writer.py

@@ -222,8 +222,15 @@ def render_value(value: Any, imports: ImportManager) -> str:
 def _render_call(path: str, args: list[Any], kwargs: dict[str, Any], imports: ImportManager) -> str:
     if path.startswith("tortoise.fields."):
         class_name = path.rsplit(".", 1)[1]
-        # Render FieldInstance classes as their public Field name
-        if class_name.endswith("FieldInstance"):
+        # Render FieldInstance classes as their public Field name. The enum fields are
+        # excluded: their public ``IntEnumField``/``CharEnumField`` names are factory
+        # functions typed to return the enum type (not a ``Field``), so rendering them
+        # produces migrations that fail ``mypy`` (see #2155). The concrete
+        # ``*EnumFieldInstance`` classes are real ``Field`` subclasses that type-check.
+        if class_name.endswith("FieldInstance") and class_name not in (
+            "IntEnumFieldInstance",
+            "CharEnumFieldInstance",
+        ):
             class_name = class_name.replace("FieldInstance", "Field")
             # For relational fields, move model_name to first positional arg
             if path.startswith("tortoise.fields.relational.") and "model_name" in kwargs: