enum-properties 2.2.4__tar.gz → 2.3.0__tar.gz

{enum_properties-2.2.4 → enum_properties-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: enum-properties
-Version: 2.2.4
+Version: 2.3.0
 Summary: Add properties and method specializations to Python enumeration values with a simple declarative syntax.
 Project-URL: Homepage, https://github.com/bckohan/enum-properties
 Project-URL: Documentation, https://enum-properties.readthedocs.io
@@ -39,8 +39,8 @@ Description-Content-Type: text/markdown
 [![PyPI status](https://img.shields.io/pypi/status/enum-properties.svg)](https://pypi.python.org/pypi/enum-properties)
 [![Documentation Status](https://readthedocs.org/projects/enum-properties/badge/?version=latest)](http://enum-properties.readthedocs.io/?badge=latest/)
 [![Code Cov](https://codecov.io/gh/bckohan/enum-properties/branch/main/graph/badge.svg?token=0IZOKN2DYL)](https://codecov.io/gh/bckohan/enum-properties)
-[![Test Status](https://github.com/bckohan/django-enum/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/bckohan/enum-properties/actions/workflows/test.yml?query=branch:main)
-[![Lint Status](https://github.com/bckohan/django-enum/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/bckohan/enum-properties/actions/workflows/lint.yml?query=branch:main)
+[![Test Status](https://github.com/bckohan/enum-properties/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/bckohan/enum-properties/actions/workflows/test.yml?query=branch:main)
+[![Lint Status](https://github.com/bckohan/enum-properties/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/bckohan/enum-properties/actions/workflows/lint.yml?query=branch:main)
 
 Add properties to Python enumeration values with a simple declarative syntax. [Enum Properties](https://enum-properties.readthedocs.io/en/latest) is a lightweight extension to [Python's Enum class](https://docs.python.org/3/library/enum.html). Example:
 

{enum_properties-2.2.4 → enum_properties-2.3.0}/README.md

@@ -7,8 +7,8 @@
 [![PyPI status](https://img.shields.io/pypi/status/enum-properties.svg)](https://pypi.python.org/pypi/enum-properties)
 [![Documentation Status](https://readthedocs.org/projects/enum-properties/badge/?version=latest)](http://enum-properties.readthedocs.io/?badge=latest/)
 [![Code Cov](https://codecov.io/gh/bckohan/enum-properties/branch/main/graph/badge.svg?token=0IZOKN2DYL)](https://codecov.io/gh/bckohan/enum-properties)
-[![Test Status](https://github.com/bckohan/django-enum/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/bckohan/enum-properties/actions/workflows/test.yml?query=branch:main)
-[![Lint Status](https://github.com/bckohan/django-enum/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/bckohan/enum-properties/actions/workflows/lint.yml?query=branch:main)
+[![Test Status](https://github.com/bckohan/enum-properties/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/bckohan/enum-properties/actions/workflows/test.yml?query=branch:main)
+[![Lint Status](https://github.com/bckohan/enum-properties/actions/workflows/lint.yml/badge.svg?branch=main)](https://github.com/bckohan/enum-properties/actions/workflows/lint.yml?query=branch:main)
 
 Add properties to Python enumeration values with a simple declarative syntax. [Enum Properties](https://enum-properties.readthedocs.io/en/latest) is a lightweight extension to [Python's Enum class](https://docs.python.org/3/library/enum.html). Example:
 

{enum_properties-2.2.4 → enum_properties-2.3.0}/doc/source/changelog.rst

@@ -2,6 +2,17 @@
 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)
+===================
+
+* Fix readme badges.
+
+
 v2.2.4 (2025-03-17)
 ===================
 

{enum_properties-2.2.4 → enum_properties-2.3.0}/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

{enum_properties-2.2.4 → enum_properties-2.3.0}/doc/source/reference.rst

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

{enum_properties-2.2.4 → enum_properties-2.3.0}/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

{enum_properties-2.2.4 → enum_properties-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "enum-properties"
-version = "2.2.4"
+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 = [

{enum_properties-2.2.4 → enum_properties-2.3.0}/src/enum_properties/__init__.py

@@ -19,7 +19,7 @@ from collections.abc import Generator, Hashable, Iterable
 from dataclasses import dataclass
 from functools import cached_property
 
-VERSION = (2, 2, 4)
+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 EnumPropertiesMeta(enum.EnumMeta):
     # 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 EnumPropertiesMeta(enum.EnumMeta):
     _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 EnumPropertiesMeta(enum.EnumMeta):
             _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 @@ class EnumPropertiesMeta(enum.EnumMeta):
                         # 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 @@ class EnumPropertiesMeta(enum.EnumMeta):
             **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 @@ class EnumPropertiesMeta(enum.EnumMeta):
                 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 @@ class EnumPropertiesMeta(enum.EnumMeta):
                     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):

enum_properties-2.3.0/tests/annotations/test_aliases.py

@@ -0,0 +1,211 @@
+import sys
+import enum
+from unittest import TestCase
+from typing_extensions import Annotated
+
+from enum_properties import (
+    EnumProperties,
+    FlagProperties,
+    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
+
+            if sys.version_info[:2] >= (3, 11):
+
+                @enum.nonmember
+                class Nested:
+                    pass
+            else:
+
+                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
+
+            if sys.version_info[:2] >= (3, 11):
+
+                @enum.nonmember
+                class Nested:
+                    pass
+            else:
+
+                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"],
+        )

{enum_properties-2.2.4 → enum_properties-2.3.0}/tests/annotations/test_symmetric.py

@@ -1,7 +1,11 @@
 from unittest import TestCase
-from typing_extensions import Annotated
-
 from enum_properties import EnumProperties, symmetric
+import sys
+
+if sys.version_info[0:2] >= (3, 11):
+    from enum import property as enum_property
+else:
+    from types import DynamicClassAttribute as enum_property
 
 
 class TestSymmetricDecorator(TestCase):
@@ -82,3 +86,22 @@ class TestSymmetricDecorator(TestCase):
         self.assertTrue(SymEnum(SymEnum.ONE.label) is SymEnum.ONE)
         self.assertTrue(SymEnum(SymEnum.TWO.label) is SymEnum.TWO)
         self.assertTrue(SymEnum(SymEnum.THREE.label) is SymEnum.THREE)
+
+    def test_make_enum_properties_symmetric(self):
+        class SymEnum(EnumProperties):
+            ONE = 1
+            TWO = 2
+            THREE = 3
+
+            @symmetric(case_fold=True)
+            @enum_property
+            def label(self):
+                return self.name
+
+        self.assertEqual(SymEnum.ONE.label, "ONE")
+        self.assertEqual(SymEnum.TWO.label, "TWO")
+        self.assertEqual(SymEnum.THREE.label, "THREE")
+
+        self.assertTrue(SymEnum("one") is SymEnum.ONE)
+        self.assertTrue(SymEnum("tWo") is SymEnum.TWO)
+        self.assertTrue(SymEnum("THRee") is SymEnum.THREE)

enum_properties-2.3.0/tests/examples/howto_members_and_aliases.py

@@ -0,0 +1,22 @@
+import typing as t
+from enum_properties import EnumProperties, Symmetric
+
+
+class MyEnum(EnumProperties):
+
+    label: t.Annotated[str, Symmetric()]
+
+    A = 1, "a"
+    B = 2, "b"
+    C = 3, "c"
+    ALIAS_TO_A = A, "a"
+
+
+# __first_class_members__ contains members and aliases
+assert MyEnum.__first_class_members__ == ["A", "B", "C", "ALIAS_TO_A"]
+
+# __members__ contains all members, including aliases and symmetric aliases
+assert set(MyEnum.__members__.keys()) == {"A", "B", "C", "ALIAS_TO_A", "a", "b", "c"}
+
+# iterating contains only non-alias members
+assert list(MyEnum) == [MyEnum.A, MyEnum.B, MyEnum.C]

{enum_properties-2.2.4 → enum_properties-2.3.0}/tests/examples/test_examples.py

@@ -123,3 +123,7 @@ def test_howto_hash_equiv_def():
 
 def test_howto_legacy():
     from tests.examples import howto_legacy
+
+
+def test_howto_members_and_aliases():
+    from tests.examples import howto_members_and_aliases