frequenz-core 1.2.0__tar.gz → 1.3.0__tar.gz

{frequenz_core-1.2.0/src/frequenz_core.egg-info → frequenz_core-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-core
-Version: 1.2.0
+Version: 1.3.0
 Summary: Core utilities to complement Python's standard library
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT
@@ -162,13 +162,15 @@ Define enums with deprecated members that raise deprecation warnings when
 accessed:
 
 ```python
-from frequenz.core.enum import Enum, DeprecatedMember
+from frequenz.core.enum import Enum, deprecated_member, unique
 
+@unique
 class TaskStatus(Enum):
    OPEN = 1
    IN_PROGRESS = 2
-   PENDING = DeprecatedMember(1, "PENDING is deprecated, use OPEN instead")
-   DONE = DeprecatedMember(3, "DONE is deprecated, use FINISHED instead")
+   # Duplicate values are fine with `@unique` as long as they are deprecated
+   PENDING = deprecated_member(1, "PENDING is deprecated, use OPEN instead")
+   DONE = deprecated_member(3, "DONE is deprecated, use FINISHED instead")
    FINISHED = 4
 
 status1 = TaskStatus.PENDING  # Warns: "PENDING is deprecated, use OPEN instead"

{frequenz_core-1.2.0 → frequenz_core-1.3.0}/README.md

@@ -98,13 +98,15 @@ Define enums with deprecated members that raise deprecation warnings when
 accessed:
 
 ```python
-from frequenz.core.enum import Enum, DeprecatedMember
+from frequenz.core.enum import Enum, deprecated_member, unique
 
+@unique
 class TaskStatus(Enum):
    OPEN = 1
    IN_PROGRESS = 2
-   PENDING = DeprecatedMember(1, "PENDING is deprecated, use OPEN instead")
-   DONE = DeprecatedMember(3, "DONE is deprecated, use FINISHED instead")
+   # Duplicate values are fine with `@unique` as long as they are deprecated
+   PENDING = deprecated_member(1, "PENDING is deprecated, use OPEN instead")
+   DONE = deprecated_member(3, "DONE is deprecated, use FINISHED instead")
    FINISHED = 4
 
 status1 = TaskStatus.PENDING  # Warns: "PENDING is deprecated, use OPEN instead"

frequenz_core-1.3.0/RELEASE_NOTES.md

@@ -0,0 +1,9 @@
+# Frequenz Core Library Release Notes
+
+## Upgrading
+
+- If you used `enum.DeprecatedMember` directly anywhere, you should probably switch to using `enum.deprecated_member` instead, which will tag the member value with the appropriate type.
+
+## New Features
+
+- A new `enum.deprecated_member` function has been added to create deprecated enum members with proper typing.

{frequenz_core-1.2.0 → frequenz_core-1.3.0}/src/frequenz/core/enum.py

@@ -27,12 +27,19 @@ EnumT = TypeVar("EnumT", bound=enum.Enum)
 """Type variable for enum types."""
 
 
+ValueT = TypeVar("ValueT")
+"""Type variable for enum member values."""
+
+
 class DeprecatedMemberWarning(DeprecationWarning):
     """Warning category for deprecated enum members."""
 
 
 class DeprecatedMember:
-    """Marker used in enum class bodies to declare deprecated members.
+    """Class to mark members as deprecated.
+
+    This class should not be used directly, use
+    [`deprecated_member`][frequenz.core.enum.deprecated_member] instead.
 
     Please read the [`Enum`][frequenz.core.enum.Enum] documentation for details and
     examples.
@@ -48,8 +55,24 @@ class DeprecatedMember:
         self.message = message
 
 
+def deprecated_member(value: ValueT, message: str) -> ValueT:
+    """Mark an enum member as deprecated.
+
+    Please read the [`Enum`][frequenz.core.enum.Enum] documentation for details and
+    examples.
+
+    Args:
+        value: The value of the enum member to mark as deprecated.
+        message: The deprecation message to be shown when the member is accessed.
+
+    Returns:
+        The wrapped value, to mark the enum member as deprecated.
+    """
+    return cast(ValueT, DeprecatedMember(value, message))
+
+
 class DeprecatingEnumType(enum.EnumType):
-    """Enum metaclass that supports `DeprecatedMember` wrappers.
+    """Enum metaclass that supports deprecated members.
 
     Tip:
         Normally it is not necessary to use this class directly, use
@@ -163,7 +186,7 @@ if TYPE_CHECKING:
 else:
 
     class Enum(enum.Enum, metaclass=DeprecatingEnumType):
-        """Base class for enums that support DeprecatedMember.
+        """Base class for enums that support deprecated members.
 
         This class extends the standard library's [`enum.Enum`][] to support marking
         certain members as deprecated. Deprecated members can be accessed, but doing so
@@ -171,7 +194,7 @@ else:
         a [`DeprecatedMemberWarning`][frequenz.core.enum.DeprecatedMemberWarning].
 
         To declare a deprecated member, use the
-        [`DeprecatedMember`][frequenz.core.enum.DeprecatedMember] wrapper in the class body.
+        [`deprecated_member()`][frequenz.core.enum.deprecated_member] function.
 
         When using the enum constructor (i.e. `MyEnum(value)`), a warning is only emitted if
         the resolved member has no non-deprecated aliases. If there is at least one
@@ -179,13 +202,13 @@ else:
 
         Example:
             ```python
-            from frequenz.core.enum import Enum, DeprecatedMember
+            from frequenz.core.enum import Enum, deprecated_member
 
             class TaskStatus(Enum):
                 OPEN = 1
                 IN_PROGRESS = 2
-                PENDING = DeprecatedMember(1, "PENDING is deprecated, use OPEN instead")
-                DONE = DeprecatedMember(3, "DONE is deprecated, use FINISHED instead")
+                PENDING = deprecated_member(1, "PENDING is deprecated, use OPEN instead")
+                DONE = deprecated_member(3, "DONE is deprecated, use FINISHED instead")
                 FINISHED = 4
 
             # Accessing deprecated members:
@@ -219,14 +242,14 @@ def unique(enumeration: type[EnumT]) -> type[EnumT]:
 
     Example:
         ```python
-        from frequenz.core.enum import Enum, DeprecatedMember, unique
+        from frequenz.core.enum import Enum, deprecated_member, unique
 
         @unique
         class TaskStatus(Enum):
             OPEN = 1
             IN_PROGRESS = 2
             # This is okay, as PENDING is a deprecated alias.
-            PENDING = DeprecatedMember(1, "Use OPEN instead")
+            PENDING = deprecated_member(1, "Use OPEN instead")
         ```
 
     Args:

{frequenz_core-1.2.0 → frequenz_core-1.3.0/src/frequenz_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-core
-Version: 1.2.0
+Version: 1.3.0
 Summary: Core utilities to complement Python's standard library
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License: MIT
@@ -162,13 +162,15 @@ Define enums with deprecated members that raise deprecation warnings when
 accessed:
 
 ```python
-from frequenz.core.enum import Enum, DeprecatedMember
+from frequenz.core.enum import Enum, deprecated_member, unique
 
+@unique
 class TaskStatus(Enum):
    OPEN = 1
    IN_PROGRESS = 2
-   PENDING = DeprecatedMember(1, "PENDING is deprecated, use OPEN instead")
-   DONE = DeprecatedMember(3, "DONE is deprecated, use FINISHED instead")
+   # Duplicate values are fine with `@unique` as long as they are deprecated
+   PENDING = deprecated_member(1, "PENDING is deprecated, use OPEN instead")
+   DONE = deprecated_member(3, "DONE is deprecated, use FINISHED instead")
    FINISHED = 4
 
 status1 = TaskStatus.PENDING  # Warns: "PENDING is deprecated, use OPEN instead"

frequenz_core-1.2.0/RELEASE_NOTES.md

@@ -1,41 +0,0 @@
-# Frequenz Core Library Release Notes
-
-## Summary
-
-## New Features
-
-* `frequenz.core.enum` now provides a `@unique` decorator that is aware of deprecations, and will only check for uniqueness among non-deprecated enum members.
-
-    For example this works:
-
-    ```py
-    >>> from frequenz.core.enum import DeprecatedMember, Enum, unique
-    >>> 
-    >>> @unique
-    ... class Status(Enum):
-    ...     ACTIVE = 1
-    ...     INACTIVE = 2
-    ...     PENDING = DeprecatedMember(1, "PENDING is deprecated, use ACTIVE instead")
-    ... 
-    >>> 
-    ```
-
-    While using the standard library's `enum.unique` decorator raises a `ValueError`:
-
-    ```py
-    >>> from enum import unique
-    >>> from frequenz.core.enum import DeprecatedMember, Enum
-    >>> 
-    >>> @unique
-    ... class Status(Enum):
-    ...     ACTIVE = 1
-    ...     INACTIVE = 2
-    ...     PENDING = DeprecatedMember(1, "PENDING is deprecated, use ACTIVE instead")
-    ... 
-    Traceback (most recent call last):
-      File "<stdin>", line 1, in <module>
-      File "/usr/lib/python3.12/enum.py", line 1617, in unique
-        raise ValueError('duplicate values found in %r: %s' %
-    ValueError: duplicate values found in <enum 'Status'>: PENDING -> ACTIVE
-    >>> 
-    ```