Fix admin import without django-stubs runtime monkeypatch (#113)

* Fix admin import without django-stubs runtime monkeypatch

Keep the Django generic typing in django_fsm.admin under TYPE_CHECKING so the module no longer evaluates ModelForm[...] or ModelAdmin[...] at runtime. This avoids import-time failures in downstream projects that do not call django_stubs_ext.monkeypatch() before Django admin autodiscovery.

Add a regression test that imports django_fsm.admin in a fresh subprocess with only minimal Django settings configured, proving the admin module loads without relying on the test suite's django-stubs monkeypatch. Also document the fix under Unreleased in the changelog.

* Move test to dedicated file

---------

Co-authored-by: pfouque <pfouque@users.noreply.github.com>

Author: samiashi

CHANGELOG.rst

@@ -4,6 +4,9 @@ Changelog
 Unreleased
 ~~~~~~~~~~
 
+- Fix ``django_fsm.admin`` import failures when Django generic types are not
+  runtime-subscriptable
+
 django-fsm-2 4.2.0 2026-03-07
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

django_fsm/admin.py

@@ -33,11 +33,11 @@
     from typing_extensions import override
 
 if typing.TYPE_CHECKING:  # pragma: no cover
-    _ModelAdmin = admin.ModelAdmin[fsm._FSMModel]
+    _ModelAdmin: typing.TypeAlias = admin.ModelAdmin[fsm._FSMModel]
+    _FormType: typing.TypeAlias = type[Form | ModelForm[fsm._FSMModel]]
 else:
     _ModelAdmin = admin.ModelAdmin
-
-_FormType: typing.TypeAlias = type[Form | ModelForm[fsm._FSMModel]]
+    _FormType = type[Form | ModelForm]
 
 
 @dataclass

tests/testapp/tests/test_typing.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from django.test import TestCase
+
+
+class BaseAdminTestCase(TestCase):
+    project_root: Path
+    env: dict[str, str]
+
+    def setUp(self) -> None:
+        self.project_root = Path(__file__).resolve().parents[3]
+        self.env = os.environ.copy()
+        self.env.pop("DJANGO_SETTINGS_MODULE", None)
+        python_path = self.env.get("PYTHONPATH")
+        self.env["PYTHONPATH"] = (
+            f"{self.project_root}{os.pathsep}{python_path}"
+            if python_path
+            else str(self.project_root)
+        )
+
+    def test_admin_module_imports_without_django_stubs_monkeypatch(self) -> None:
+        result = subprocess.run(  # noqa: S603
+            [
+                sys.executable,
+                "-c",
+                (
+                    "from django.conf import settings; "
+                    "settings.configure(SECRET_KEY='test', USE_I18N=False); "
+                    "import django_fsm.admin"
+                ),
+            ],
+            capture_output=True,
+            check=False,
+            cwd=self.project_root,
+            env=self.env,
+            text=True,
+        )
+
+        assert result.returncode == 0, result.stderr
+
+    def test_main_module_imports_without_django_stubs_monkeypatch(self) -> None:
+        result = subprocess.run(  # noqa: S603
+            [
+                sys.executable,
+                "-c",
+                (
+                    "from django.conf import settings; "
+                    "settings.configure(SECRET_KEY='test', USE_I18N=False); "
+                    "import django_fsm"
+                ),
+            ],
+            capture_output=True,
+            check=False,
+            cwd=self.project_root,
+            env=self.env,
+            text=True,
+        )
+
+        assert result.returncode == 0, result.stderr