Adding support for named integer enums (#1214)

Adding support for named enums via an optional extension,
`x-enum-varnames`.

This extension is added to the schema inline with the `enum` definition:
```
 "Siva.e_Install_State": {
        "enum": [
          0,
          1,
          2,
          3,
          4,
          5,
          6,
          99
        ],
        "type": "integer",
        "format": "int32",
        "x-enum-varnames": [
          "Deinstalled",
          "Installed",
          "Upcoming_Site",
          "Lab_Site",
          "Pending_Deinstall",
          "Suspended",
          "Install_In_Progress",
          "Unknown"
        ]
      },
```


The result:

![image](https://github.com/user-attachments/assets/780880b3-2f1f-49be-823b-f9abb713a3e1)

---------

Co-authored-by: Barry Barrette <[email protected]>

Author: barrybarrette

.changeset/adding_support_for_named_integer_enums.md

@@ -0,0 +1,40 @@
+---
+default: minor
+---
+
+# Adding support for named integer enums
+
+#1214 by @barrybarrette
+
+Adding support for named integer enums via an optional extension, `x-enum-varnames`. 
+
+This extension is added to the schema inline with the `enum` definition:
+```
+"MyEnum": {
+    "enum": [
+        0,
+        1,
+        2,
+        3,
+        4,
+        5,
+        6,
+        99
+    ],
+    "type": "integer",
+    "format": "int32",
+    "x-enum-varnames": [
+        "Deinstalled",
+        "Installed",
+        "Upcoming_Site",
+        "Lab_Site",
+        "Pending_Deinstall",
+        "Suspended",
+        "Install_In_Progress",
+        "Unknown"
+    ]
+}
+```
+
+The result:
+![image](https://github.com/user-attachments/assets/780880b3-2f1f-49be-823b-f9abb713a3e1)

README.md

@@ -192,6 +192,39 @@ content_type_overrides:
   application/zip: application/octet-stream
 ```
 
+## Supported Extensions
+
+### x-enum-varnames
+
+This extension has been adopted by similar projects such as [OpenAPI Tools](https://github.com/OpenAPITools/openapi-generator/pull/917).
+It is intended to provide user-friendly names for integer Enum members that get generated.
+It is critical that the length of the array matches that of the enum values.
+
+```
+"Colors": {
+   "type": "integer",
+   "format": "int32",
+   "enum": [
+       0,
+       1,
+       2
+   ], 
+  "x-enum-varnames": [
+      "Red",
+      "Green",
+      "Blue"
+   ]
+}
+```
+
+Results in:
+```
+class Color(IntEnum):
+    RED = 0
+    GREEN = 1
+    BLUE = 2
+```
+
 [changelog.md]: CHANGELOG.md
 [poetry]: https://python-poetry.org/
 [PDM]: https://pdm-project.org/latest/

end_to_end_tests/functional_tests/generated_code_execution/test_enums_and_consts.py

@@ -129,6 +129,35 @@ def test_invalid_values(self, MyModel):
             MyModel.from_dict({"enumProp": "a"})
 
 
+@with_generated_client_fixture(
+"""
+components:
+  schemas:
+    MyEnum:
+      type: integer
+      enum: [2, 3, -4]
+      x-enum-varnames: [
+        "Two",
+        "Three",
+        "Negative Four"
+      ]
+""")
+@with_generated_code_imports(
+    ".models.MyEnum",
+)
+class TestIntEnumVarNameExtensions:
+    @pytest.mark.parametrize(
+        "expected_name,expected_value",
+        [
+            ("TWO", 2),
+            ("THREE", 3),
+            ("NEGATIVE_FOUR", -4),
+        ],
+    )
+    def test_enum_values(self, MyEnum, expected_name, expected_value):
+        assert getattr(MyEnum, expected_name) == MyEnum(expected_value)
+
+
 @with_generated_client_fixture(
 """
 components:

openapi_python_client/parser/properties/enum_property.py

@@ -121,7 +121,8 @@ def build(  # noqa: PLR0911
         if parent_name:
             class_name = f"{utils.pascal_case(parent_name)}{utils.pascal_case(class_name)}"
         class_info = Class.from_string(string=class_name, config=config)
-        values = EnumProperty.values_from_list(value_list, class_info)
+        var_names = data.model_extra.get("x-enum-varnames", []) if data.model_extra else []
+        values = EnumProperty.values_from_list(value_list, class_info, var_names)
 
         if class_info.name in schemas.classes_by_name:
             existing = schemas.classes_by_name[class_info.name]
@@ -183,14 +184,21 @@ def get_imports(self, *, prefix: str) -> set[str]:
         return imports
 
     @staticmethod
-    def values_from_list(values: list[str] | list[int], class_info: Class) -> dict[str, ValueType]:
+    def values_from_list(
+        values: list[str] | list[int], class_info: Class, var_names: list[str]
+    ) -> dict[str, ValueType]:
         """Convert a list of values into dict of {name: value}, where value can sometimes be None"""
         output: dict[str, ValueType] = {}
+        use_var_names = len(var_names) == len(values)
 
         for i, value in enumerate(values):
             value = cast(Union[str, int], value)
             if isinstance(value, int):
-                if value < 0:
+                if use_var_names:
+                    key = var_names[i]
+                    sanitized_key = utils.snake_case(key).upper()
+                    output[sanitized_key] = value
+                elif value < 0:
                     output[f"VALUE_NEGATIVE_{-value}"] = value
                 else:
                     output[f"VALUE_{value}"] = value