feat: add StrStructuredEnum & IntStructuredEnum class (TencentBlueKing#192)

Author: narasux

sdks/blue-krill/CHANGE.md

@@ -1,5 +1,9 @@
 ## Change logs
 
+### 2.0.7
+
+- Feature: (py 3.11+) add StrStructuredEnum, IntStructuredEnum class
+
 ### 2.0.6
 
 - Fix: update urllib3 version

sdks/blue-krill/blue_krill/__init__.py

@@ -8,4 +8,4 @@
  * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
  * specific language governing permissions and limitations under the License.
 """
-__version__ = "2.0.6"
+__version__ = "2.0.7"

sdks/blue-krill/blue_krill/data_types/enum.py

@@ -192,7 +192,16 @@ def get_field_members(cls) -> Dict:
 
 
 class StructuredEnum(OrigEnum, metaclass=StructuredEnumMeta):
-    """Structured Enum type, providing extra features such as getting enum members as choices tuple"""
+    """
+    Structured Enum type, providing extra features such as getting enum members as choices tuple
+
+    NOTE: XEnum(str / int, StructuredEnum) not working in string formatting since python 3.11，
+    please use StrStructuredEnum / IntStructuredEnum instead of StructuredEnum
+    refs:
+      - https://github.com/python/cpython/issues/100458
+      - https://github.com/TencentBlueKing/bkpaas-python-sdk/issues/190
+      - https://blog.pecar.me/python-enum
+    """
 
     @classmethod
     def get_django_choices(cls) -> List[Tuple[Any, str]]:
@@ -227,3 +236,26 @@ def get_choices(cls) -> List[Tuple[Any, str]]:
         """Get Choices for all field members."""
         members = cls.get_field_members()
         return [(field.real_value, field.label) for field in members.values()]
+
+
+try:
+    # python 3.11+ required
+    from enum import StrEnum, IntEnum
+except ImportError:
+    pass
+else:
+    class StrStructuredEnum(StructuredEnum, StrEnum):
+        """
+        StrStructuredEnum ensures the literals in f-string / str.format() is real_value
+
+        Important: Use XEnum(StrStructuredEnum) instead of XEnum(str, StructuredEnum) since python 3.11
+        """
+        pass
+
+    class IntStructuredEnum(StructuredEnum, IntEnum):
+        """
+        IntStructuredEnum ensures the literals in f-string / str.format() is real_value
+
+        Important: Use XEnum(IntStructuredEnum) instead of XEnum(int, StructuredEnum) since python 3.11
+        """
+        pass

sdks/blue-krill/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "blue-krill"
-version = "2.0.6"
+version = "2.0.7"
 description = "Tools and common packages for blueking PaaS platform."
 include = ["blue_krill/py.typed"]
 readme = "README.md"

sdks/blue-krill/tests/data_types/test_enum.py

@@ -220,3 +220,39 @@ def test_get_labels(self):
 
     def test_get_values(self):
         assert UserType.get_values() == [1, 2, 3, 4]
+
+
+try:
+    from blue_krill.data_types.enum import StrStructuredEnum, IntStructuredEnum
+except ImportError:
+    pass
+else:
+    class StrDemoEnum(StrStructuredEnum):
+        FOO = "foo"
+        BAR = "bar"
+
+    class TestStrStructuredEnum:
+        def test_value_compare(self):
+            assert StrDemoEnum.FOO == "foo"
+            assert StrDemoEnum.BAR.value == "bar"
+
+        def test_string_formatting(self):
+            assert str(StrDemoEnum.BAR) == "bar"
+            assert "%s" % StrDemoEnum.FOO == "foo"
+            assert "{}".format(StrDemoEnum.BAR) == "bar"
+            assert f"{StrDemoEnum.FOO}-{StrDemoEnum.BAR}" == "foo-bar"
+
+    class IntDemoEnum(IntStructuredEnum):
+        FOO = 1
+        BAR = 2
+
+    class TestIntStructuredEnum:
+        def test_value_compare(self):
+            assert IntDemoEnum.FOO == 1
+            assert IntDemoEnum.BAR.value == 2
+
+        def test_string_formatting(self):
+            assert str(IntDemoEnum.BAR) == "2"
+            assert "%s" % IntDemoEnum.FOO == "1"
+            assert "{}".format(IntDemoEnum.BAR) == "2"
+            assert f"{IntDemoEnum.FOO}-{IntDemoEnum.BAR}" == "1-2"