enumerific 1.0.5__tar.gz → 1.0.7__tar.gz

{enumerific-1.0.5/source/enumerific.egg-info → enumerific-1.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: enumerific
-Version: 1.0.5
+Version: 1.0.7
 Summary: Simplifies working with Python enums.
 Author: Daniel Sissman
 License-Expression: MIT
@@ -468,6 +468,11 @@ assert Colors.BLUE.aliased is False
 assert Colors.RED.aliases == [Colors.ROUGE]
 assert Colors.GREEN.aliases == [Colors.VERTE]
 assert Colors.BLUE.aliases == []  # BLUE has not been aliased
+
+# The names including any aliases for an option can be obtained via the .named property
+assert Colors.RED.named == ["RED", "ROUGE"]
+assert Colors.GREEN.named == ["GREEN", "VERTE"]
+assert Colors.BLUE.named == ["BLUE"]
 ```
 
 #### Example 15: Non-Unique Options
@@ -670,6 +675,32 @@ assert Colors.PURPLE.rgb == (255, 0, 255)
 assert Colors.PURPLE.primary is False
 ```
 
+#### Example 19: Reconciling Enumeration Options via Annotations
+
+```python
+from enumerific import Enumeration, auto
+
+class Colors(Enumeration):
+    """Create a test Color enumeration based on the Enumeration class"""
+
+    RED = auto(RGB=(255, 0, 0))
+    GREEN = auto(RGB=(0, 255, 0))
+    BLUE = auto(RGB=(0, 0, 255))
+
+# Ensure that the Colors enumeration subclass is of the expected types
+assert issubclass(Colors, Enumeration)
+
+# Attempt to reconcile a Color against one of its annotations
+color = Colors.reconcile(value=(255, 0, 0), annotation="RGB")
+
+assert isinstance(color, Colors)
+assert isinstance(color, Enumeration)
+
+assert color.name == "RED"
+assert color.value == 1
+assert color.RGB == (255, 0, 0)
+```
+
 # Enumerific Library Enumerations: Classes & Methods
 
 The Enumerific library's `Enumeration` class is a greenfield implementation of enumerations

{enumerific-1.0.5 → enumerific-1.0.7}/README.md

@@ -438,6 +438,11 @@ assert Colors.BLUE.aliased is False
 assert Colors.RED.aliases == [Colors.ROUGE]
 assert Colors.GREEN.aliases == [Colors.VERTE]
 assert Colors.BLUE.aliases == []  # BLUE has not been aliased
+
+# The names including any aliases for an option can be obtained via the .named property
+assert Colors.RED.named == ["RED", "ROUGE"]
+assert Colors.GREEN.named == ["GREEN", "VERTE"]
+assert Colors.BLUE.named == ["BLUE"]
 ```
 
 #### Example 15: Non-Unique Options
@@ -640,6 +645,32 @@ assert Colors.PURPLE.rgb == (255, 0, 255)
 assert Colors.PURPLE.primary is False
 ```
 
+#### Example 19: Reconciling Enumeration Options via Annotations
+
+```python
+from enumerific import Enumeration, auto
+
+class Colors(Enumeration):
+    """Create a test Color enumeration based on the Enumeration class"""
+
+    RED = auto(RGB=(255, 0, 0))
+    GREEN = auto(RGB=(0, 255, 0))
+    BLUE = auto(RGB=(0, 0, 255))
+
+# Ensure that the Colors enumeration subclass is of the expected types
+assert issubclass(Colors, Enumeration)
+
+# Attempt to reconcile a Color against one of its annotations
+color = Colors.reconcile(value=(255, 0, 0), annotation="RGB")
+
+assert isinstance(color, Colors)
+assert isinstance(color, Enumeration)
+
+assert color.name == "RED"
+assert color.value == 1
+assert color.RGB == (255, 0, 0)
+```
+
 # Enumerific Library Enumerations: Classes & Methods
 
 The Enumerific library's `Enumeration` class is a greenfield implementation of enumerations

{enumerific-1.0.5 → enumerific-1.0.7}/source/enumerific/extensible.py

@@ -1458,6 +1458,7 @@ class EnumerationMetaClass(type):
         value: Enumeration | object = None,
         name: str = None,
         caselessly: bool = False,
+        annotation: str = None,
     ) -> Enumeration | None:
         """The 'reconcile' method can be used to reconcile Enumeration type, enumeration
         values, or enumeration names to their matching Enumeration type instances. If a
@@ -1480,7 +1481,23 @@ class EnumerationMetaClass(type):
         reconciled: Enumeration = None
 
         for attribute, enumeration in self._enumerations.items():
-            if isinstance(value, Enumeration):
+            if isinstance(annotation, str):
+                if annotation in enumeration._annotations:
+                    if enumeration._annotations[annotation] is value:
+                        reconciled = enumeration
+                        break
+                    elif enumeration._annotations[annotation] == value:
+                        reconciled = enumeration
+                        break
+                else:
+                    raise EnumerationOptionError(
+                        "The enumeration option, %s, has no '%s' annotation!"
+                        % (
+                            enumeration,
+                            annotation,
+                        )
+                    )
+            elif isinstance(value, Enumeration):
                 if enumeration is value:
                     reconciled = enumeration
                     break
@@ -1797,6 +1814,28 @@ class Enumeration(metaclass=EnumerationMetaClass):
 
         return aliases
 
+    @property
+    def named(self) -> list[str]:
+        logger.debug(
+            "%s.names() >>> id(%s) => %s (%s)",
+            self.__class__.__name__,
+            self,
+            id(self._enumerations),
+            type(self._enumerations),
+        )
+
+        names: list[Enumeration] = [self.name]
+
+        for name, enumeration in self._enumerations.items():
+            logger.debug(" >>> checking for alias: %s => %s", name, enumeration)
+
+            if isinstance(enumeration, Enumeration):
+                if self is enumeration and enumeration.name != name:
+                    if not name in names:
+                        names.append(name)
+
+        return names
+
 
 class EnumerationType(Enumeration, typecast=False):
     """The EnumerationType class represents the type of value held by an enumeration."""

enumerific-1.0.7/source/enumerific/version.txt

@@ -0,0 +1 @@
+1.0.7

{enumerific-1.0.5 → enumerific-1.0.7/source/enumerific.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: enumerific
-Version: 1.0.5
+Version: 1.0.7
 Summary: Simplifies working with Python enums.
 Author: Daniel Sissman
 License-Expression: MIT
@@ -468,6 +468,11 @@ assert Colors.BLUE.aliased is False
 assert Colors.RED.aliases == [Colors.ROUGE]
 assert Colors.GREEN.aliases == [Colors.VERTE]
 assert Colors.BLUE.aliases == []  # BLUE has not been aliased
+
+# The names including any aliases for an option can be obtained via the .named property
+assert Colors.RED.named == ["RED", "ROUGE"]
+assert Colors.GREEN.named == ["GREEN", "VERTE"]
+assert Colors.BLUE.named == ["BLUE"]
 ```
 
 #### Example 15: Non-Unique Options
@@ -670,6 +675,32 @@ assert Colors.PURPLE.rgb == (255, 0, 255)
 assert Colors.PURPLE.primary is False
 ```
 
+#### Example 19: Reconciling Enumeration Options via Annotations
+
+```python
+from enumerific import Enumeration, auto
+
+class Colors(Enumeration):
+    """Create a test Color enumeration based on the Enumeration class"""
+
+    RED = auto(RGB=(255, 0, 0))
+    GREEN = auto(RGB=(0, 255, 0))
+    BLUE = auto(RGB=(0, 0, 255))
+
+# Ensure that the Colors enumeration subclass is of the expected types
+assert issubclass(Colors, Enumeration)
+
+# Attempt to reconcile a Color against one of its annotations
+color = Colors.reconcile(value=(255, 0, 0), annotation="RGB")
+
+assert isinstance(color, Colors)
+assert isinstance(color, Enumeration)
+
+assert color.name == "RED"
+assert color.value == 1
+assert color.RGB == (255, 0, 0)
+```
+
 # Enumerific Library Enumerations: Classes & Methods
 
 The Enumerific library's `Enumeration` class is a greenfield implementation of enumerations

{enumerific-1.0.5 → enumerific-1.0.7}/tests/test_extensible_enums.py

@@ -380,24 +380,57 @@ def test_extensible_enumeration_integer_non_unique():
         BLUE = 3
         ROUGE = 1
 
-    assert (
-        len(Colors) == 4
-    )  # while there are only 3 distinct values, there are 4 options
+    # While there are only 3 distinct values, there are 4 options, due the alias for RED
+    assert len(Colors) == 4
 
-    assert Colors.RED is Colors.ROUGE  # as ROUGE is an alias of RED, identity matches
+    # Ensure that the keys, names, values, items and options methods return as expected
+    assert Colors.keys() == ["RED", "GREEN", "BLUE", "ROUGE"]
+    assert Colors.names() == ["RED", "GREEN", "BLUE", "ROUGE"]
+    assert Colors.values() == [1, 2, 3, 1]
+    assert Colors.items() == [("RED", 1), ("GREEN", 2), ("BLUE", 3), ("ROUGE", 1)]
+    assert Colors.options() == {"RED": 1, "GREEN": 2, "BLUE": 3, "ROUGE": 1}
 
+    # Ensure that the aliased option has the expected identity and equality
+    assert Colors.RED is Colors.ROUGE  # As ROUGE is an alias of RED, identity matches
+    assert Colors.RED == Colors.ROUGE  # As ROUGE is an alias of RED, equality matches
+
+    # Ensure that the property values of RED are as expected
     assert Colors.RED.name == "RED"
     assert Colors.RED.value == 1
+    assert Colors.RED.aliased is True
+    assert Colors.RED.aliases == [Colors.ROUGE]
+    assert Colors.RED.named == ["RED", "ROUGE"]
 
+    # Ensure that the property values of ROUGE are as expected (as an alias of RED)
     assert Colors.ROUGE.name == "RED"
     assert Colors.ROUGE.value == 1
+    assert Colors.ROUGE.aliased is True
+    assert Colors.ROUGE.aliases == [Colors.RED]
+    assert Colors.ROUGE.named == ["RED", "ROUGE"]
+
+    # Ensure that the property values of GREEN are as expected
+    assert Colors.GREEN.name == "GREEN"
+    assert Colors.GREEN.value == 2
+    assert Colors.GREEN.aliased is False
+    assert Colors.GREEN.aliases == []
+    assert Colors.GREEN.named == ["GREEN"]
+
+    # Ensure that the property values of BLUE are as expected
+    assert Colors.BLUE.name == "BLUE"
+    assert Colors.BLUE.value == 3
+    assert Colors.BLUE.aliased is False
+    assert Colors.BLUE.aliases == []
+    assert Colors.BLUE.named == ["BLUE"]
 
+    # We can find the aliases for the Colors enumeration by finding the options with
+    # names that do no match their associated enumeration option name:
     assert [
         name for name, option in Colors.__options__.items() if option.name != name
     ] == [
         "ROUGE"
     ]  # ROUGE is an alias, so its name does not match the option it maps to
 
+    # Ensure that the aliases map is as expected
     assert len(Colors.__aliases__) == 1
     assert Colors.__aliases__ == {"ROUGE": Colors.RED}
     assert list(Colors.__aliases__.items()) == [("ROUGE", Colors.RED)]
@@ -1580,8 +1613,8 @@ def test_membership_in_tuple():
     assert Colors.VIOLET not in colors
 
 
-def test_attribute_access():
-    """Test access to attributes (methods, properties, etc) on an Enumeration subclass"""
+def test_annotation_access():
+    """Test access to annotations (methods, properties, etc) on an Enumeration subclass"""
 
     class Colors(Enumeration, backfill=True):
         """Create a test Color enumeration based on the Enumeration class"""
@@ -1779,3 +1812,32 @@ def test_attribute_access():
     assert color.isMetallic() is False  # isMetallic() is defined on the Colors subclass
     assert color.HEX == "FF0000"  # HEX is a property defined on the Colors subclass
     assert color.count() == 8  # count() is a classmethod defined on the Colors subclass
+
+
+def test_annotation_reconciliation():
+    """Test reconciliation of enumeration options via their annotations."""
+
+    class Colors(Enumeration):
+        """Create a test Color enumeration based on the Enumeration class"""
+
+        RED = auto(RGB=(255, 0, 0))
+        ORANGE = auto(RGB=(255, 165, 0))
+        YELLOW = auto(RGB=(255, 255, 0))
+        GREEN = auto(RGB=(0, 255, 0))
+        BLUE = auto(RGB=(0, 0, 255))
+        VIOLET = auto(RGB=(255, 0, 255))
+
+    # Ensure that the Colors enumeration subclass is of the expected types
+    assert issubclass(Colors, Enumeration)
+    assert issubclass(Colors, EnumerationInteger)
+
+    # Attempt to reconcile a Color against one of its annotations
+    color = Colors.reconcile(value=(255, 0, 0), annotation="RGB")
+
+    assert isinstance(color, Colors)
+    assert isinstance(color, Enumeration)
+    assert isinstance(color, EnumerationInteger)
+
+    assert color.name == "RED"
+    assert color.value == 1
+    assert color.RGB == (255, 0, 0)

enumerific-1.0.5/source/enumerific/version.txt

@@ -1 +0,0 @@
-1.0.5