fix #86

Author: bckohan

doc/source/changelog.rst

@@ -2,6 +2,11 @@
 Change Log
 ==========
 
+v2.3.0 (2025-03-29)
+===================
+
+* Implemented `Need a way to distinguish symmetric properties from first class aliases. <https://github.com/bckohan/enum-properties/issues/86>`_
+
 v2.2.5 (2025-03-22)
 ===================
 

doc/source/howto.rst

@@ -282,6 +282,18 @@ enumeration for the following reasons:**
 .. literalinclude:: ../../tests/examples/howto_dataclass_integration.py
 
 
+.. _howto_members_and_aliases:
+Get members and aliases
+-----------------------
+
+Symmetric properties are added to the :attr:`~enum.EnumType.__members__` attribute,
+and alias members do not appear in :attr:`~enum.Enum._member_names_`. To get a list
+of first class members and aliases use
+:attr:`~enum_properties.EnumProperties.__first_class_members__`. This class member may
+also be overridden if you wish to customize this behavior for users.
+
+.. literalinclude:: ../../tests/examples/howto_members_and_aliases.py
+
 .. _howto_hash_equivalency:
 
 Define hash equivalent enums

doc/source/reference.rst

@@ -14,3 +14,4 @@ Module
    :undoc-members:
    :show-inheritance:
    :private-members:
+   :special-members: __first_class_members__

justfile

@@ -130,6 +130,28 @@ check-docs-links: _link_check
 check-docs:
     @just run doc8 --ignore-path ./doc/build --max-line-length 100 -q ./doc
 
+# fetch the intersphinx references for the given package
+[script]
+fetch-refs LIB: install-docs
+    import os
+    from pathlib import Path
+    import logging as _logging
+    import sys
+    import runpy
+    from sphinx.ext.intersphinx import inspect_main
+    _logging.basicConfig()
+
+    libs = runpy.run_path(Path(os.getcwd()) / "doc/source/conf.py").get("intersphinx_mapping")
+    url = libs.get("{{ LIB }}", None)
+    if not url:
+        sys.exit(f"Unrecognized {{ LIB }}, must be one of: {', '.join(libs.keys())}")
+    if url[1] is None:
+        url = f"{url[0].rstrip('/')}/objects.inv"
+    else:
+        url = url[1]
+
+    raise SystemExit(inspect_main([url]))
+
 # lint the code
 check-lint:
     @just run ruff check --select I

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "enum-properties"
-version = "2.2.5"
+version = "2.3.0"
 description = "Add properties and method specializations to Python enumeration values with a simple declarative syntax."
 requires-python = ">=3.8,<4.0"
 authors = [

src/enum_properties/__init__.py

@@ -19,7 +19,7 @@
 from dataclasses import dataclass
 from functools import cached_property
 
-VERSION = (2, 2, 5)
+VERSION = (2, 3, 0)
 
 __title__ = "Enum Properties"
 __version__ = ".".join(str(i) for i in VERSION)
@@ -230,6 +230,38 @@ class SymmetricMixin(with_typehint("EnumProperties")):  # type: ignore
     property will be a case sensitive symmetric property.
     """
 
+    _ep_symmetric_map_: t.Dict[t.Any, enum.Enum]
+    """
+    The case sensitive mapping of symmetric values to enumeration values.
+    """
+
+    _ep_isymmetric_map_: t.Dict[str, enum.Enum]
+    """
+    The case insensitive mapping of symmetric values to enumeration values.
+    """
+
+    _ep_coerce_types_: t.List[t.Type[t.Any]]
+    """
+    On instantiation, if _missing_ is invoked a coercion attempt will be made to each
+    of these types before failure.
+    """
+
+    _num_sym_props_: int
+    """
+    The number of symmetric properties on this enumeration.
+    """
+
+    _properties_: t.List[_Prop]
+    """
+    List of properties defined on the enumeration class.
+    """
+
+    __first_class_members__: t.List[str]
+    """
+    The list of first class members - this includes all members and aliases. May be
+    overridden.
+    """
+
     def __eq__(self, value: t.Any) -> bool:
         """Symmetric equality - try to coerce value before failure"""
         if isinstance(value, self.__class__):
@@ -346,6 +378,7 @@ class MyEnum(SymmetricMixin, enum.Enum, metaclass=EnumPropertiesMeta):
     # members reserved for use by EnumProperties
     RESERVED = [
         "_properties_",
+        "_num_sym_props_",
         "_ep_coerce_types_",
         "_ep_symmetric_map_",
         "_ep_isymmetric_map_",
@@ -354,7 +387,9 @@ class MyEnum(SymmetricMixin, enum.Enum, metaclass=EnumPropertiesMeta):
     _ep_symmetric_map_: t.Dict[t.Any, enum.Enum]
     _ep_isymmetric_map_: t.Dict[str, enum.Enum]
     _ep_coerce_types_: t.List[t.Type[t.Any]]
+    _num_sym_props_: int
     _properties_: t.List[_Prop]
+    __first_class_members__: t.List[str]
 
     @classmethod
     def __prepare__(mcs, cls, bases, **kwargs):
@@ -396,6 +431,7 @@ class _PropertyEnumDict(class_dict.__class__):  # type: ignore[name-defined]
             _ids_: t.Dict[int, str] = {}
             _member_names: t.Union[t.List[str], t.Dict[str, t.Any]]
             _create_properties_: bool = False
+            __first_class_members__: t.List[str] = []
 
             class AnnotationPropertyRecorder(dict):
                 class_dict: "_PropertyEnumDict"
@@ -479,6 +515,7 @@ def __setitem__(self, key, value):
                         # todo remove below when minimum python >= 3.13
                         not isinstance(value, type)
                     ):
+                        self.__first_class_members__.append(key)
                         try:
                             num_vals = len(value) - len(self._ep_properties_)
                             if num_vals < 1 or len(self._ep_properties_) != len(
@@ -553,10 +590,16 @@ def __new__(mcs, classname, bases, classdict, **kwargs):
             **kwargs,
         )
         cls._ep_coerce_types_ = []
+        cls._num_sym_props_ = 0
         cls._ep_symmetric_map_ = cls._member_map_
         cls._ep_isymmetric_map_ = {}
         cls._properties_ = list(classdict._ep_properties_.keys())
 
+        # we allow users to override this
+        cls.__first_class_members__ = classdict.get(
+            "__first_class_members__", classdict.__first_class_members__
+        )
+
         if classdict._specialized_:
             for val in cls:  # type: ignore[var-annotated]
                 val = t.cast(enum.Enum, val)
@@ -598,11 +641,13 @@ def add_coerce_type(typ: t.Type[t.Any]):
                 setattr(member, prop, values[idx])
 
         # we reverse to maintain precedence order for symmetric lookups
+        cls._num_sym_props_ = 0
         member_values = t.cast(
             t.List[enum.Enum],
             list(cls._value2member_map_.values() or cls.__members__.values()),
         )
         for prop in reversed([prop for prop in cls._properties_ if prop.symmetric]):
+            cls._num_sym_props_ += 1
             prop = t.cast(_SProp, prop)
             for idx, val2 in enumerate(reversed(classdict._ep_properties_[prop])):
                 enum_cls = member_values[len(member_values) - 1 - idx]
@@ -615,6 +660,7 @@ def add_coerce_type(typ: t.Type[t.Any]):
                     add_coerce_type(type(val2))
 
         # add builtin symmetries
+        cls._num_sym_props_ += len(getattr(cls, "_symmetric_builtins_", []))
         for sym_builtin in reversed(getattr(cls, "_symmetric_builtins_", [])):
             # allow simple strings for the default case
             if isinstance(sym_builtin, str):

tests/annotations/test_aliases.py

@@ -0,0 +1,199 @@
+import sys
+from enum import auto
+from unittest import TestCase
+from typing_extensions import Annotated
+
+from enum_properties import (
+    EnumProperties,
+    FlagProperties,
+    IntEnumProperties,
+    IntFlagProperties,
+    Symmetric,
+    specialize,
+    symmetric,
+)
+
+
+class TestAliases(TestCase):
+    def test_enum_alias(self):
+        class EnumWithAliases(EnumProperties):
+            label: Annotated[str, Symmetric(case_fold=True)]
+
+            A = 1, "a"
+            B = 2, "b"
+            C = 3, "c"
+            X = C, "x"
+            Y = B, "y"
+            Z = A, "z"
+
+        self.assertEqual(
+            EnumWithAliases.__first_class_members__, ["A", "B", "C", "X", "Y", "Z"]
+        )
+
+        class EnumWithAliasesComplex(EnumProperties):
+            label: Annotated[str, Symmetric(case_fold=True)]
+
+            A = 1, "a"
+            B = 2, "b"
+            C = 3, "c"
+            X = C, "x"
+            Y = B, "y"
+            Z = A, "z"
+
+            @symmetric(case_fold=True)
+            def x3(self) -> str:
+                return self.label * 3
+
+            @property
+            def prop(self) -> str:
+                return self.label * 5
+
+            def method(self) -> str:
+                return self.label * 7
+
+            @specialize(A)
+            def method(self) -> str:
+                return self.label * 8
+
+            class Nested:
+                pass
+
+        self.assertEqual(
+            EnumWithAliasesComplex.__first_class_members__,
+            ["A", "B", "C", "X", "Y", "Z"],
+        )
+
+        class EnumWithAliasesOverride1(EnumProperties):
+            label: Annotated[str, Symmetric(case_fold=True)]
+
+            A = 1, "a"
+            B = 2, "b"
+            C = 3, "c"
+            X = C, "x"
+            Y = B, "y"
+            Z = A, "z"
+
+            __first_class_members__ = ["A", "B", "C", "X", "Y"]
+
+        self.assertEqual(
+            EnumWithAliasesOverride1.__first_class_members__, ["A", "B", "C", "X", "Y"]
+        )
+
+        class EnumWithAliasesOverride2(EnumProperties):
+            label: Annotated[str, Symmetric(case_fold=True)]
+
+            __first_class_members__ = ["A", "B", "C", "X"]
+
+            A = 1, "a"
+            B = 2, "b"
+            C = 3, "c"
+            X = C, "x"
+            Y = B, "y"
+            Z = A, "z"
+
+        self.assertEqual(
+            EnumWithAliasesOverride2.__first_class_members__, ["A", "B", "C", "X"]
+        )
+
+    def test_flag_alias(self):
+        class FlagWithAliases(FlagProperties):
+            label: Annotated[str, Symmetric(case_fold=True)]
+
+            A = 1 << 0, "a"
+            B = 1 << 1, "b"
+            C = 1 << 2, "c"
+            X = C, "x"
+            Y = B, "y"
+            Z = A, "z"
+
+            AB = A | B, "ab"
+            AC = A | C, "ac"
+            BC = B | C, "bc"
+            ABC = A | B | C, "abc"
+
+        self.assertEqual(
+            FlagWithAliases.__first_class_members__,
+            ["A", "B", "C", "X", "Y", "Z", "AB", "AC", "BC", "ABC"],
+        )
+
+        class FlagWithAliasesComplex(FlagProperties):
+            label: Annotated[str, Symmetric(case_fold=True)]
+
+            A = 1 << 0, "a"
+            B = 1 << 1, "b"
+            C = 1 << 2, "c"
+            X = C, "x"
+            Y = B, "y"
+            Z = A, "z"
+
+            AB = A | B, "ab"
+            AC = A | C, "ac"
+            BC = B | C, "bc"
+            ABC = A | B | C, "abc"
+
+            @symmetric(case_fold=True)
+            def x3(self) -> str:
+                return self.label * 3
+
+            @property
+            def prop(self) -> str:
+                return self.label * 5
+
+            def method(self) -> str:
+                return self.label * 7
+
+            @specialize(A)
+            def method(self) -> str:
+                return self.label * 8
+
+            class Nested:
+                pass
+
+        self.assertEqual(
+            FlagWithAliasesComplex.__first_class_members__,
+            ["A", "B", "C", "X", "Y", "Z", "AB", "AC", "BC", "ABC"],
+        )
+
+        class FlagWithAliasesOverride1(FlagProperties):
+            label: Annotated[str, Symmetric(case_fold=True)]
+
+            __first_class_members__ = ["A", "B", "C", "X", "Y", "ABC"]
+
+            A = 1 << 0, "a"
+            B = 1 << 1, "b"
+            C = 1 << 2, "c"
+            X = C, "x"
+            Y = B, "y"
+            Z = A, "z"
+
+            AB = A | B, "ab"
+            AC = A | C, "ac"
+            BC = B | C, "bc"
+            ABC = A | B | C, "abc"
+
+        self.assertEqual(
+            FlagWithAliasesOverride1.__first_class_members__,
+            ["A", "B", "C", "X", "Y", "ABC"],
+        )
+
+        class FlagWithAliasesOverride2(FlagProperties):
+            label: Annotated[str, Symmetric(case_fold=True)]
+
+            A = 1 << 0, "a"
+            B = 1 << 1, "b"
+            C = 1 << 2, "c"
+            X = C, "x"
+            Y = B, "y"
+            Z = A, "z"
+
+            AB = A | B, "ab"
+            AC = A | C, "ac"
+            BC = B | C, "bc"
+            ABC = A | B | C, "abc"
+
+            __first_class_members__ = ["A", "B", "C", "X", "Y", "ABC"]
+
+        self.assertEqual(
+            FlagWithAliasesOverride2.__first_class_members__,
+            ["A", "B", "C", "X", "Y", "ABC"],
+        )