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

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

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: frequenz-core
-Version: 1.3.0
+Version: 1.5.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
@@ -22,42 +21,44 @@ Description-Content-Type: text/markdown
 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==7.4.1; extra == "dev-flake8"
+Requires-Dist: flake8-datetimez==26.8.1; 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.10.0; 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==9.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.11; extra == "dev-mkdocs"
+Requires-Dist: black==26.5.1; extra == "dev-mkdocs"
+Requires-Dist: griffe-warnings-deprecated==1.1.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.7; extra == "dev-mkdocs"
+Requires-Dist: frequenz-repo-config[lib]==0.19.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.1; 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.8.17; extra == "dev-noxfile"
+Requires-Dist: frequenz-repo-config[lib]==0.19.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.8; extra == "dev-pytest"
+Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.19.0; extra == "dev-pytest"
+Requires-Dist: pytest-mock==3.16.0; 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.168.2; 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
@@ -72,8 +73,8 @@ Dynamic: license-file
 
 Core utilities to complement Python's standard library. This library provides
 essential building blocks for Python applications, including mathematical
-utilities, datetime constants, typing helpers, strongly-typed identifiers, and
-module introspection tools.
+utilities, datetime constants, typing helpers, strongly-typed identifiers,
+module introspection tools, and warning and deprecation helpers.
 
 The `frequenz-core` library is designed to be lightweight, type-safe, and
 follow modern Python best practices. It fills common gaps in the standard
@@ -83,8 +84,8 @@ library with utilities that are frequently needed across different projects.
 
 The following platforms are officially supported (tested):
 
-- **Python:** 3.11
-- **Operating System:** Ubuntu Linux 20.04
+- **Python:** 3.11, 3.12, 3.13, 3.14
+- **Operating System:** Ubuntu Linux 24.04
 - **Architectures:** amd64, arm64
 
 ## Installation
@@ -156,7 +157,7 @@ positive = Interval(0, None)  # [0, ∞]
 assert 1000 in positive  # True
 ```
 
-### `Enum` with deprecated members
+### `Enum` Utilities
 
 Define enums with deprecated members that raise deprecation warnings when
 accessed:
@@ -200,6 +201,102 @@ 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"
+```
+
+### Warnings/Deprecations Utilities
+
+Silence a warning around a call without the side effect
+[`warnings.catch_warnings`](https://docs.python.org/3/library/warnings.html#warnings.catch_warnings)
+has, which is to reset the deduplication history of the whole program, so
+every warning already shown is shown again
+([python/cpython#73858](https://github.com/python/cpython/issues/73858)):
+
+```python
+import warnings
+
+from frequenz.core.warnings import ignoring_deprecations
+
+def legacy_parse(raw: str) -> int:
+    warnings.warn("legacy_parse() is deprecated", DeprecationWarning, stacklevel=2)
+    return int(raw)
+
+def parse(raw: str) -> int:
+    # Only around the call that reaches the deprecated symbol.
+    with ignoring_deprecations():
+        return legacy_parse(raw)
+
+with warnings.catch_warnings(record=True, action="default") as shown:
+    for _ in range(10):
+        warnings.warn("said once", UserWarning)
+        parse("1")
+
+assert len(shown) == 1  # ✅ `catch_warnings()` in `parse()` would show it 10 times
+```
+
+Keep the old import path of a symbol that moved working, serving the very same
+object so `isinstance` keeps working through both paths:
+
+```python
+from typing import TYPE_CHECKING, TypeAlias
+
+from frequenz.core.warnings import DeprecatedAlias, deprecated_aliases
+
+if TYPE_CHECKING:
+    # Type checkers can't see the runtime `__getattr__` in the `else` branch.
+    from decimal import Decimal as _Decimal
+    from fractions import Fraction as _Fraction
+
+    Decimal: TypeAlias = _Decimal
+    Rational: TypeAlias = _Fraction
+else:
+    # In the `else`, never at module level: a `__getattr__` mypy can see makes
+    # every name it doesn't know in this module `Any`, typos in downstream
+    # imports included.
+    __getattr__ = deprecated_aliases(
+        __name__,
+        # Warns "<module>.Decimal is deprecated since v1.2.0. Use
+        # decimal.Decimal instead."
+        DeprecatedAlias("Decimal", new_module="decimal", since="v1.2.0"),
+        # Renamed on the way out
+        DeprecatedAlias(
+            "Rational", new_module="fractions", new_name="Fraction", since="v1.3.0"
+        ),
+    )
+```
+
+And check in a test that a piece of code doesn't warn, without the `"error"`
+filter that would make `warnings.warn()` raise inside the code under test:
+
+```python
+from frequenz.core.warnings import asserting_no_deprecations
+
+def parse(raw: str) -> int:
+    return int(raw)
+
+with asserting_no_deprecations():
+    assert parse("1") == 1
+```
+
 ### Strongly-Typed IDs
 
 Create type-safe identifiers for different entities:

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

@@ -8,8 +8,8 @@
 
 Core utilities to complement Python's standard library. This library provides
 essential building blocks for Python applications, including mathematical
-utilities, datetime constants, typing helpers, strongly-typed identifiers, and
-module introspection tools.
+utilities, datetime constants, typing helpers, strongly-typed identifiers,
+module introspection tools, and warning and deprecation helpers.
 
 The `frequenz-core` library is designed to be lightweight, type-safe, and
 follow modern Python best practices. It fills common gaps in the standard
@@ -19,8 +19,8 @@ library with utilities that are frequently needed across different projects.
 
 The following platforms are officially supported (tested):
 
-- **Python:** 3.11
-- **Operating System:** Ubuntu Linux 20.04
+- **Python:** 3.11, 3.12, 3.13, 3.14
+- **Operating System:** Ubuntu Linux 24.04
 - **Architectures:** amd64, arm64
 
 ## Installation
@@ -92,7 +92,7 @@ positive = Interval(0, None)  # [0, ∞]
 assert 1000 in positive  # True
 ```
 
-### `Enum` with deprecated members
+### `Enum` Utilities
 
 Define enums with deprecated members that raise deprecation warnings when
 accessed:
@@ -136,6 +136,102 @@ 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"
+```
+
+### Warnings/Deprecations Utilities
+
+Silence a warning around a call without the side effect
+[`warnings.catch_warnings`](https://docs.python.org/3/library/warnings.html#warnings.catch_warnings)
+has, which is to reset the deduplication history of the whole program, so
+every warning already shown is shown again
+([python/cpython#73858](https://github.com/python/cpython/issues/73858)):
+
+```python
+import warnings
+
+from frequenz.core.warnings import ignoring_deprecations
+
+def legacy_parse(raw: str) -> int:
+    warnings.warn("legacy_parse() is deprecated", DeprecationWarning, stacklevel=2)
+    return int(raw)
+
+def parse(raw: str) -> int:
+    # Only around the call that reaches the deprecated symbol.
+    with ignoring_deprecations():
+        return legacy_parse(raw)
+
+with warnings.catch_warnings(record=True, action="default") as shown:
+    for _ in range(10):
+        warnings.warn("said once", UserWarning)
+        parse("1")
+
+assert len(shown) == 1  # ✅ `catch_warnings()` in `parse()` would show it 10 times
+```
+
+Keep the old import path of a symbol that moved working, serving the very same
+object so `isinstance` keeps working through both paths:
+
+```python
+from typing import TYPE_CHECKING, TypeAlias
+
+from frequenz.core.warnings import DeprecatedAlias, deprecated_aliases
+
+if TYPE_CHECKING:
+    # Type checkers can't see the runtime `__getattr__` in the `else` branch.
+    from decimal import Decimal as _Decimal
+    from fractions import Fraction as _Fraction
+
+    Decimal: TypeAlias = _Decimal
+    Rational: TypeAlias = _Fraction
+else:
+    # In the `else`, never at module level: a `__getattr__` mypy can see makes
+    # every name it doesn't know in this module `Any`, typos in downstream
+    # imports included.
+    __getattr__ = deprecated_aliases(
+        __name__,
+        # Warns "<module>.Decimal is deprecated since v1.2.0. Use
+        # decimal.Decimal instead."
+        DeprecatedAlias("Decimal", new_module="decimal", since="v1.2.0"),
+        # Renamed on the way out
+        DeprecatedAlias(
+            "Rational", new_module="fractions", new_name="Fraction", since="v1.3.0"
+        ),
+    )
+```
+
+And check in a test that a piece of code doesn't warn, without the `"error"`
+filter that would make `warnings.warn()` raise inside the code under test:
+
+```python
+from frequenz.core.warnings import asserting_no_deprecations
+
+def parse(raw: str) -> int:
+    return int(raw)
+
+with asserting_no_deprecations():
+    assert parse("1") == 1
+```
+
 ### Strongly-Typed IDs
 
 Create type-safe identifiers for different entities:

frequenz_core-1.5.0/RELEASE_NOTES.md

@@ -0,0 +1,11 @@
+# Frequenz Core Library Release Notes
+
+## New Features
+
+A new `frequenz.core.warnings` module with:
+
+- `ignoring_warnings()` and `ignoring_deprecations()` to silence warnings/deprecations around a piece of code. Unlike `warnings.catch_warnings()`, entering and leaving it doesn't reset the warnings deduplication history of the program, so warnings already shown are not shown again, working around [python/cpython#73858](https://github.com/python/cpython/issues/73858). It costs about the same as the standard library block, so it is also usable on a hot path, where repairing the damage afterwards would not be.
+
+- `asserting_no_warnings()`, and its `asserting_no_deprecations()` shortcut, fail when the code in the block raises a matching warning/deprecation, listing each one with the place it came from. They are meant for tests, and are a better tool than an `"error"` filter, which makes `warnings.warn()` raise inside the code under test and so changes the very behaviour the test is checking.
+
+- `deprecated_aliases()` builds a module `__getattr__` that warns when a symbol that moved to another module, or was renamed, is reached through its old import path, serving the very same object so `isinstance` keeps working through both paths.

{frequenz_core-1.3.0 → frequenz_core-1.5.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 == 84.0.0",
+  "setuptools_scm[toml] == 10.3.4",
+  "frequenz-repo-config[lib] == 0.19.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",
@@ -46,45 +46,47 @@ email = "floss@frequenz.com"
 
 [project.optional-dependencies]
 dev-flake8 = [
-  "flake8 == 7.3.0",
+  "flake8 == 7.4.1",
+  "flake8-datetimez == 26.8.1",
   "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.10.0",
   "pydocstyle == 6.3.0",
 ]
-dev-formatting = ["black == 25.1.0", "isort == 6.0.1"]
+dev-formatting = ["black == 26.5.1", "isort == 9.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.11",
+  "black == 26.5.1",
+  "griffe-warnings-deprecated == 1.1.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.7",
+  "frequenz-repo-config[lib] == 0.19.0",
 ]
 dev-mypy = [
-  "mypy == 1.17.1",
-  "types-Markdown == 3.8.0.20250809",
+  "mypy == 2.3.1",
+  "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.8.17", "frequenz-repo-config[lib] == 0.19.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.8", # We need this to check for the examples
+  "frequenz-repo-config[extra-lint-examples] == 0.19.0",
+  "pytest-mock == 3.16.0",
+  "pytest-asyncio == 1.4.0",
+  "async-solipsism == 0.9",
+  "hypothesis == 6.168.2",
 ]
 dev = [
   "frequenz-core[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
@@ -123,6 +125,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']
@@ -155,13 +161,25 @@ disable = [
 ]
 
 [tool.pytest.ini_options]
-addopts = "-W=all -Werror -Wdefault::DeprecationWarning -Wdefault::PendingDeprecationWarning -vv"
+filterwarnings = [
+  "error",
+  "once::DeprecationWarning",
+  "once::PendingDeprecationWarning",
+  # We ignore warnings about protobuf gencode version being one version older
+  # than the current version, as this is supported by protobuf, and we expect to
+  # have such cases. If we go too far, we will get a proper error anyways.
+  # We use a raw string (single quotes) to avoid the need to escape special
+  # characters as this is a regex.
+  'ignore:Protobuf gencode version .*exactly one major version older.*:UserWarning',
+]
 testpaths = ["tests", "src"]
+asyncio_debug = true
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 required_plugins = ["pytest-asyncio", "pytest-mock"]
 
 [tool.mypy]
+enable_error_code = ["exhaustive-match"]
 explicit_package_bases = true
 namespace_packages = true
 # This option disables mypy cache, and it is sometimes useful to enable it if

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

@@ -76,11 +76,13 @@ class DeprecatingEnumType(enum.EnumType):
 
     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:
@@ -98,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)
 

{frequenz_core-1.3.0 → frequenz_core-1.5.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))