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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: frequenz-core
-Version: 1.2.0
+Version: 1.4.0
 Summary: Core utilities to complement Python's standard library
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Documentation, https://frequenz-floss.github.io/frequenz-core-python/
 Project-URL: Changelog, https://github.com/frequenz-floss/frequenz-core-python/releases
 Project-URL: Issues, https://github.com/frequenz-floss/frequenz-core-python/issues
@@ -12,7 +12,6 @@ Project-URL: Support, https://github.com/frequenz-floss/frequenz-core-python/dis
 Keywords: asyncio,collections,core,datetime,frequenz,lib,library,math,python,stdlib,typing
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development :: Libraries
@@ -23,41 +22,42 @@ License-File: LICENSE
 Requires-Dist: typing-extensions<5,>=4.13.0
 Provides-Extra: dev-flake8
 Requires-Dist: flake8==7.3.0; extra == "dev-flake8"
+Requires-Dist: flake8-datetimez==20.10.0; extra == "dev-flake8"
 Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"
-Requires-Dist: flake8-pyproject==1.2.3; extra == "dev-flake8"
-Requires-Dist: pydoclint==0.6.11; extra == "dev-flake8"
+Requires-Dist: flake8-pyproject==1.2.4; extra == "dev-flake8"
+Requires-Dist: pydoclint==0.9.1; extra == "dev-flake8"
 Requires-Dist: pydocstyle==6.3.0; extra == "dev-flake8"
 Provides-Extra: dev-formatting
-Requires-Dist: black==25.1.0; extra == "dev-formatting"
-Requires-Dist: isort==6.0.1; extra == "dev-formatting"
+Requires-Dist: black==26.5.1; extra == "dev-formatting"
+Requires-Dist: isort==8.0.1; extra == "dev-formatting"
 Provides-Extra: dev-mkdocs
-Requires-Dist: Markdown==3.8.2; extra == "dev-mkdocs"
-Requires-Dist: black==25.1.0; extra == "dev-mkdocs"
-Requires-Dist: mike==2.1.3; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-gen-files==0.5.0; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-literate-nav==0.6.2; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-macros-plugin==1.3.9; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-material==9.6.18; extra == "dev-mkdocs"
-Requires-Dist: mkdocstrings[python]==0.30.0; extra == "dev-mkdocs"
-Requires-Dist: mkdocstrings-python==1.18.2; extra == "dev-mkdocs"
-Requires-Dist: frequenz-repo-config[lib]==0.13.5; extra == "dev-mkdocs"
+Requires-Dist: Markdown==3.10.2; extra == "dev-mkdocs"
+Requires-Dist: black==26.5.1; extra == "dev-mkdocs"
+Requires-Dist: mike==2.2.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-gen-files==0.6.1; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-literate-nav==0.6.3; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-macros-plugin==1.5.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.7.7; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings[python]==1.0.6; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings-python==2.0.5; extra == "dev-mkdocs"
+Requires-Dist: frequenz-repo-config[lib]==0.18.0; extra == "dev-mkdocs"
 Provides-Extra: dev-mypy
-Requires-Dist: mypy==1.17.1; extra == "dev-mypy"
-Requires-Dist: types-Markdown==3.8.0.20250809; extra == "dev-mypy"
+Requires-Dist: mypy==2.3.0; extra == "dev-mypy"
+Requires-Dist: types-Markdown==3.10.2.20260712; extra == "dev-mypy"
 Requires-Dist: frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
 Provides-Extra: dev-noxfile
-Requires-Dist: nox==2025.5.1; extra == "dev-noxfile"
-Requires-Dist: frequenz-repo-config[lib]==0.13.5; extra == "dev-noxfile"
+Requires-Dist: nox==2026.7.11; extra == "dev-noxfile"
+Requires-Dist: frequenz-repo-config[lib]==0.18.0; extra == "dev-noxfile"
 Provides-Extra: dev-pylint
 Requires-Dist: frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
-Requires-Dist: pytest==8.4.1; extra == "dev-pytest"
-Requires-Dist: pylint==3.3.8; extra == "dev-pytest"
-Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.13.5; extra == "dev-pytest"
-Requires-Dist: pytest-mock==3.14.1; extra == "dev-pytest"
-Requires-Dist: pytest-asyncio==1.1.0; extra == "dev-pytest"
-Requires-Dist: async-solipsism==0.8; extra == "dev-pytest"
-Requires-Dist: hypothesis==6.138.11; extra == "dev-pytest"
+Requires-Dist: pytest==9.1.1; extra == "dev-pytest"
+Requires-Dist: pylint==4.0.6; extra == "dev-pytest"
+Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.18.0; extra == "dev-pytest"
+Requires-Dist: pytest-mock==3.15.1; extra == "dev-pytest"
+Requires-Dist: pytest-asyncio==1.4.0; extra == "dev-pytest"
+Requires-Dist: async-solipsism==0.9; extra == "dev-pytest"
+Requires-Dist: hypothesis==6.163.0; extra == "dev-pytest"
 Provides-Extra: dev
 Requires-Dist: frequenz-core[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"
 Dynamic: license-file
@@ -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"
@@ -198,6 +200,28 @@ class ApiClient:
 client = ApiClient.create("my-api-key")  # ✅ Works
 ```
 
+Annotate floating point values honestly, as Python's numeric tower lets `int`
+values through any `float` annotation:
+
+```python
+from typing import assert_never
+
+from frequenz.core.typing import FloatInt
+
+def describe(value: FloatInt | None) -> str:
+    match value:
+        case float() | int():
+            return f"number {value}"
+        case None:
+            return "nothing"
+        case unexpected:
+            assert_never(unexpected)
+
+assert describe(1) == "number 1"  # ✅ `case float():` alone would crash here
+assert describe(1.5) == "number 1.5"
+assert describe(None) == "nothing"
+```
+
 ### Strongly-Typed IDs
 
 Create type-safe identifiers for different entities:

{frequenz_core-1.2.0 → frequenz_core-1.4.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"
@@ -134,6 +136,28 @@ class ApiClient:
 client = ApiClient.create("my-api-key")  # ✅ Works
 ```
 
+Annotate floating point values honestly, as Python's numeric tower lets `int`
+values through any `float` annotation:
+
+```python
+from typing import assert_never
+
+from frequenz.core.typing import FloatInt
+
+def describe(value: FloatInt | None) -> str:
+    match value:
+        case float() | int():
+            return f"number {value}"
+        case None:
+            return "nothing"
+        case unexpected:
+            assert_never(unexpected)
+
+assert describe(1) == "number 1"  # ✅ `case float():` alone would crash here
+assert describe(1.5) == "number 1.5"
+assert describe(None) == "nothing"
+```
+
 ### Strongly-Typed IDs
 
 Create type-safe identifiers for different entities:

frequenz_core-1.4.0/RELEASE_NOTES.md

@@ -0,0 +1,23 @@
+# Frequenz Core Library Release Notes
+
+## Upgrading
+
+- [`Interval`][frequenz.core.math.Interval]'s type parameter no longer includes `None`. The exported type variable `LessThanComparableOrNoneT` (bound to `LessThanComparable | None`) was deprecated and replaced with `LessThanComparableT` (bound to `LessThanComparable`). `None` is still accepted as a value for `start` / `end` to indicate an unbounded side, but it is treated purely as bound metadata rather than a value in the interval's comparable space.
+
+  Migration:
+
+  - `Interval[int | None]` → `Interval[int]`
+  - `Interval[LessThanComparable | None]` → `Interval[LessThanComparable]`
+  - `LessThanComparableOrNoneT` (importable name) → `LessThanComparableT`
+
+  Note that explicitly using `Interval[int | None]` still works, as `(int | None) | None` is equivalent to `int | None`, even when it is no longer needed nor recommended. Old code will mostly work, but there is one soft breaking change: `None in some_interval` and `None in some_interval_set` is now a type-check error at call sites, matching the design intent that `None` is a bound marker and never a member value.
+
+## New Features
+
+- Added [`FloatInt`][frequenz.core.typing.FloatInt], a type alias for `float | int`.
+
+  [PEP 484](https://peps.python.org/pep-0484/)'s [numeric tower](https://peps.python.org/pep-0484/#the-numeric-tower) makes `int` assignable wherever `float` is annotated, while at runtime `isinstance(1, float)` is `False`. A plain `float` annotation therefore silently admits values that break `match … case float():` arms and `float`-only methods like `hex()`.
+
+  Annotate with `FloatInt` instead of a plain `float`: the alias docstring documents the trap in detail, including the inherent `bool ⊂ int` leak.
+
+- [`is_close_to_zero()`][frequenz.core.math.is_close_to_zero] now annotates its `value` and `abs_tol` parameters as [`FloatInt`][frequenz.core.typing.FloatInt]. This is a pure widening, `int` arguments were always accepted by type checkers, the annotation just didn't admit it.

{frequenz_core-1.2.0 → frequenz_core-1.4.0}/pyproject.toml

@@ -3,9 +3,9 @@
 
 [build-system]
 requires = [
-  "setuptools == 80.9.0",
-  "setuptools_scm[toml] == 9.2.0",
-  "frequenz-repo-config[lib] == 0.13.5",
+  "setuptools == 83.0.0",
+  "setuptools_scm[toml] == 10.2.1",
+  "frequenz-repo-config[lib] == 0.18.0",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -13,7 +13,8 @@ build-backend = "setuptools.build_meta"
 name = "frequenz-core"
 description = "Core utilities to complement Python's standard library"
 readme = "README.md"
-license = { text = "MIT" }
+license = "MIT"
+license-files = ["LICENSE"]
 keywords = [
   "asyncio",
   "collections",
@@ -30,7 +31,6 @@ keywords = [
 classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
   "Topic :: Software Development :: Libraries",
@@ -47,44 +47,45 @@ email = "floss@frequenz.com"
 [project.optional-dependencies]
 dev-flake8 = [
   "flake8 == 7.3.0",
+  "flake8-datetimez == 20.10.0",
   "flake8-docstrings == 1.7.0",
-  "flake8-pyproject == 1.2.3", # For reading the flake8 config from pyproject.toml
-  "pydoclint == 0.6.11",
+  "flake8-pyproject == 1.2.4", # For reading the flake8 config from pyproject.toml
+  "pydoclint == 0.9.1",
   "pydocstyle == 6.3.0",
 ]
-dev-formatting = ["black == 25.1.0", "isort == 6.0.1"]
+dev-formatting = ["black == 26.5.1", "isort == 8.0.1"]
 dev-mkdocs = [
-  "Markdown == 3.8.2",
-  "black == 25.1.0",
-  "mike == 2.1.3",
-  "mkdocs-gen-files == 0.5.0",
-  "mkdocs-literate-nav == 0.6.2",
-  "mkdocs-macros-plugin == 1.3.9",
-  "mkdocs-material == 9.6.18",
-  "mkdocstrings[python] == 0.30.0",
-  "mkdocstrings-python == 1.18.2",
-  "frequenz-repo-config[lib] == 0.13.5",
+  "Markdown == 3.10.2",
+  "black == 26.5.1",
+  "mike == 2.2.0",
+  "mkdocs-gen-files == 0.6.1",
+  "mkdocs-literate-nav == 0.6.3",
+  "mkdocs-macros-plugin == 1.5.0",
+  "mkdocs-material == 9.7.7",
+  "mkdocstrings[python] == 1.0.6",
+  "mkdocstrings-python == 2.0.5",
+  "frequenz-repo-config[lib] == 0.18.0",
 ]
 dev-mypy = [
-  "mypy == 1.17.1",
-  "types-Markdown == 3.8.0.20250809",
+  "mypy == 2.3.0",
+  "types-Markdown == 3.10.2.20260712",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
-dev-noxfile = ["nox == 2025.5.1", "frequenz-repo-config[lib] == 0.13.5"]
+dev-noxfile = ["nox == 2026.7.11", "frequenz-repo-config[lib] == 0.18.0"]
 dev-pylint = [
   # dev-pytest already defines a dependency to pylint because of the examples
   # For checking the noxfile, docs/ script, and tests
   "frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
 dev-pytest = [
-  "pytest == 8.4.1",
-  "pylint == 3.3.8", # We need this to check for the examples
-  "frequenz-repo-config[extra-lint-examples] == 0.13.5",
-  "pytest-mock == 3.14.1",
-  "pytest-asyncio == 1.1.0",
-  "async-solipsism == 0.8",
-  "hypothesis == 6.138.11",
+  "pytest == 9.1.1",
+  "pylint == 4.0.6", # We need this to check for the examples
+  "frequenz-repo-config[extra-lint-examples] == 0.18.0",
+  "pytest-mock == 3.15.1",
+  "pytest-asyncio == 1.4.0",
+  "async-solipsism == 0.9",
+  "hypothesis == 6.163.0",
 ]
 dev = [
   "frequenz-core[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
@@ -123,6 +124,10 @@ check-yield-types = false
 arg-type-hints-in-docstring = false
 arg-type-hints-in-signature = true
 allow-init-docstring = true
+check-class-attributes = true
+check-style-mismatch = true
+require-inline-class-var-docs = true
+skip-checking-short-docstrings = true
 
 [tool.pylint.similarities]
 ignore-comments = ['yes']

{frequenz_core-1.2.0 → frequenz_core-1.4.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,16 +55,34 @@ 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
-        [`Enum`][frequenz.core.enum.Enum] instead.
+        [`Enum`][..Enum] instead.
 
     Behavior:
 
     - In the class body, members may be declared as `NAME = DeprecatedMember(value, msg)`.
+      See [`DeprecatedMember`][..DeprecatedMember] and
+      [`deprecated_member()`][..deprecated_member] for details.
     - During class creation, these wrappers are replaced with `value` so that
       a normal enum member or alias is created by [`EnumType`][enum.EnumType].
     - The deprecated names are recorded so that:
@@ -75,7 +100,7 @@ class DeprecatingEnumType(enum.EnumType):
         classdict: Mapping[str, Any],
         **kw: Any,
     ) -> type[EnumT]:
-        """Create the new enum class, rewriting `DeprecatedMember` instances."""
+        """Create the new enum class rewriting [`DeprecatedMember`][...DeprecatedMember] members."""
         deprecated_names: dict[str, str] = {}
         prepared = super().__prepare__(name, bases, **kw)
 
@@ -163,7 +188,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 +196,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 +204,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 +244,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.4.0}/src/frequenz/core/id.py

@@ -20,7 +20,7 @@ the ID and must be unique across all ID types.
 
 Note:
     The `str_prefix` must be unique across all ID types. If you try to use a
-    prefix that is already registered, a `ValueError` will be raised when defining
+    prefix that is already registered, a warning will be logged when defining
     the class.
 
 To encourage consistency, the class name must end with the suffix "Id" (e.g.,
@@ -61,7 +61,6 @@ Example: Creating an ID type with a non-standard name
     ```
 '''
 
-
 import logging
 from typing import Any, ClassVar, Self, cast
 
@@ -157,6 +156,13 @@ class BaseId:
 
         Equality is defined as being of the exact same type and having the same
         underlying ID.
+
+        Args:
+            other: The object to compare against.
+
+        Returns:
+            True if `other` is of the same type and has the same underlying ID,
+            `NotImplemented` if `other` is of a different type.
         """
         # pylint thinks this is not an unidiomatic typecheck, but in this case
         # it is not. isinstance() returns True for subclasses, which is not
@@ -173,6 +179,13 @@ class BaseId:
         """Check if this instance is less than another object.
 
         Comparison is only defined between instances of the exact same type.
+
+        Args:
+            other: The object to compare against.
+
+        Returns:
+            True if this instance is less than `other`, `NotImplemented` if
+            `other` is of a different type.
         """
         # pylint: disable-next=unidiomatic-typecheck
         if type(other) is not type(self):
@@ -185,6 +198,9 @@ class BaseId:
 
         The hash is based on the exact type and the underlying ID to ensure
         that IDs of different types but with the same numeric value have different hashes.
+
+        Returns:
+            The hash of this instance.
         """
         return hash((type(self), self._id))
 

{frequenz_core-1.2.0 → frequenz_core-1.4.0}/src/frequenz/core/math.py

@@ -5,10 +5,12 @@
 
 import math
 from dataclasses import dataclass
-from typing import Generic, Protocol, Self, TypeVar, cast
+from typing import Generic, Protocol, Self, TypeVar
 
+from .typing import FloatInt
 
-def is_close_to_zero(value: float, abs_tol: float = 1e-9) -> bool:
+
+def is_close_to_zero(value: FloatInt, abs_tol: FloatInt = 1e-9) -> bool:
     """Check if a floating point value is close to zero.
 
     A value of 1e-9 is a commonly used absolute tolerance to balance precision
@@ -34,76 +36,68 @@ class LessThanComparable(Protocol):
         """Return whether self is less than other."""
 
 
+LessThanComparableT = TypeVar("LessThanComparableT", bound=LessThanComparable)
+"""Type variable for a value that is [`LessThanComparable`][..LessThanComparable]."""
+
+
 LessThanComparableOrNoneT = TypeVar(
     "LessThanComparableOrNoneT", bound=LessThanComparable | None
 )
-"""Type variable for a value that a `LessThanComparable` or `None`."""
+"""Type variable for a value that is [`LessThanComparable`][..LessThanComparable] or `None`.
+
+Warning: Deprecated
+    This type variable is deprecated and it will be removed in a future version. Use
+    [`LessThanComparableT`][..LessThanComparableT] instead.
+"""
 
 
 @dataclass(frozen=True, repr=False)
-class Interval(Generic[LessThanComparableOrNoneT]):
+class Interval(Generic[LessThanComparableT]):
     """An interval to test if a value is within its limits.
 
-    The `start` and `end` are inclusive, meaning that the `start` and `end` limites are
-    included in the range when checking if a value is contained by the interval.
+    The [`.start`][.start] and [`.end`][.end] are inclusive, meaning that the
+    [`.start`][.start] and [`.end`][.end] limits are included in the range when
+    checking if a value is contained by the interval.
 
-    If the `start` or `end` is `None`, it means that the interval is unbounded in that
-    direction.
+    If the [`.start`][.start] or [`.end`][.end] is `None`, it means that the interval
+    is unbounded in that direction. `None` is used purely as a bound marker; it is
+    never a value in the interval.
 
-    If `start` is bigger than `end`, a `ValueError` is raised.
+    If [`.start`][.start] is bigger than [`.end`][.end], a `ValueError` is raised.
 
     The type stored in the interval must be comparable, meaning that it must implement
     the `__lt__` method to be able to compare values.
     """
 
-    start: LessThanComparableOrNoneT
-    """The start of the interval."""
+    start: LessThanComparableT | None
+    """The start of the interval, or `None` to indicate no lower bound (-∞)."""
 
-    end: LessThanComparableOrNoneT
-    """The end of the interval."""
+    end: LessThanComparableT | None
+    """The end of the interval, or `None` to indicate no upper bound (+∞)."""
 
     def __post_init__(self) -> None:
         """Check if the start is less than or equal to the end."""
         if self.start is None or self.end is None:
             return
-        start = cast(LessThanComparable, self.start)
-        end = cast(LessThanComparable, self.end)
-        if start > end:
+        if self.start > self.end:
             raise ValueError(
                 f"The start ({self.start}) can't be bigger than end ({self.end})"
             )
 
-    def __contains__(self, item: LessThanComparableOrNoneT) -> bool:
-        """
-        Check if the value is within the range of the container.
+    def __contains__(self, item: LessThanComparableT) -> bool:
+        """Check if the value is within the range of the interval.
 
         Args:
             item: The value to check.
 
         Returns:
-            bool: True if value is within the range, otherwise False.
+            True if value is within the range, otherwise False.
         """
-        if item is None:
+        if self.start is not None and item < self.start:
+            return False
+        if self.end is not None and item > self.end:
             return False
-        casted_item = cast(LessThanComparable, item)
-
-        if self.start is None and self.end is None:
-            return True
-        if self.start is None:
-            start = cast(LessThanComparable, self.end)
-            return not casted_item > start
-        if self.end is None:
-            return not self.start > item
-        # mypy seems to get confused here, not being able to narrow start and end to
-        # just LessThanComparable, complaining with:
-        #   error: Unsupported left operand type for <= (some union)
-        # But we know if they are not None, they should be LessThanComparable, and
-        # actually mypy is being able to figure it out in the lines above, just not in
-        # this one, so it should be safe to cast.
-        return not (
-            casted_item < cast(LessThanComparable, self.start)
-            or casted_item > cast(LessThanComparable, self.end)
-        )
+        return True
 
     def __repr__(self) -> str:
         """Return a string representation of this instance."""

{frequenz_core-1.2.0 → frequenz_core-1.4.0}/src/frequenz/core/typing.py

@@ -11,10 +11,60 @@ It also provides a metaclass used by the decorator to disable the `__init__`:
 [`NoInitConstructibleMeta`][frequenz.core.typing.NoInitConstructibleMeta]. This is
 useful mostly for disabling `__init__` while having to use another metaclass too (like
 [`abc.ABCMeta`][abc.ABCMeta]).
+
+Finally, it provides [`FloatInt`][frequenz.core.typing.FloatInt], an honest type alias
+for `float | int`, to annotate floating point values that can also be an `int` at
+runtime.
 """
 
 from collections.abc import Callable
-from typing import Any, NoReturn, TypeVar, cast, overload
+from typing import Any, NoReturn, TypeAlias, TypeVar, cast, overload
+
+FloatInt: TypeAlias = float | int
+"""A floating point value that can also be an `int` at runtime.
+
+[PEP 484's numeric tower](https://peps.python.org/pep-0484/#the-numeric-tower) makes
+`int` assignable to any `float`-annotated parameter, attribute or variable, so a plain
+`float` annotation is a lie: type checkers (even `mypy --strict`) happily accept `int`
+values, but `isinstance(1, float)` is `False` at runtime. This breaks `match … case
+float():` arms (an `int` value falls through to
+[`assert_never()`][typing.assert_never]), calls to `float`-only methods like
+[`hex()`][float.hex], and any other code dispatching on the concrete runtime type.
+
+Annotating with this alias instead makes the heterogeneity explicit, so type checkers
+push the code reading these values to handle both branches, typically by matching with
+`case float() | int():`.
+
+The full analysis, including the alternatives that were rejected, is recorded in
+[issue #250](https://github.com/frequenz-floss/frequenz-client-common-python/issues/250).
+
+Danger:
+    `bool` is a subclass of `int`, so `True` and `False` also satisfy this alias. This
+    is inherent to Python's type system and is not guarded against.
+
+Example:
+    ```python
+    from typing import assert_never
+
+    from frequenz.core.typing import FloatInt
+
+
+    def describe(value: FloatInt | None) -> str:
+        match value:
+            case float() | int():
+                return f"number {value}"
+            case None:
+                return "nothing"
+            case unexpected:
+                assert_never(unexpected)
+
+
+    assert describe(1) == "number 1"
+    assert describe(1.5) == "number 1.5"
+    assert describe(None) == "nothing"
+    ```
+"""
+
 
 TypeT = TypeVar("TypeT", bound=type)
 """A type variable that is bound to a type."""
@@ -207,7 +257,7 @@ class NoInitConstructibleMeta(type):
         class NoInitConstructibleABCMeta(ABCMeta, NoInitConstructibleMeta):
             pass
 
-        class MyAbstractClass(metaclas=NoInitConstructibleABCMeta):
+        class MyAbstractClass(metaclass=NoInitConstructibleABCMeta):
             @abstractmethod
             def do_something(self) -> None:
                 ...

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: frequenz-core
-Version: 1.2.0
+Version: 1.4.0
 Summary: Core utilities to complement Python's standard library
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Documentation, https://frequenz-floss.github.io/frequenz-core-python/
 Project-URL: Changelog, https://github.com/frequenz-floss/frequenz-core-python/releases
 Project-URL: Issues, https://github.com/frequenz-floss/frequenz-core-python/issues
@@ -12,7 +12,6 @@ Project-URL: Support, https://github.com/frequenz-floss/frequenz-core-python/dis
 Keywords: asyncio,collections,core,datetime,frequenz,lib,library,math,python,stdlib,typing
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Topic :: Software Development :: Libraries
@@ -23,41 +22,42 @@ License-File: LICENSE
 Requires-Dist: typing-extensions<5,>=4.13.0
 Provides-Extra: dev-flake8
 Requires-Dist: flake8==7.3.0; extra == "dev-flake8"
+Requires-Dist: flake8-datetimez==20.10.0; extra == "dev-flake8"
 Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"
-Requires-Dist: flake8-pyproject==1.2.3; extra == "dev-flake8"
-Requires-Dist: pydoclint==0.6.11; extra == "dev-flake8"
+Requires-Dist: flake8-pyproject==1.2.4; extra == "dev-flake8"
+Requires-Dist: pydoclint==0.9.1; extra == "dev-flake8"
 Requires-Dist: pydocstyle==6.3.0; extra == "dev-flake8"
 Provides-Extra: dev-formatting
-Requires-Dist: black==25.1.0; extra == "dev-formatting"
-Requires-Dist: isort==6.0.1; extra == "dev-formatting"
+Requires-Dist: black==26.5.1; extra == "dev-formatting"
+Requires-Dist: isort==8.0.1; extra == "dev-formatting"
 Provides-Extra: dev-mkdocs
-Requires-Dist: Markdown==3.8.2; extra == "dev-mkdocs"
-Requires-Dist: black==25.1.0; extra == "dev-mkdocs"
-Requires-Dist: mike==2.1.3; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-gen-files==0.5.0; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-literate-nav==0.6.2; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-macros-plugin==1.3.9; extra == "dev-mkdocs"
-Requires-Dist: mkdocs-material==9.6.18; extra == "dev-mkdocs"
-Requires-Dist: mkdocstrings[python]==0.30.0; extra == "dev-mkdocs"
-Requires-Dist: mkdocstrings-python==1.18.2; extra == "dev-mkdocs"
-Requires-Dist: frequenz-repo-config[lib]==0.13.5; extra == "dev-mkdocs"
+Requires-Dist: Markdown==3.10.2; extra == "dev-mkdocs"
+Requires-Dist: black==26.5.1; extra == "dev-mkdocs"
+Requires-Dist: mike==2.2.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-gen-files==0.6.1; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-literate-nav==0.6.3; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-macros-plugin==1.5.0; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.7.7; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings[python]==1.0.6; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings-python==2.0.5; extra == "dev-mkdocs"
+Requires-Dist: frequenz-repo-config[lib]==0.18.0; extra == "dev-mkdocs"
 Provides-Extra: dev-mypy
-Requires-Dist: mypy==1.17.1; extra == "dev-mypy"
-Requires-Dist: types-Markdown==3.8.0.20250809; extra == "dev-mypy"
+Requires-Dist: mypy==2.3.0; extra == "dev-mypy"
+Requires-Dist: types-Markdown==3.10.2.20260712; extra == "dev-mypy"
 Requires-Dist: frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
 Provides-Extra: dev-noxfile
-Requires-Dist: nox==2025.5.1; extra == "dev-noxfile"
-Requires-Dist: frequenz-repo-config[lib]==0.13.5; extra == "dev-noxfile"
+Requires-Dist: nox==2026.7.11; extra == "dev-noxfile"
+Requires-Dist: frequenz-repo-config[lib]==0.18.0; extra == "dev-noxfile"
 Provides-Extra: dev-pylint
 Requires-Dist: frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
 Provides-Extra: dev-pytest
-Requires-Dist: pytest==8.4.1; extra == "dev-pytest"
-Requires-Dist: pylint==3.3.8; extra == "dev-pytest"
-Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.13.5; extra == "dev-pytest"
-Requires-Dist: pytest-mock==3.14.1; extra == "dev-pytest"
-Requires-Dist: pytest-asyncio==1.1.0; extra == "dev-pytest"
-Requires-Dist: async-solipsism==0.8; extra == "dev-pytest"
-Requires-Dist: hypothesis==6.138.11; extra == "dev-pytest"
+Requires-Dist: pytest==9.1.1; extra == "dev-pytest"
+Requires-Dist: pylint==4.0.6; extra == "dev-pytest"
+Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.18.0; extra == "dev-pytest"
+Requires-Dist: pytest-mock==3.15.1; extra == "dev-pytest"
+Requires-Dist: pytest-asyncio==1.4.0; extra == "dev-pytest"
+Requires-Dist: async-solipsism==0.9; extra == "dev-pytest"
+Requires-Dist: hypothesis==6.163.0; extra == "dev-pytest"
 Provides-Extra: dev
 Requires-Dist: frequenz-core[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"
 Dynamic: license-file
@@ -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"
@@ -198,6 +200,28 @@ class ApiClient:
 client = ApiClient.create("my-api-key")  # ✅ Works
 ```
 
+Annotate floating point values honestly, as Python's numeric tower lets `int`
+values through any `float` annotation:
+
+```python
+from typing import assert_never
+
+from frequenz.core.typing import FloatInt
+
+def describe(value: FloatInt | None) -> str:
+    match value:
+        case float() | int():
+            return f"number {value}"
+        case None:
+            return "nothing"
+        case unexpected:
+            assert_never(unexpected)
+
+assert describe(1) == "number 1"  # ✅ `case float():` alone would crash here
+assert describe(1.5) == "number 1.5"
+assert describe(None) == "nothing"
+```
+
 ### Strongly-Typed IDs
 
 Create type-safe identifiers for different entities:

{frequenz_core-1.2.0 → frequenz_core-1.4.0}/src/frequenz_core.egg-info/SOURCES.txt

@@ -16,4 +16,6 @@ src/frequenz_core.egg-info/PKG-INFO
 src/frequenz_core.egg-info/SOURCES.txt
 src/frequenz_core.egg-info/dependency_links.txt
 src/frequenz_core.egg-info/requires.txt
+src/frequenz_core.egg-info/scm_file_list.json
+src/frequenz_core.egg-info/scm_version.json
 src/frequenz_core.egg-info/top_level.txt

frequenz_core-1.4.0/src/frequenz_core.egg-info/requires.txt

@@ -0,0 +1,49 @@
+typing-extensions<5,>=4.13.0
+
+[dev]
+frequenz-core[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]
+
+[dev-flake8]
+flake8==7.3.0
+flake8-datetimez==20.10.0
+flake8-docstrings==1.7.0
+flake8-pyproject==1.2.4
+pydoclint==0.9.1
+pydocstyle==6.3.0
+
+[dev-formatting]
+black==26.5.1
+isort==8.0.1
+
+[dev-mkdocs]
+Markdown==3.10.2
+black==26.5.1
+mike==2.2.0
+mkdocs-gen-files==0.6.1
+mkdocs-literate-nav==0.6.3
+mkdocs-macros-plugin==1.5.0
+mkdocs-material==9.7.7
+mkdocstrings[python]==1.0.6
+mkdocstrings-python==2.0.5
+frequenz-repo-config[lib]==0.18.0
+
+[dev-mypy]
+mypy==2.3.0
+types-Markdown==3.10.2.20260712
+frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]
+
+[dev-noxfile]
+nox==2026.7.11
+frequenz-repo-config[lib]==0.18.0
+
+[dev-pylint]
+frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]
+
+[dev-pytest]
+pytest==9.1.1
+pylint==4.0.6
+frequenz-repo-config[extra-lint-examples]==0.18.0
+pytest-mock==3.15.1
+pytest-asyncio==1.4.0
+async-solipsism==0.9
+hypothesis==6.163.0

frequenz_core-1.4.0/src/frequenz_core.egg-info/scm_file_list.json

@@ -0,0 +1,55 @@
+{
+  "files": [
+    ".cookiecutter-replay.json",
+    ".editorconfig",
+    ".github/ISSUE_TEMPLATE/bug.yml",
+    ".github/ISSUE_TEMPLATE/config.yml",
+    ".github/ISSUE_TEMPLATE/feature.yml",
+    ".github/RELEASE_NOTES.template.md",
+    ".github/dependabot.yml",
+    ".github/keylabeler.yml",
+    ".github/labeler.yml",
+    ".github/workflows/auto-dependabot.yaml",
+    ".github/workflows/black-migration.yaml",
+    ".github/workflows/ci-pr.yaml",
+    ".github/workflows/ci.yaml",
+    ".github/workflows/dco-merge-queue.yml",
+    ".github/workflows/isort-migration.yaml",
+    ".github/workflows/labeler.yml",
+    ".github/workflows/release-notes-check.yml",
+    ".github/workflows/repo-config-migration.yaml",
+    ".gitignore",
+    "CODEOWNERS",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "MANIFEST.in",
+    "README.md",
+    "RELEASE_NOTES.md",
+    "docs/CONTRIBUTING.md",
+    "docs/SUMMARY.md",
+    "docs/_css/mkdocstrings.css",
+    "docs/_css/style.css",
+    "docs/_img/logo.png",
+    "docs/_overrides/main.html",
+    "docs/_scripts/mkdocstrings_autoapi.py",
+    "docs/index.md",
+    "mkdocs.yml",
+    "noxfile.py",
+    "pyproject.toml",
+    "src/frequenz/core/__init__.py",
+    "src/frequenz/core/conftest.py",
+    "src/frequenz/core/datetime.py",
+    "src/frequenz/core/enum.py",
+    "src/frequenz/core/id.py",
+    "src/frequenz/core/math.py",
+    "src/frequenz/core/module.py",
+    "src/frequenz/core/py.typed",
+    "src/frequenz/core/typing.py",
+    "tests/math/test_interval.py",
+    "tests/math/test_is_close_to_zero.py",
+    "tests/test_enum.py",
+    "tests/test_id.py",
+    "tests/test_module.py",
+    "tests/test_typing.py"
+  ]
+}

frequenz_core-1.4.0/src/frequenz_core.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.4.0",
+  "distance": 0,
+  "node": "g96e40b27995efe79ab7899dea61139096d2983f6",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-08-17"
+}

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
-    >>> 
-    ```

frequenz_core-1.2.0/src/frequenz_core.egg-info/requires.txt

@@ -1,48 +0,0 @@
-typing-extensions<5,>=4.13.0
-
-[dev]
-frequenz-core[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]
-
-[dev-flake8]
-flake8==7.3.0
-flake8-docstrings==1.7.0
-flake8-pyproject==1.2.3
-pydoclint==0.6.11
-pydocstyle==6.3.0
-
-[dev-formatting]
-black==25.1.0
-isort==6.0.1
-
-[dev-mkdocs]
-Markdown==3.8.2
-black==25.1.0
-mike==2.1.3
-mkdocs-gen-files==0.5.0
-mkdocs-literate-nav==0.6.2
-mkdocs-macros-plugin==1.3.9
-mkdocs-material==9.6.18
-mkdocstrings[python]==0.30.0
-mkdocstrings-python==1.18.2
-frequenz-repo-config[lib]==0.13.5
-
-[dev-mypy]
-mypy==1.17.1
-types-Markdown==3.8.0.20250809
-frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]
-
-[dev-noxfile]
-nox==2025.5.1
-frequenz-repo-config[lib]==0.13.5
-
-[dev-pylint]
-frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]
-
-[dev-pytest]
-pytest==8.4.1
-pylint==3.3.8
-frequenz-repo-config[extra-lint-examples]==0.13.5
-pytest-mock==3.14.1
-pytest-asyncio==1.1.0
-async-solipsism==0.8
-hypothesis==6.138.11