Add Enum class that supports deprecated members

This commit introduces a new `frequenz.core.enum` module that provides
a drop-in replacement for the standard library's `enum.Enum` class, with
added support for deprecating enum members.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

Author: llucax

README.md

@@ -92,6 +92,25 @@ positive = Interval(0, None)  # [0, ∞]
 assert 1000 in positive  # True
 ```
 
+### `Enum` with deprecated members
+
+Define enums with deprecated members that raise deprecation warnings when
+accessed:
+
+```python
+from frequenz.core.enum import Enum, DeprecatedMember
+
+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")
+   FINISHED = 4
+
+status1 = TaskStatus.PENDING  # Warns: "PENDING is deprecated, use OPEN instead"
+assert status1 is TaskStatus.OPEN
+```
+
 ### Typing Utilities
 
 Disable class constructors to enforce factory pattern usage:

RELEASE_NOTES.md

@@ -10,7 +10,23 @@
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+- A new `frequenz.core.enum` module was added, proding a drop-in replacement `Enum` that supports deprecating members.
+
+   Example:
+
+   ```python
+   from frequenz.core.enum import Enum, DeprecatedMember
+
+   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")
+       FINISHED = 4
+
+   status1 = TaskStatus.PENDING  # Warns: "PENDING is deprecated, use OPEN instead"
+   assert status1 is TaskStatus.OPEN
+   ```
 
 ## Bug Fixes
 

src/frequenz/core/datetime.py

@@ -1,7 +1,7 @@
 # License: MIT
 # Copyright © 2024 Frequenz Energy-as-a-Service GmbH
 
-"""Timeseries basic types."""
+"""Date and time utilities."""
 
 from datetime import datetime, timezone
 from typing import Final