feat(python): add Python 3.11+ StrEnum compatibility (#11105)

* feat(python): add Python 3.11+ StrEnum compatibility

Generated enums now use StrEnum for Python >= 3.11 and the (str, Enum)
mixin for older versions, fixing compatibility issues with Python 3.11's
stricter enum mixin handling.

- Add fern_enum.py utility with version-aware enum base class
- Update pydantic CoreUtilities to copy fern_enum.py
- Update SDK CoreUtilities to copy fern_enum.py
- Update enum generator to use FernEnum base class

Co-Authored-By: [email protected] <[email protected]>

* chore(python): address PR feedback - rename to StrEnum, rename file to enum.py, add comments, don't re-export

- Rename FernEnum to StrEnum (use native StrEnum for Python >= 3.11)
- Rename fern_enum.py to enum.py
- Add docstring explaining the version-aware enum base class
- Don't re-export StrEnum from __init__.py (internal use only)

Co-Authored-By: [email protected] <[email protected]>

* chore(python): add StrEnum support to fastapi and pydantic generators

- Update fastapi versions.yml with changelog entry for v1.12.2
- Update pydantic versions.yml with changelog entry for v1.10.2
- Add generated enum.py to pydantic seed output

Co-Authored-By: [email protected] <[email protected]>

* fix(python): change changelog type from feat to fix for fastapi and pydantic

The semver validator requires patch version bumps to use 'fix' type, not 'feat'.
This change is semantically correct since we're fixing Python 3.11 compatibility.

Co-Authored-By: [email protected] <[email protected]>

* chore(python): use module import pattern for StrEnum to avoid naming conflicts

Change import from 'from ..core.enum import StrEnum' to 'from ..core import enum'
so generated enums use 'enum.StrEnum' instead of 'StrEnum' directly.

This avoids potential naming conflicts with user-defined classes named StrEnum.

Co-Authored-By: [email protected] <[email protected]>

* chore(python): only copy enum.py when generating actual enum classes

Co-Authored-By: [email protected] <[email protected]>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: tjb9dc

generators/python/core_utilities/pydantic/enum.py

@@ -0,0 +1,18 @@
+"""
+Provides a StrEnum base class that works across Python versions.
+
+For Python >= 3.11, this re-exports the standard library enum.StrEnum.
+For older Python versions, this defines a compatible StrEnum using the
+(str, Enum) mixin pattern so that generated SDKs can use a single base
+class in all supported Python versions.
+"""
+
+import enum
+import sys
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+
+    class StrEnum(str, enum.Enum):
+        pass

generators/python/core_utilities/sdk/enum.py

@@ -0,0 +1,18 @@
+"""
+Provides a StrEnum base class that works across Python versions.
+
+For Python >= 3.11, this re-exports the standard library enum.StrEnum.
+For older Python versions, this defines a compatible StrEnum using the
+(str, Enum) mixin pattern so that generated SDKs can use a single base
+class in all supported Python versions.
+"""
+
+import enum
+import sys
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+
+    class StrEnum(str, enum.Enum):
+        pass

generators/python/fastapi/versions.yml

@@ -1,5 +1,15 @@
 # yaml-language-server: $schema=../../../fern-versions-yml.schema.json
 # For unreleased changes, use unreleased.yml
+- version: 1.12.2
+  changelogEntry:
+    - summary: |
+        Fix Python 3.11+ enum compatibility by using StrEnum for Python >= 3.11 and the (str, Enum)
+        mixin for older versions. This resolves compatibility issues with Python 3.11's stricter
+        enum mixin handling.
+      type: fix
+  createdAt: "2025-12-08"
+  irVersion: 61
+
 - version: 1.12.1
   changelogEntry:
     - summary: Fix discriminated union Field(discriminator=...) and UnionMetadata(discriminant=...) to use Python field names instead of JSON aliases for Pydantic v2 compatibility.

generators/python/pydantic/versions.yml

@@ -1,5 +1,15 @@
 # yaml-language-server: $schema=../../../fern-versions-yml.schema.json
 # For unreleased changes, use unreleased.yml
+- version: 1.10.2
+  changelogEntry:
+    - summary: |
+        Fix Python 3.11+ enum compatibility by using StrEnum for Python >= 3.11 and the (str, Enum)
+        mixin for older versions. This resolves compatibility issues with Python 3.11's stricter
+        enum mixin handling.
+      type: fix
+  createdAt: "2025-12-08"
+  irVersion: 61
+
 - version: 1.10.1
   changelogEntry:
     - summary: Fix discriminated union Field(discriminator=...) and UnionMetadata(discriminant=...) to use Python field names instead of JSON aliases for Pydantic v2 compatibility.

generators/python/sdk/versions.yml

@@ -1,5 +1,15 @@
 # yaml-language-server: $schema=../../../fern-versions-yml.schema.json
 # For unreleased changes, use unreleased.yml
+- version: 4.44.0
+  changelogEntry:
+    - summary: |
+        Add Python 3.11+ StrEnum compatibility. Generated enums now use StrEnum for Python >= 3.11
+        and the (str, Enum) mixin for older versions, fixing compatibility issues with Python 3.11's
+        stricter enum mixin handling.
+      type: feat
+  createdAt: "2025-12-08"
+  irVersion: 61
+
 - version: 4.43.0
   changelogEntry:
     - summary: |

generators/python/src/fern_python/generators/core_utilities/core_utilities.py

@@ -42,6 +42,16 @@ def copy_to_project(self, *, project: Project) -> None:
             exports={"serialize_datetime"},
         )
 
+        self._copy_file_to_project(
+            project=project,
+            relative_filepath_on_disk="enum.py",
+            filepath_in_project=Filepath(
+                directories=self.filepath,
+                file=Filepath.FilepathPart(module_name="enum"),
+            ),
+            exports=set(),
+        )
+
         utilities_path = (
             "with_pydantic_v1_on_v2/with_aliases/pydantic_utilities.py"
             if is_v1_on_v2 and self._use_pydantic_field_aliases
@@ -119,6 +129,12 @@ def get_serialize_datetime(self) -> AST.Reference:
             ),
         )
 
+    def get_fern_enum(self) -> AST.ClassReference:
+        return AST.ClassReference(
+            qualified_name_excluding_import=("StrEnum",),
+            import_=AST.ReferenceImport(module=AST.Module.local(*self._module_path), named_import="enum"),
+        )
+
     def get_field_metadata(self) -> FieldMetadata:
         field_metadata_reference = AST.ClassReference(
             qualified_name_excluding_import=(),

generators/python/src/fern_python/generators/pydantic_model/type_declaration_handler/enum_generator.py

@@ -64,13 +64,7 @@ def generate(self) -> None:
             enum_class = AST.ClassDeclaration(
                 name=self._class_name,
                 extends=[
-                    AST.ClassReference(
-                        qualified_name_excluding_import=("str",),
-                    ),
-                    AST.ClassReference(
-                        import_=AST.ReferenceImport(module=AST.Module.built_in(("enum",))),
-                        qualified_name_excluding_import=("Enum",),
-                    ),
+                    self._context.core_utilities.get_fern_enum(),
                 ],
                 docstring=AST.Docstring(self._docs) if self._docs is not None else None,
                 snippet=self._snippet,

generators/python/src/fern_python/generators/sdk/core_utilities/core_utilities.py

@@ -42,6 +42,7 @@ def __init__(
         self._should_generate_websocket_clients = custom_config.should_generate_websocket_clients
         self._exclude_types_from_init_exports = custom_config.exclude_types_from_init_exports
         self._custom_pager_base_name = self._sanitize_pager_name(custom_config.custom_pager_name or "CustomPager")
+        self._use_str_enums = custom_config.pydantic_config.use_str_enums
 
     def copy_to_project(self, *, project: Project) -> None:
         self._copy_file_to_project(
@@ -53,6 +54,17 @@ def copy_to_project(self, *, project: Project) -> None:
             ),
             exports={"serialize_datetime"} if not self._exclude_types_from_init_exports else set(),
         )
+        # Only copy enum.py when generating actual enum classes (not string literals)
+        if not self._use_str_enums:
+            self._copy_file_to_project(
+                project=project,
+                relative_filepath_on_disk="enum.py",
+                filepath_in_project=Filepath(
+                    directories=self.filepath,
+                    file=Filepath.FilepathPart(module_name="enum"),
+                ),
+                exports=set(),
+            )
         self._copy_file_to_project(
             project=project,
             relative_filepath_on_disk="api_error.py",