enumerific 1.0.1__py3-none-any.whl → 1.0.3__py3-none-any.whl

enumerific/extensible.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import typing
+import collections
 
 from enumerific.logging import logger
 
@@ -8,6 +9,7 @@ from enumerific.exceptions import (
     EnumerationError,
     EnumerationOptionError,
     EnumerationSubclassingError,
+    EnumerationExtensibilityError,
     EnumerationNonUniqueError,
 )
 
@@ -17,7 +19,71 @@ from types import MappingProxyType
 logger = logger.getChild(__name__)
 
 
-class auto(int):
+class anno(collections.abc.Mapping):
+    """The annotations class supports adding annotations to an Enumeration option."""
+
+    _value: object = None
+    _annotations: dict[str, object] = None
+
+    def __init__(self, value: object, **annotations: dict[str, object]):
+        self._value: object = value
+
+        for key, value in annotations.items():
+            if not isinstance(key, str):
+                raise TypeError("All annotation values must have string keys!")
+
+        self._annotations: dict[str, object] = annotations
+
+    def __len__(self) -> int:
+        return len(self._annotations)
+
+    def __iter__(self) -> str:
+        for key in self._annotations.keys():
+            yield key
+
+    def __contains__(self, other: object) -> bool:
+        return other in self._annotations
+
+    def __getitem__(self, key: str) -> object | None:
+        if key in self._annotations:
+            return self._annotations[key]
+        else:
+            raise KeyError(f"The annotation does not have an '{key}' item!")
+
+    def __setitem__(self, key: str, value: object):
+        raise NotImplementedError
+
+    def __delitem__(self, key: str, value: object):
+        raise NotImplementedError
+
+    def __getattr__(self, name: str) -> object | None:
+        if name.startswith("_"):
+            return super().__getattr__(name)
+        elif name in self._annotations:
+            return self._annotations[name]
+        else:
+            raise AttributeError(f"The annotation does not have an '{name}' attribute!")
+
+    def __setattr__(self, name: str, value: object):
+        if name.startswith("_"):
+            return super().__setattr__(name, value)
+        else:
+            raise NotImplementedError
+
+    def __detattr__(self, name: str):
+        raise NotImplementedError
+
+    def get(self, name: str, default: object = None) -> object | None:
+        if name in self._annotations:
+            return self._annotations[name]
+        else:
+            return default
+
+    def unwrap(self) -> object:
+        return self._value
+
+
+class auto(int, anno):
     """Generate an automatically inrementing integer each time the class is instantiated
     based on the previously supplied configuration, which allows the start and steps to
     be configured as well as if the integers should be generated as powers/flags."""
@@ -32,6 +98,7 @@ class auto(int):
         cls,
         start: int = None,
         steps: int = None,
+        times: int = None,
         power: int | bool = None,
         flags: bool = None,
     ):
@@ -57,6 +124,15 @@ class auto(int):
                 "The 'steps' argument, if specified, must have a positive integer value!"
             )
 
+        if times is None:
+            times = 0
+        elif isinstance(times, int) and times >= 0:
+            pass
+        else:
+            raise TypeError(
+                "The 'times' argument, if specified, must have a positive integer value!"
+            )
+
         if power is None:
             power = 0
         elif isinstance(power, bool):
@@ -90,17 +166,21 @@ class auto(int):
 
         cls.steps = steps
 
+        cls.times = times
+
         cls.power = power
 
         cls.value = cls.start
 
-    def __new__(cls):
+    def __new__(cls, **annotations: dict[str, object]):
         """Create a new integer (int) instance upon each call, incrementing the value as
         per the configuration defined before this method is called; the configuration
         can be changed at any time and the next call to this method will generate the
         next value based on the most recently specified configuration options."""
 
-        if cls.power > 0:
+        if cls.times > 0:
+            value = cls.value * cls.times
+        elif cls.power > 0:
             value = pow(cls.power, (cls.value - 1))
         else:
             value = cls.value
@@ -109,52 +189,71 @@ class auto(int):
 
         return super().__new__(cls, value)
 
+    def __init__(self, **annotations: dict[str, object]):
+        super().__init__(self.value, **annotations)
+
 
 class EnumerationConfiguration(object):
     """The EnumerationConfiguration class holds the Enumeration configuration options"""
 
     _unique: bool = None
-    _aliased: bool = False
+    _aliased: bool = None
+    _backfill: bool = None
     _overwritable: bool = None
     _removable: bool = None
     _subclassable: bool = None
+    _extensible: bool = None
     _raises: bool = None
     _flags: bool = None
     _start: int = None
+    _steps: int = None
+    _times: int = None
     _typecast: bool = None
 
     def __init__(
         self,
         unique: bool = None,
         aliased: bool = None,
+        backfill: bool = None,
         overwritable: bool = None,
         removable: bool = None,
         subclassable: bool = None,
+        extensible: bool = None,
         raises: bool = None,
         flags: bool = None,
         start: int = None,
+        steps: int = None,
+        times: int = None,
         typecast: bool = None,
     ):
         self.unique = unique
         self.aliased = aliased
+        self.backfill = backfill
         self.overwritable = overwritable
         self.removable = removable
         self.subclassable = subclassable
+        self.extensible = extensible
         self.raises = raises
         self.flags = flags
         self.start = start
+        self.steps = steps
+        self.times = times
         self.typecast = typecast
 
     def __dir__(self) -> list[str]:
         return [
             "unique",
             "aliased",
+            "backfill",
             "overwritable",
             "removable",
             "subclassable",
+            "extensible",
             "raises",
             "flags",
             "start",
+            "steps",
+            "times",
             "typecast",
         ]
 
@@ -220,6 +319,20 @@ class EnumerationConfiguration(object):
             )
         self._aliased = aliased
 
+    @property
+    def backfill(self) -> bool | None:
+        return self._backfill
+
+    @backfill.setter
+    def backfill(self, backfill: bool | None):
+        if backfill is None:
+            pass
+        elif not isinstance(backfill, bool):
+            raise TypeError(
+                "The 'backfill' argument, if specified, must have a boolean value!"
+            )
+        self._backfill = backfill
+
     @property
     def overwritable(self) -> bool | None:
         return self._overwritable
@@ -262,6 +375,20 @@ class EnumerationConfiguration(object):
             )
         self._subclassable = subclassable
 
+    @property
+    def extensible(self) -> bool | None:
+        return self._extensible
+
+    @extensible.setter
+    def extensible(self, extensible: bool | None):
+        if extensible is None:
+            pass
+        elif not isinstance(extensible, bool):
+            raise TypeError(
+                "The 'extensible' argument, if specified, must have a boolean value!"
+            )
+        self._extensible = extensible
+
     @property
     def raises(self) -> bool | None:
         return self._raises
@@ -291,7 +418,7 @@ class EnumerationConfiguration(object):
         self._flags = flags
 
     @property
-    def start(self) -> bool | None:
+    def start(self) -> int | None:
         return self._start
 
     @start.setter
@@ -304,6 +431,34 @@ class EnumerationConfiguration(object):
             )
         self._start = start
 
+    @property
+    def steps(self) -> int | None:
+        return self._steps
+
+    @steps.setter
+    def steps(self, steps: int | None):
+        if steps is None:
+            pass
+        elif not (isinstance(steps, int) and steps >= 0):
+            raise TypeError(
+                "The 'steps' argument, if specified, must have a positive integer value!"
+            )
+        self._steps = steps
+
+    @property
+    def times(self) -> int | None:
+        return self._times
+
+    @times.setter
+    def times(self, times: int | None):
+        if times is None:
+            pass
+        elif not (isinstance(times, int) and times >= 0):
+            raise TypeError(
+                "The 'times' argument, if specified, must have a positive integer value!"
+            )
+        self._times = times
+
     @property
     def typecast(self) -> bool | None:
         return self._typecast
@@ -345,12 +500,16 @@ class EnumerationMetaClass(type):
         bases: tuple[type],
         unique: bool = None,
         aliased: bool = None,
+        backfill: bool = None,
         overwritable: bool = None,
         subclassable: bool = None,
+        extensible: bool = None,
         removable: bool = None,
         raises: bool = None,
         flags: bool = None,
         start: int = None,
+        steps: int = None,
+        times: int = None,
         typecast: bool = None,
         **kwargs,
     ) -> dict:
@@ -361,18 +520,22 @@ class EnumerationMetaClass(type):
         any other keyword arguments that are included in the class signature call."""
 
         logger.debug(
-            "[EnumerationMetaClass] %s.__prepare__(name: %s, bases: %s, unique: %s, aliased: %s, overwritable: %s, subclassable: %s, removable: %s, raises: %s, flags: %s, start: %s, typecast: %s, kwargs: %s)",
+            "[EnumerationMetaClass] %s.__prepare__(name: %s, bases: %s, unique: %s, aliased: %s, backfill: %s, overwritable: %s, subclassable: %s, extensible: %s, removable: %s, raises: %s, flags: %s, start: %s, steps: %s, times: %s, typecast: %s, kwargs: %s)",
             name,
             name,
             bases,
             unique,
             aliased,
+            backfill,
             overwritable,
             subclassable,
+            extensible,
             removable,
             raises,
             flags,
             start,
+            steps,
+            times,
             typecast,
             kwargs,
         )
@@ -430,9 +593,27 @@ class EnumerationMetaClass(type):
                 "The 'start' argument, if specified, must have a positive integer value!"
             )
 
+        if steps is None:
+            pass
+        elif isinstance(steps, int) and steps >= 1:
+            pass
+        else:
+            raise TypeError(
+                "The 'steps' argument, if specified, must have a positive integer value!"
+            )
+
+        if times is None:
+            pass
+        elif isinstance(times, int) and times >= 1:
+            pass
+        else:
+            raise TypeError(
+                "The 'times' argument, if specified, must have a positive integer value!"
+            )
+
         # Configure the auto() class for subsequent use, resetting the sequence, setting
         # the new start value, and whether values should be flag values (powers of 2)
-        auto.configure(start=start, flags=flags)
+        auto.configure(start=start, steps=steps, times=times, flags=flags)
 
         return dict()
 
@@ -441,12 +622,16 @@ class EnumerationMetaClass(type):
         *args,
         unique: bool = None,  # True
         aliased: bool = None,  # False
+        backfill: bool = None,  # False
         overwritable: bool = None,  # False
         subclassable: bool = None,  # True
+        extensible: bool = None,  # True
         removable: bool = None,  # False
         raises: bool = None,  # False
         flags: bool = None,  # False
         start: int = None,  # None
+        steps: int = None,  # None
+        times: int = None,  # None
         typecast: bool = None,  # True
         **kwargs,
     ):
@@ -471,6 +656,13 @@ class EnumerationMetaClass(type):
                 "The 'aliased' argument, if specified, must have a boolean value!"
             )
 
+        if backfill is None:
+            pass
+        elif not isinstance(backfill, bool):
+            raise TypeError(
+                "The 'backfill' argument, if specified, must have a boolean value!"
+            )
+
         if overwritable is None:
             pass
         elif not isinstance(overwritable, bool):
@@ -485,6 +677,13 @@ class EnumerationMetaClass(type):
                 "The 'subclassable' argument, if specified, must have a boolean value!"
             )
 
+        if extensible is None:
+            pass
+        elif not isinstance(extensible, bool):
+            raise TypeError(
+                "The 'extensible' argument, if specified, must have a boolean value!"
+            )
+
         if removable is None:
             pass
         elif not isinstance(removable, bool):
@@ -513,6 +712,20 @@ class EnumerationMetaClass(type):
                 "The 'start' argument, if specified, must have a positive integer value!"
             )
 
+        if steps is None:
+            pass
+        elif not (isinstance(steps, int) and steps >= 0):
+            raise TypeError(
+                "The 'steps' argument, if specified, must have a positive integer value!"
+            )
+
+        if times is None:
+            pass
+        elif not (isinstance(times, int) and times >= 0):
+            raise TypeError(
+                "The 'times' argument, if specified, must have a positive integer value!"
+            )
+
         if typecast is None:
             pass
         elif not isinstance(typecast, bool):
@@ -523,12 +736,16 @@ class EnumerationMetaClass(type):
         configuration = EnumerationConfiguration(
             unique=unique,
             aliased=aliased,
+            backfill=backfill,
             overwritable=overwritable,
             subclassable=subclassable,
+            extensible=extensible,
             removable=removable,
             raises=raises,
             flags=flags,
             start=start,
+            steps=steps,
+            times=times,
             typecast=typecast,
         )
 
@@ -543,6 +760,7 @@ class EnumerationMetaClass(type):
             return super().__new__(cls, *args, **kwargs)
 
         enumerations: dict[str, object] = {}  # Keep track of the enumeration options
+        annotations: dict[str, dict] = {}  # Keep track of the enumeration annotations
 
         names: list[object] = []  # Keep track of the option names to check uniqueness
         values: list[object] = []  # Keep track of the option values to check uniqueness
@@ -587,12 +805,18 @@ class EnumerationMetaClass(type):
                         logger.debug(
                             " >>> aliased      => %s", base_configuration.aliased
                         )
+                        logger.debug(
+                            " >>> backfill     => %s", base_configuration.backfill
+                        )
                         logger.debug(
                             " >>> overwritable => %s", base_configuration.overwritable
                         )
                         logger.debug(
                             " >>> subclassable => %s", base_configuration.subclassable
                         )
+                        logger.debug(
+                            " >>> extensible   => %s", base_configuration.extensible
+                        )
                         logger.debug(
                             " >>> removable    => %s", base_configuration.removable
                         )
@@ -605,13 +829,22 @@ class EnumerationMetaClass(type):
                         logger.debug(
                             " >>> start        => %s", base_configuration.start
                         )
+                        logger.debug(
+                            " >>> steps        => %s", base_configuration.steps
+                        )
+                        logger.debug(
+                            " >>> times        => %s", base_configuration.times
+                        )
                         logger.debug(
                             " >>> typecast     => %s", base_configuration.typecast
                         )
 
-                        if base_configuration.subclassable is False:
+                        if (
+                            base_configuration.subclassable is False
+                            or base_configuration.extensible is False
+                        ):
                             raise EnumerationSubclassingError(
-                                "The '%s' enumeration class cannot be subclassed when the keyword argument 'subclassable=False' was passed to the class constructor!"
+                                "The '%s' enumeration class cannot be subclassed when the keyword arguments 'subclassable=False' or 'extensible=False` are passed to the class constructor!"
                                 % (base.__name__)
                             )
 
@@ -626,6 +859,9 @@ class EnumerationMetaClass(type):
                         logger.debug(
                             " >>> (updated) aliased      => %s", configuration.aliased
                         )
+                        logger.debug(
+                            " >>> (updated) backfill     => %s", configuration.backfill
+                        )
                         logger.debug(
                             " >>> (updated) overwritable => %s",
                             configuration.overwritable,
@@ -634,6 +870,10 @@ class EnumerationMetaClass(type):
                             " >>> (updated) subclassable => %s",
                             configuration.subclassable,
                         )
+                        logger.debug(
+                            " >>> (updated) extensible => %s",
+                            configuration.extensible,
+                        )
                         logger.debug(
                             " >>> (updated) removable    => %s", configuration.removable
                         )
@@ -646,6 +886,12 @@ class EnumerationMetaClass(type):
                         logger.debug(
                             " >>> (updated) start        => %s", configuration.start
                         )
+                        logger.debug(
+                            " >>> (updated) steps        => %s", configuration.steps
+                        )
+                        logger.debug(
+                            " >>> (updated) times        => %s", configuration.times
+                        )
                         logger.debug(
                             " >>> (updated) typecast     => %s", configuration.typecast
                         )
@@ -653,7 +899,6 @@ class EnumerationMetaClass(type):
                     # logger.debug(" >>> found base (%s) that is an instance of EnumerationMetaClass and a subclass of Enumeration" % (base))
 
                     if not (base is Enumeration or Enumeration in base.__bases__):
-                        # enumerations = base._enumerations  # reference to the _enumerations dictionary
                         _enumerations = base._enumerations
 
                     logger.debug("  >>> enumerations => %s" % (base._enumerations))
@@ -675,29 +920,37 @@ class EnumerationMetaClass(type):
         configuration.defaults(
             unique=True,
             aliased=False,
+            backfill=False,
             overwritable=False,
             subclassable=True,
+            extensible=True,
             removable=False,
             raises=False,
             flags=False,
             start=1,
+            steps=1,
+            times=None,
             typecast=True,
         )
 
         logger.debug(" >>> (after defaults) unique       => %s", configuration.unique)
         logger.debug(" >>> (after defaults) aliased      => %s", configuration.aliased)
+        logger.debug(" >>> (after defaults) backfill     => %s", configuration.backfill)
         logger.debug(
             " >>> (after defaults) overwritable => %s", configuration.overwritable
         )
         logger.debug(
             " >>> (after defaults) subclassable => %s", configuration.subclassable
         )
+        logger.debug(" >>> (after defaults) extensible => %s", configuration.extensible)
         logger.debug(
             " >>> (after defaults) removable    => %s", configuration.removable
         )
         logger.debug(" >>> (after defaults) raises       => %s", configuration.raises)
         logger.debug(" >>> (after defaults) flags        => %s", configuration.flags)
         logger.debug(" >>> (after defaults) start        => %s", configuration.start)
+        logger.debug(" >>> (after defaults) steps        => %s", configuration.steps)
+        logger.debug(" >>> (after defaults) times        => %s", configuration.times)
         logger.debug(" >>> (after defaults) typecast     => %s", configuration.typecast)
 
         # Iterate over the class attributes, looking for any enumeration options
@@ -709,6 +962,12 @@ class EnumerationMetaClass(type):
                 % (index, attribute, value, type(value))
             )
 
+            if isinstance(value, auto):
+                annotations[attribute] = value
+            elif isinstance(value, anno):
+                annotations[attribute] = value
+                value = value.unwrap()  # unwrap the annotated value
+
             if attribute.startswith("_") or attribute in cls._special:
                 continue
             elif attribute in names:
@@ -730,8 +989,8 @@ class EnumerationMetaClass(type):
                     )
                 else:
                     raise EnumerationNonUniqueError(
-                        "The enumeration option, '%s', has a non-unique value, %r, however, unless either the keyword argument 'unique=False' or 'aliased=True' are passed during class construction, all enumeration options must have unique values!"
-                        % (attribute, value)
+                        "The enumeration option, '%s', has a non-unique value, %r, however, unless either the keyword argument 'unique=False' or 'aliased=True' are passed during class construction, all enumeration options must have unique values; existing values: %s!"
+                        % (attribute, value, values)
                     )
             else:
                 logger.debug(
@@ -763,6 +1022,8 @@ class EnumerationMetaClass(type):
         if isinstance(_enumerations, dict):
             attributes["base_enumerations"] = _enumerations
 
+        attributes["annotations"] = annotations
+
         # If the new enumeration class is not subclassing an existing enumeration class
         if configuration.typecast is True and (
             (baseclass is None) or (baseclass is Enumeration)
@@ -815,31 +1076,26 @@ class EnumerationMetaClass(type):
 
         logger.debug(" >>> bases         => %s", [base for base in bases])
 
-        # if "EnumerationInteger" in globals():
-        #     if EnumerationInteger in bases and EnumerationFlag in bases:
-        #         bases = tuple([base for base in bases if not EnumerationInteger])
-
         args: tuple[object] = (name, bases, attributes)
 
         # Create the new enumeration class instance
         instance = super().__new__(cls, *args, **kwargs)
 
-        # logger.debug(
-        # " >>> metaclass => %s (base: %s, type: %s, bases: %s)\n"
-        # % (enumclass, instance, type(instance), instance.__bases__)
-        # )
-        # logger.debug(" >>> metaclass => %s (base: %s, type: %s, bases: %s)\n" % (enumclass, instance, type(instance), instance.__bases__))
-
         logger.debug(" >>> baseclass     => %s", baseclass)
         logger.debug(" >>> instance      => %s", instance)
 
         logger.debug(" >>> unique        => %s", configuration.unique)
         logger.debug(" >>> aliased       => %s", configuration.aliased)
+        logger.debug(" >>> backfill      => %s", configuration.backfill)
         logger.debug(" >>> overwritable  => %s", configuration.overwritable)
         logger.debug(" >>> subclassable  => %s", configuration.subclassable)
+        logger.debug(" >>> extensible    => %s", configuration.extensible)
         logger.debug(" >>> removable     => %s", configuration.removable)
         logger.debug(" >>> raises        => %s", configuration.raises)
         logger.debug(" >>> flags         => %s", configuration.flags)
+        logger.debug(" >>> start         => %s", configuration.start)
+        logger.debug(" >>> steps         => %s", configuration.steps)
+        logger.debug(" >>> times         => %s", configuration.times)
         logger.debug(" >>> typecast      => %s", configuration.typecast)
 
         # Store the enumeration class configuration options for future reference
@@ -862,7 +1118,16 @@ class EnumerationMetaClass(type):
         )
 
         if isinstance(base_enumerations := attributes.get("base_enumerations"), dict):
-            self._enumerations: dict[str, Enumeration] = base_enumerations
+            if (
+                self._configuration.backfill is True
+                and self._configuration.extensible is True
+            ):
+                self._enumerations: dict[str, Enumeration] = base_enumerations
+            else:
+                self._enumerations: dict[str, Enumeration] = {}
+
+                for enumeration_name, enumeration in base_enumerations.items():
+                    self._enumerations[enumeration_name] = enumeration
         else:
             self._enumerations: dict[str, Enumeration] = {}
 
@@ -876,6 +1141,8 @@ class EnumerationMetaClass(type):
         logger.debug("+" * 100)
 
         if isinstance(enumerations := attributes.get("enumerations"), dict):
+            annotations: dict[str, anno] = attributes.get("annotations") or {}
+
             for attribute, value in enumerations.items():
                 if attribute in self._enumerations:
                     continue
@@ -913,6 +1180,7 @@ class EnumerationMetaClass(type):
                             enumeration=self,
                             name=attribute,
                             value=value,
+                            annotations=annotations.get(attribute),
                         )
 
                 logger.debug(
@@ -935,24 +1203,32 @@ class EnumerationMetaClass(type):
         elif self._enumerations and name in self._enumerations:
             return self._enumerations[name]
         else:
+            # EnumerationOptionError subclasses AttributeError so we adhere to convention
             raise EnumerationOptionError(
-                "The '%s' enumeration class, has no '%s' enumeration option!"
+                "The '%s' enumeration class, has no '%s' enumeration option nor annotation property!"
                 % (self.__name__, name)
             )
 
     def __dir__(self) -> list[str]:
-        members: list[str] = []
-
-        for name, enumeration in self._enumerations.items():
-            members.append(name)
+        members: set[str] = set()
 
         for member in object.__dir__(self):
             if member.startswith("_") or member in self._special:
-                members.append(member)
+                members.add(member)
+
+        for name, enumeration in self._enumerations.items():
+            members.add(name)
 
-        return members
+        for member in vars(self):
+            members.add(member)
+
+        return list(members)
 
     def __contains__(self, other: Enumeration | object) -> bool:
+        logger.debug(
+            "%s(%s).__contains__(other: %s)", self.__class__.__name__, self, other
+        )
+
         contains: bool = False
 
         for name, enumeration in self._enumerations.items():
@@ -1132,6 +1408,12 @@ class EnumerationMetaClass(type):
             value,
         )
 
+        if self.configuration.extensible is False:
+            raise EnumerationExtensibilityError(
+                "The '%s' enumeration class has been configured to prevent extensibility, so cannot be extended with new options either through registration or subclassing, so the '%s' option cannot be registered!"
+                % (self.__name__, name)
+            )
+
         if self.configuration.overwritable is False and name in self._enumerations:
             raise EnumerationNonUniqueError(
                 "The '%s' enumeration class already has an option named '%s', so a new option with the same name cannot be created unless the 'overwritable=True' argument is passed during class construction!"
@@ -1175,11 +1457,12 @@ class EnumerationMetaClass(type):
         self,
         value: Enumeration | object = None,
         name: str = None,
+        caselessly: bool = False,
     ) -> 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
-        match is found the Enumeration type instance will be returned otherwise None
-        will be returned."""
+        match is found the Enumeration type instance will be returned otherwise None will
+        be returned, unless the class is configured to raise an error for mismatches."""
 
         if name is None and value is None:
             raise ValueError(
@@ -1197,14 +1480,20 @@ class EnumerationMetaClass(type):
         reconciled: Enumeration = None
 
         for attribute, enumeration in self._enumerations.items():
-            if isinstance(name, str) and enumeration.name == name:
-                reconciled = enumeration
-                break
-            elif isinstance(value, Enumeration):
+            if isinstance(value, Enumeration):
                 if enumeration is value:
                     reconciled = enumeration
                     break
-            elif isinstance(value, str) and enumeration.name == value:
+            elif isinstance(name, str) and (
+                (enumeration.name == name)
+                or (caselessly and (enumeration.name.casefold() == name.casefold()))
+            ):
+                reconciled = enumeration
+                break
+            elif isinstance(value, str) and (
+                (enumeration.name == value)
+                or (caselessly and (enumeration.name.casefold() == value.casefold()))
+            ):
                 reconciled = enumeration
                 break
             elif enumeration.value == value:
@@ -1229,6 +1518,14 @@ class EnumerationMetaClass(type):
                     )
                 )
 
+        # When an enumeration option is reconciled, it may be defined in another class
+        # but have been accessed through a subclass; in order for attribute lookups to
+        # work within the subclass, we need to provide the current lookup context to the
+        # reconciled enumeration option, so that any attribute access on this object can
+        # perform their lookup in the correct part of the class hierarchy
+        if isinstance(reconciled, Enumeration):
+            reconciled._context = self
+
         return reconciled
 
     def validate(self, value: Enumeration | object = None, name: str = None) -> bool:
@@ -1238,13 +1535,20 @@ class EnumerationMetaClass(type):
 
         return not self.reconcile(value=value, name=name) is None
 
+    def options(self) -> MappingProxyType[str, Enumeration]:
+        """The 'options' method returns a read-only mapping proxy of the options."""
+
+        return MappingProxyType(self._enumerations)
+
 
 class Enumeration(metaclass=EnumerationMetaClass):
     """The Enumeration class is the subclass of all enumerations and their subtypes."""
 
     _metaclass: EnumerationMetaClass = None
+    _context: EnumerationMetaClass = None
     _enumeration: Enumeration = None
     _enumerations: dict[str, Enumeration] = None
+    _annotations: anno = None
     _name: str = None
     _value: object = None
     _aliased: Enumeration = None
@@ -1257,6 +1561,7 @@ class Enumeration(metaclass=EnumerationMetaClass):
         name: str = None,
         value: object = None,
         aliased: Enumeration = None,
+        annotations: anno = None,
         **kwargs,
     ) -> Enumeration | None:
         # Supports reconciling enumeration options via their name/value via __new__ call
@@ -1264,12 +1569,14 @@ class Enumeration(metaclass=EnumerationMetaClass):
             value = args[0]
 
         logger.debug(
-            "[Enumeration] %s.__new__(args: %s, enumeration: %s, name: %s, value: %s, kwargs: %s)",
+            "[Enumeration] %s.__new__(args: %s, enumeration: %s, name: %s, value: %s, aliased: %s, annotations: %s, kwargs: %s)",
             cls.__name__,
             args,
             enumeration,
             name,
             value,
+            aliased,
+            annotations,
             kwargs,
         )
 
@@ -1298,15 +1605,18 @@ class Enumeration(metaclass=EnumerationMetaClass):
         name: str = None,
         value: object = None,
         aliased: Enumeration = None,
+        annotations: anno = None,
         **kwargs,
     ) -> None:
         logger.debug(
-            "[Enumeration] %s.__init__(args: %s, enumeration: %s, name: %s, value: %s, kwargs: %s)",
+            "[Enumeration] %s.__init__(args: %s, enumeration: %s, name: %s, value: %s, aliased: %s, annotations: %s, kwargs: %s)",
             self.__class__.__name__,
             args,
             enumeration,
             name,
             value,
+            aliased,
+            annotations,
             kwargs,
         )
 
@@ -1340,6 +1650,15 @@ class Enumeration(metaclass=EnumerationMetaClass):
                 "The 'aliased' argument, if specified, must reference an Enumeration class instance!"
             )
 
+        if annotations is None:
+            pass
+        elif isinstance(annotations, anno):
+            self._annotations = annotations
+        else:
+            raise TypeError(
+                "The 'annotations' argument, if specified, must reference an anno class instance!"
+            )
+
     # NOTE: This method is only called if the instance is called via instance(..) syntax
     def __call__(self, *args, **kwargs) -> Enumeration | None:
         logger.debug(
@@ -1361,32 +1680,51 @@ class Enumeration(metaclass=EnumerationMetaClass):
         return id(self)
 
     def __eq__(self, other: Enumeration | object) -> bool:
-        logger.debug("%s.__eq__(other: %s)" % (self.__class__.__name__, other))
+        logger.debug("%s(%s).__eq__(other: %s)", self.__class__.__name__, self, other)
 
         equals: bool = False
 
         if isinstance(other, Enumeration):
-            if self is other:
-                return True
+            equals = self is other
+        elif self.name == other:
+            equals = True
+        elif self.value == other:
+            equals = True
 
-        for attribute, enumeration in self._enumerations.items():
-            logger.info(
-                "%s.__eq__(other: %s) enumeration => %s"
-                % (self.__class__.__name__, other, enumeration)
+        return equals
+
+    def __getattr__(self, name) -> object:
+        """The '__getattr__' method provides support for accessing attribute values that
+        have been assigned to the current enumeration option. If a matching attribute can
+        be found, its value will be returned, otherwise an exception will be raised."""
+
+        logger.debug("%s.__getattr__(name: %s)", self.__class__.__name__, name)
+
+        if name.startswith("_") or name in self.__class__._special or name in dir(self):
+            return object.__getattribute__(self, name)
+        elif self._enumerations and name in self._enumerations:
+            return self._enumerations[name]
+        elif self._annotations and name in self._annotations:
+            return self._annotations[name]
+        elif self._context and name in dir(self._context):
+            return object.__getattribute__(self._context, name)
+        else:
+            # EnumerationOptionError subclasses AttributeError so we adhere to convention
+            raise EnumerationOptionError(
+                "The '%s' enumeration class, has no '%s' enumeration option nor annotation property!"
+                % (self.__class__.__name__, name)
             )
 
-            if isinstance(other, Enumeration):
-                if enumeration is other:
-                    equals = True
-                    break
-            elif enumeration.value == other:
-                equals = True
-                break
-            elif enumeration.name == other:
-                equals = True
-                break
+    def get(self, name: str, default: object = None) -> object | None:
+        """The 'get' method provides support for accessing annotation values that may
+        have been assigned to the current enumeration option. If a matching annotation
+        can be found, its value will be returned, otherwise the default value will be
+        returned, which defaults to None, but may be specified as any value."""
 
-        return equals
+        if name in self._annotations:
+            return self._annotations[name]
+        else:
+            return default
 
     @property
     def enumeration(self) -> Enumeration:
@@ -1407,21 +1745,43 @@ class Enumeration(metaclass=EnumerationMetaClass):
     @property
     def aliased(self) -> bool:
         logger.debug(
-            "%s.aliased() >>> id(Colors._enumerations) => %s (%s)",
+            "%s.aliased() >>> id(%s) => %s (%s)",
             self.__class__.__name__,
+            self,
             id(self._enumerations),
             type(self._enumerations),
         )
 
         for name, enumeration in self._enumerations.items():
-            logger.info(" >>> checking for alias: %s => %s", name, enumeration)
+            logger.debug(" >>> checking for alias: %s => %s", name, enumeration)
 
             if isinstance(enumeration, Enumeration):
-                if name != enumeration.name:
+                if self is enumeration and enumeration.name != name:
                     return True
 
         return False
 
+    @property
+    def aliases(self) -> list[Enumeration]:
+        logger.debug(
+            "%s.aliases() >>> id(%s) => %s (%s)",
+            self.__class__.__name__,
+            self,
+            id(self._enumerations),
+            type(self._enumerations),
+        )
+
+        aliases: list[Enumeration] = []
+
+        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:
+                    aliases.append(enumeration)
+
+        return aliases
+
 
 class EnumerationType(Enumeration, typecast=False):
     """The EnumerationType class represents the type of value held by an enumeration."""
@@ -1462,6 +1822,15 @@ class EnumerationInteger(int, Enumeration):
     def __repr__(self) -> str:
         return Enumeration.__repr__(self)
 
+    def __hash__(self) -> id:
+        return super().__hash__()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (int, self.__class__)):
+            return super().__eq__(other)
+        else:
+            return Enumeration.__eq__(self, other)
+
 
 class EnumerationFloat(float, Enumeration):
     """An Enumeration subclass where all values are float values."""
@@ -1505,6 +1874,15 @@ class EnumerationComplex(complex, Enumeration):
     def __repr__(self) -> str:
         return Enumeration.__repr__(self)
 
+    def __hash__(self) -> id:
+        return super().__hash__()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (float, self.__class__)):
+            return super().__eq__(other)
+        else:
+            return Enumeration.__eq__(self, other)
+
 
 class EnumerationString(str, Enumeration):
     """An Enumeration subclass where all values are string values."""
@@ -1528,6 +1906,15 @@ class EnumerationString(str, Enumeration):
     def __repr__(self) -> str:
         return Enumeration.__repr__(self)
 
+    def __hash__(self) -> id:
+        return super().__hash__()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (str, self.__class__)):
+            return super().__eq__(other)
+        else:
+            return Enumeration.__eq__(self, other)
+
 
 class EnumerationBytes(bytes, Enumeration):
     """An Enumeration subclass where all values are bytes values."""
@@ -1548,6 +1935,15 @@ class EnumerationBytes(bytes, Enumeration):
     def __repr__(self) -> str:
         return Enumeration.__repr__(self)
 
+    def __hash__(self) -> id:
+        return super().__hash__()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (bytes, self.__class__)):
+            return super().__eq__(other)
+        else:
+            return Enumeration.__eq__(self, other)
+
 
 class EnumerationTuple(tuple, Enumeration):
     """An Enumeration subclass where all values are tuple values."""
@@ -1568,6 +1964,15 @@ class EnumerationTuple(tuple, Enumeration):
     def __repr__(self) -> str:
         return Enumeration.__repr__(self)
 
+    def __hash__(self) -> id:
+        return super().__hash__()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (tuple, self.__class__)):
+            return super().__eq__(other)
+        else:
+            return Enumeration.__eq__(self, other)
+
 
 class EnumerationSet(set, Enumeration):
     """An Enumeration subclass where all values are set values."""
@@ -1588,6 +1993,15 @@ class EnumerationSet(set, Enumeration):
     def __repr__(self) -> str:
         return Enumeration.__repr__(self)
 
+    def __hash__(self) -> id:
+        return super().__hash__()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (set, self.__class__)):
+            return super().__eq__(other)
+        else:
+            return Enumeration.__eq__(self, other)
+
 
 class EnumerationList(list, Enumeration):
     """An Enumeration subclass where all values are list values."""
@@ -1608,6 +2022,15 @@ class EnumerationList(list, Enumeration):
     def __repr__(self) -> str:
         return Enumeration.__repr__(self)
 
+    def __hash__(self) -> id:
+        return super().__hash__()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (list, self.__class__)):
+            return super().__eq__(other)
+        else:
+            return Enumeration.__eq__(self, other)
+
 
 class EnumerationDictionary(dict, Enumeration):
     """An Enumeration subclass where all values are dictionary values."""
@@ -1631,6 +2054,15 @@ class EnumerationDictionary(dict, Enumeration):
     def __repr__(self) -> str:
         return Enumeration.__repr__(self)
 
+    def __hash__(self) -> id:
+        return super().__hash__()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (dict, self.__class__)):
+            return super().__eq__(other)
+        else:
+            return Enumeration.__eq__(self, other)
+
 
 class EnumerationFlag(int, Enumeration):
     """An Enumeration subclass where all values are integer values to the power of 2."""
@@ -1772,6 +2204,15 @@ class EnumerationFlag(int, Enumeration):
     def __repr__(self) -> str:
         return Enumeration.__repr__(self)
 
+    def __hash__(self) -> id:
+        return super().__hash__()
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (int, self.__class__)):
+            return super().__eq__(other)
+        else:
+            return Enumeration.__eq__(self, other)
+
     def __or__(self, other: EnumerationFlag):  # called for: "a | b" (bitwise or)
         """Support performing a bitwise or between the current EnumerationFlag
         instance's bitmask and the 'other' provided EnumerationFlag's bitmask;