frequenz-core 1.0.0__tar.gz

frequenz_core-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

frequenz_core-1.0.0/MANIFEST.in

@@ -0,0 +1,13 @@
+exclude .cookiecutter-replay.json
+exclude .editorconfig
+exclude .gitignore
+exclude CODEOWNERS
+exclude CONTRIBUTING.md
+exclude mkdocs.yml
+exclude noxfile.py
+exclude src/conftest.py
+recursive-exclude .github *
+recursive-exclude benchmarks *
+recursive-exclude docs *
+recursive-exclude tests *
+recursive-include py *.pyi

frequenz_core-1.0.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: frequenz-core
+Version: 1.0.0
+Summary: Core utilities to complement Python's standard library
+Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
+License: 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
+Project-URL: Repository, https://github.com/frequenz-floss/frequenz-core-python
+Project-URL: Support, https://github.com/frequenz-floss/frequenz-core-python/discussions/categories/support
+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
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions<5,>=4.13.0
+Provides-Extra: dev-flake8
+Requires-Dist: flake8==7.2.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.6; 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"
+Provides-Extra: dev-mkdocs
+Requires-Dist: Markdown==3.8; 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.7; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.6.14; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings[python]==0.29.1; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings-python==1.16.11; extra == "dev-mkdocs"
+Requires-Dist: frequenz-repo-config[lib]==0.13.4; extra == "dev-mkdocs"
+Provides-Extra: dev-mypy
+Requires-Dist: mypy==1.16.0; extra == "dev-mypy"
+Requires-Dist: types-Markdown==3.8.0.20250415; 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.4; 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.3.5; extra == "dev-pytest"
+Requires-Dist: pylint==3.3.7; extra == "dev-pytest"
+Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.13.4; extra == "dev-pytest"
+Requires-Dist: pytest-mock==3.14.1; extra == "dev-pytest"
+Requires-Dist: pytest-asyncio==0.26.0; extra == "dev-pytest"
+Requires-Dist: async-solipsism==0.7; extra == "dev-pytest"
+Requires-Dist: hypothesis==6.132.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
+
+# Frequenz Core Library
+
+[![Build Status](https://github.com/frequenz-floss/frequenz-core-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-core-python/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/frequenz-core)](https://pypi.org/project/frequenz-core/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-core-python/)
+
+## Introduction
+
+Core utilities to complement Python's standard library.
+
+## Documentation
+
+For information on how to use this library, please refer to the
+[documentation](https://frequenz-floss.github.io/frequenz-core-python/).
+
+## Supported Platforms
+
+The following platforms are officially supported (tested):
+
+- **Python:** 3.11
+- **Operating System:** Ubuntu Linux 20.04
+- **Architectures:** amd64, arm64
+
+## Contributing
+
+If you want to know how to build this project and contribute to it, please
+check out the [Contributing Guide](CONTRIBUTING.md).

frequenz_core-1.0.0/README.md

@@ -0,0 +1,27 @@
+# Frequenz Core Library
+
+[![Build Status](https://github.com/frequenz-floss/frequenz-core-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-core-python/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/frequenz-core)](https://pypi.org/project/frequenz-core/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-core-python/)
+
+## Introduction
+
+Core utilities to complement Python's standard library.
+
+## Documentation
+
+For information on how to use this library, please refer to the
+[documentation](https://frequenz-floss.github.io/frequenz-core-python/).
+
+## Supported Platforms
+
+The following platforms are officially supported (tested):
+
+- **Python:** 3.11
+- **Operating System:** Ubuntu Linux 20.04
+- **Architectures:** amd64, arm64
+
+## Contributing
+
+If you want to know how to build this project and contribute to it, please
+check out the [Contributing Guide](CONTRIBUTING.md).

frequenz_core-1.0.0/RELEASE_NOTES.md

@@ -0,0 +1,14 @@
+# Frequenz Core Library Release Notes
+
+## Summary
+
+This is the initial release of the Frequenz Core Library, which provides a set of fundamental tools and utilities for Python.
+
+The library currently includes:
+
+- `datetime`: For utilities related to dates and times.
+* `id`: For creating unique system-wide ID types.
+* `math`: For utilities related to math.
+* `typing`: For type annotations and type-checking utilities.
+
+But more tools will be added in the future.

frequenz_core-1.0.0/pyproject.toml

@@ -0,0 +1,181 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+[build-system]
+requires = [
+  "setuptools == 80.9.0",
+  "setuptools_scm[toml] == 8.3.1",
+  "frequenz-repo-config[lib] == 0.13.4",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "frequenz-core"
+description = "Core utilities to complement Python's standard library"
+readme = "README.md"
+license = { text = "MIT" }
+keywords = [
+  "asyncio",
+  "collections",
+  "core",
+  "datetime",
+  "frequenz",
+  "lib",
+  "library",
+  "math",
+  "python",
+  "stdlib",
+  "typing",
+]
+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",
+  "Typing :: Typed",
+]
+requires-python = ">= 3.11, < 4"
+dependencies = ["typing-extensions >= 4.13.0, < 5"]
+dynamic = ["version"]
+
+[[project.authors]]
+name = "Frequenz Energy-as-a-Service GmbH"
+email = "floss@frequenz.com"
+
+[project.optional-dependencies]
+dev-flake8 = [
+  "flake8 == 7.2.0",
+  "flake8-docstrings == 1.7.0",
+  "flake8-pyproject == 1.2.3", # For reading the flake8 config from pyproject.toml
+  "pydoclint == 0.6.6",
+  "pydocstyle == 6.3.0",
+]
+dev-formatting = ["black == 25.1.0", "isort == 6.0.1"]
+dev-mkdocs = [
+  "Markdown == 3.8",
+  "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.7",
+  "mkdocs-material == 9.6.14",
+  "mkdocstrings[python] == 0.29.1",
+  "mkdocstrings-python == 1.16.11",
+  "frequenz-repo-config[lib] == 0.13.4",
+]
+dev-mypy = [
+  "mypy == 1.16.0",
+  "types-Markdown == 3.8.0.20250415",
+  # 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.4"]
+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.3.5",
+  "pylint == 3.3.7", # We need this to check for the examples
+  "frequenz-repo-config[extra-lint-examples] == 0.13.4",
+  "pytest-mock == 3.14.1",
+  "pytest-asyncio == 0.26.0",
+  "async-solipsism == 0.7",
+  "hypothesis == 6.132.0",
+]
+dev = [
+  "frequenz-core[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
+]
+
+[project.urls]
+Documentation = "https://frequenz-floss.github.io/frequenz-core-python/"
+Changelog = "https://github.com/frequenz-floss/frequenz-core-python/releases"
+Issues = "https://github.com/frequenz-floss/frequenz-core-python/issues"
+Repository = "https://github.com/frequenz-floss/frequenz-core-python"
+Support = "https://github.com/frequenz-floss/frequenz-core-python/discussions/categories/support"
+
+[tool.black]
+line-length = 88
+target-version = ['py311']
+include = '\.pyi?$'
+
+[tool.isort]
+profile = "black"
+line_length = 88
+src_paths = ["benchmarks", "examples", "src", "tests"]
+
+[tool.flake8]
+# We give some flexibility to go over 88, there are cases like long URLs or
+# code in documenation that have extra indentation. Black will still take care
+# of making everything that can be 88 wide, 88 wide.
+max-line-length = 100
+extend-ignore = [
+  "E203", # Whitespace before ':' (conflicts with black)
+  "W503", # Line break before binary operator (conflicts with black)
+]
+# pydoclint options
+style = "google"
+check-return-types = false
+check-yield-types = false
+arg-type-hints-in-docstring = false
+arg-type-hints-in-signature = true
+allow-init-docstring = true
+
+[tool.pylint.similarities]
+ignore-comments = ['yes']
+ignore-docstrings = ['yes']
+ignore-imports = ['no']
+min-similarity-lines = 40
+
+[tool.pylint.messages_control]
+disable = [
+  "too-few-public-methods",
+  "too-many-return-statements",
+  # disabled because it conflicts with isort
+  "wrong-import-order",
+  "ungrouped-imports",
+  # pylint's unsubscriptable check is buggy and is not needed because
+  # it is a type-check, for which we already have mypy.
+  "unsubscriptable-object",
+  # Checked by flake8
+  "f-string-without-interpolation",
+  "line-too-long",
+  "missing-function-docstring",
+  "redefined-outer-name",
+  "unnecessary-lambda-assignment",
+  "unused-import",
+  "unused-variable",
+  # Checked by mypy
+  "no-member",
+  "possibly-used-before-assignment",
+  "no-name-in-module",
+]
+
+[tool.pytest.ini_options]
+addopts = "-W=all -Werror -Wdefault::DeprecationWarning -Wdefault::PendingDeprecationWarning -vv"
+testpaths = ["tests", "src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+required_plugins = ["pytest-asyncio", "pytest-mock"]
+
+[tool.mypy]
+explicit_package_bases = true
+namespace_packages = true
+# This option disables mypy cache, and it is sometimes useful to enable it if
+# you are getting weird intermittent error, or error in the CI but not locally
+# (or vice versa). In particular errors saying that type: ignore is not
+# used but getting the original ignored error when removing the type: ignore.
+# See for example: https://github.com/python/mypy/issues/2960
+#no_incremental = true
+packages = ["frequenz.core"]
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["mkdocs_macros.*", "sybil", "sybil.*", "async_solipsism"]
+ignore_missing_imports = true
+
+[tool.setuptools_scm]
+version_scheme = "post-release"

frequenz_core-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

frequenz_core-1.0.0/src/frequenz/core/__init__.py

@@ -0,0 +1,4 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Core utilities to complement Python's standard library."""

frequenz_core-1.0.0/src/frequenz/core/conftest.py

@@ -0,0 +1,13 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Validate docstring code examples.
+
+Code examples are often wrapped in triple backticks (```) within docstrings.
+This plugin extracts these code examples and validates them using pylint.
+"""
+
+from frequenz.repo.config.pytest import examples
+from sybil import Sybil
+
+pytest_collect_file = Sybil(**examples.get_sybil_arguments()).pytest()

frequenz_core-1.0.0/src/frequenz/core/datetime.py

@@ -0,0 +1,10 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Timeseries basic types."""
+
+from datetime import datetime, timezone
+from typing import Final
+
+UNIX_EPOCH: Final[datetime] = datetime.fromtimestamp(0.0, tz=timezone.utc)
+"""The UNIX epoch (in UTC)."""

frequenz_core-1.0.0/src/frequenz/core/id.py

@@ -0,0 +1,194 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+r'''Provides strongly-typed unique identifiers for entities.
+
+This module offers a base class, [`BaseId`][frequenz.core.id.BaseId], which can be
+subclassed to create distinct ID types for different components or concepts within
+a system.
+
+These IDs ensure type safety, meaning that an ID for one type of entity (e.g., a
+sensor) cannot be mistakenly used where an ID for another type (e.g., a
+microgrid) is expected.
+
+# Creating Custom ID Types
+
+To define a new ID type, create a class that inherits from
+[`BaseId`][frequenz.core.id.BaseId] and provide a unique `str_prefix` as a keyword
+argument in the class definition. This prefix is used in the string representation of
+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
+    the class.
+
+To encourage consistency, the class name must end with the suffix "Id" (e.g.,
+`MyNewId`). This check can be bypassed by passing `allow_custom_name=True` when
+defining the class (e.g., `class MyCustomName(BaseId, str_prefix="MCN",
+allow_custom_name=True):`).
+
+Tip:
+    Use the [`@typing.final`][typing.final] decorator to prevent subclassing of
+    ID classes.
+
+Example: Creating a standard ID type
+    ```python
+    from typing import final
+    from frequenz.core.id import BaseId
+
+    @final
+    class InverterId(BaseId, str_prefix="INV"):
+        """A unique identifier for an inverter."""
+
+    inv_id = InverterId(123)
+    print(inv_id)       # Output: INV123
+    print(int(inv_id))  # Output: 123
+    ```
+
+Example: Creating an ID type with a non-standard name
+    ```python
+    from typing import final
+    from frequenz.core.id import BaseId
+
+    @final
+    class CustomNameForId(BaseId, str_prefix="CST", allow_custom_name=True):
+        """An ID with a custom name, not ending in 'Id'."""
+
+    custom_id = CustomNameForId(456)
+    print(custom_id)       # Output: CST456
+    print(int(custom_id))  # Output: 456
+    ```
+'''
+
+
+from typing import Any, ClassVar, Self, cast
+
+
+class BaseId:
+    """A base class for unique identifiers.
+
+    Subclasses must provide a unique `str_prefix` keyword argument during
+    definition, which is used in the string representation of the ID.
+
+    By default, subclass names must end with "Id". This can be overridden by
+    passing `allow_custom_name=True` during class definition.
+
+    For more information and examples, see the [module's
+    documentation][frequenz.core.id].
+    """
+
+    _id: int
+    _str_prefix: ClassVar[str]
+    _registered_prefixes: ClassVar[set[str]] = set()
+
+    def __new__(cls, *_: Any, **__: Any) -> Self:
+        """Create a new instance of the ID class, only if it is a subclass of BaseId."""
+        if cls is BaseId:
+            raise TypeError("BaseId cannot be instantiated directly. Use a subclass.")
+        return super().__new__(cls)
+
+    def __init_subclass__(
+        cls,
+        *,
+        str_prefix: str,
+        allow_custom_name: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize a subclass, set its string prefix, and perform checks.
+
+        Args:
+            str_prefix: The string prefix for the ID type (e.g., "MID").
+                Must be unique across all ID types.
+            allow_custom_name: If True, bypasses the check that the class name
+                must end with "Id". Defaults to False.
+            **kwargs: Forwarded to the parent's __init_subclass__.
+
+        Raises:
+            ValueError: If the `str_prefix` is already registered by another
+                ID type.
+            TypeError: If `allow_custom_name` is False and the class name
+                does not end with "Id".
+        """
+        super().__init_subclass__(**kwargs)
+
+        if str_prefix in BaseId._registered_prefixes:
+            raise ValueError(
+                f"Prefix '{str_prefix}' is already registered. "
+                "ID prefixes must be unique."
+            )
+        BaseId._registered_prefixes.add(str_prefix)
+
+        if not allow_custom_name and not cls.__name__.endswith("Id"):
+            raise TypeError(
+                f"Class name '{cls.__name__}' for an ID class must end with 'Id' "
+                "(e.g., 'SomeId'), or use `allow_custom_name=True`."
+            )
+
+        cls._str_prefix = str_prefix
+
+    def __init__(self, id_: int, /) -> None:
+        """Initialize this instance.
+
+        Args:
+            id_: The numeric unique identifier.
+
+        Raises:
+            ValueError: If the ID is negative.
+        """
+        if id_ < 0:
+            raise ValueError(f"{type(self).__name__} can't be negative.")
+        self._id = id_
+
+    @property
+    def str_prefix(self) -> str:
+        """The prefix used for the string representation of this ID."""
+        return self._str_prefix
+
+    def __int__(self) -> int:
+        """Return the numeric ID of this instance."""
+        return self._id
+
+    def __eq__(self, other: object) -> bool:
+        """Check if this instance is equal to another object.
+
+        Equality is defined as being of the exact same type and having the same
+        underlying ID.
+        """
+        # pylint thinks this is not an unidiomatic typecheck, but in this case
+        # it is not. isinstance() returns True for subclasses, which is not
+        # what we want here, as different ID types should never be equal.
+        # pylint: disable-next=unidiomatic-typecheck
+        if type(other) is not type(self):
+            return NotImplemented
+        # We already checked type(other) is type(self), but mypy doesn't
+        # understand that, so we need to cast it to Self.
+        other_id = cast(Self, other)
+        return self._id == other_id._id
+
+    def __lt__(self, other: object) -> bool:
+        """Check if this instance is less than another object.
+
+        Comparison is only defined between instances of the exact same type.
+        """
+        # pylint: disable-next=unidiomatic-typecheck
+        if type(other) is not type(self):
+            return NotImplemented
+        other_id = cast(Self, other)
+        return self._id < other_id._id
+
+    def __hash__(self) -> int:
+        """Return the hash of this instance.
+
+        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.
+        """
+        return hash((type(self), self._id))
+
+    def __repr__(self) -> str:
+        """Return the string representation of this instance."""
+        return f"{type(self).__name__}({self._id!r})"
+
+    def __str__(self) -> str:
+        """Return the short string representation of this instance."""
+        return f"{self._str_prefix}{self._id}"

frequenz_core-1.0.0/src/frequenz/core/math.py

@@ -0,0 +1,116 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Math tools."""
+
+import math
+from dataclasses import dataclass
+from typing import Generic, Protocol, Self, TypeVar, cast
+
+
+def is_close_to_zero(value: float, abs_tol: float = 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
+    and robustness for floating-point numbers comparisons close to zero. Note
+    that this is also the default value for the relative tolerance.
+    For more technical details, see https://peps.python.org/pep-0485/#behavior-near-zero
+
+    Args:
+        value: The floating point value to compare to.
+        abs_tol: The minimum absolute tolerance. Defaults to 1e-9.
+
+    Returns:
+        Whether the floating point value is close to zero.
+    """
+    zero: float = 0.0
+    return math.isclose(a=value, b=zero, abs_tol=abs_tol)
+
+
+class LessThanComparable(Protocol):
+    """A protocol that requires the `__lt__` method to compare values."""
+
+    def __lt__(self, other: Self, /) -> bool:
+        """Return whether self is less than other."""
+
+
+LessThanComparableOrNoneT = TypeVar(
+    "LessThanComparableOrNoneT", bound=LessThanComparable | None
+)
+"""Type variable for a value that a `LessThanComparable` or `None`."""
+
+
+@dataclass(frozen=True, repr=False)
+class Interval(Generic[LessThanComparableOrNoneT]):
+    """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.
+
+    If the `start` or `end` is `None`, it means that the interval is unbounded in that
+    direction.
+
+    If `start` is bigger than `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."""
+
+    end: LessThanComparableOrNoneT
+    """The end of the interval."""
+
+    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:
+            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.
+
+        Args:
+            item: The value to check.
+
+        Returns:
+            bool: True if value is within the range, otherwise False.
+        """
+        if item is None:
+            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)
+        )
+
+    def __repr__(self) -> str:
+        """Return a string representation of this instance."""
+        return f"Interval({self.start!r}, {self.end!r})"
+
+    def __str__(self) -> str:
+        """Return a string representation of this instance."""
+        start = "∞" if self.start is None else str(self.start)
+        end = "∞" if self.end is None else str(self.end)
+        return f"[{start}, {end}]"

frequenz_core-1.0.0/src/frequenz/core/module.py

@@ -0,0 +1,36 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Tools for dealing with Python modules."""
+
+
+def get_public_module_name(module_name: str) -> str | None:
+    """Get the name of the public module containing the given module name.
+
+    * Modules are considered private if they start with `_`.
+    * All modules inside a private module are also considered private, even if they
+      don't start with `_`.
+    * If there is no leading public part, `None` is returned.
+
+    Example:
+        Here are a few examples of how this function will resolve module names:
+
+        * `some.pub` -> `some.pub`
+        * `some.pub._some._priv` -> `some.pub`
+        * `some.pub._some._priv.public` -> `some.pub`
+        * `some.pub._some._priv.public._private` -> `some.pub`
+        * `_priv` -> `None`
+
+    Args:
+        module_name: The fully qualified name of the module to get the public name for
+            (normally the `__name__` built-in variable).
+
+    Returns:
+        The name of the public module containing the given module name.
+    """
+    public_parts: list[str] = []
+    for part in module_name.split("."):
+        if part.startswith("_"):
+            break
+        public_parts.append(part)
+    return ".".join(public_parts) or None

frequenz_core-1.0.0/src/frequenz/core/typing.py

@@ -0,0 +1,311 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Type hints and utility functions for type checking and types.
+
+This module provides a decorator to disable the `__init__` constructor of a class, to
+force the use of a factory method to create instances. See
+[`@disable_init`][frequenz.core.typing.disable_init] for more information.
+
+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]).
+"""
+
+from collections.abc import Callable
+from typing import Any, NoReturn, TypeVar, cast, overload
+
+TypeT = TypeVar("TypeT", bound=type)
+"""A type variable that is bound to a type."""
+
+
+@overload
+def disable_init(
+    cls: None = None,
+    *,
+    error: Exception | None = None,
+) -> Callable[[TypeT], TypeT]: ...
+
+
+@overload
+def disable_init(cls: TypeT) -> TypeT: ...
+
+
+def disable_init(
+    cls: TypeT | None = None,
+    *,
+    error: Exception | None = None,
+) -> TypeT | Callable[[TypeT], TypeT]:
+    """Disable the `__init__` constructor of a class.
+
+    This decorator can be used to disable the `__init__` constructor of a class. It is
+    intended to be used with classes that don't provide a default constructor and
+    require the use of a factory method to create instances.
+
+    When marking a class with this decorator, the class cannot be even declared with a
+    `__init__` method, as it will raise a `TypeError` when the class is created, as soon
+    as the class is parsed by the Python interpreter. It will also raise a `TypeError`
+    when the `__init__` method is called.
+
+    To create an instance you must provide a factory method, using `__new__`.
+
+    Warning:
+        This decorator will use a custom metaclass to disable the `__init__` constructor
+        of the class, so if your class already uses a custom metaclass, you should be
+        aware of potential conflicts. See
+        [`NoInitConstructibleMeta`][frequenz.core.typing.NoInitConstructibleMeta] for an
+        example on how to use more than one metaclass.
+
+        It is also recommended to apply this decorator only to classes inheriting from
+        `object` directly (i.e. not explicitly inheriting from any other classes), as
+        things can also get tricky when applying the constructor to a sub-class for the
+        first time.
+
+    Example: Basic example defining a class with a factory method
+        To be able to type hint the class correctly, you can declare the instance
+        attributes in the class body, and then use a factory method to create instances.
+
+        ```python
+        from typing import Self
+
+        @disable_init
+        class MyClass:
+            value: int
+
+            @classmethod
+            def new(cls, value: int = 1) -> Self:
+                self = cls.__new__(cls)
+                self.value = value
+                return self
+
+        instance = MyClass.new()
+
+        # Calling the default constructor (__init__) will raise a TypeError
+        try:
+            instance = MyClass()
+        except TypeError as e:
+            print(e)
+        ```
+
+    Example: Class wrongly providing an `__init__` constructor
+        ```python
+        try:
+            @disable_init
+            class MyClass:
+                def __init__(self) -> None:
+                    pass
+        except TypeError as e:
+            assert isinstance(e, TypeError)
+            print(e)
+        ```
+
+    Example: Using a custom error message when the default constructor is called
+        ```python
+        from typing import Self
+
+        class NoInitError(TypeError):
+            def __init__(self) -> None:
+                super().__init__("Please create instances of MyClass using MyClass.new()")
+
+        @disable_init(error=NoInitError())
+        class MyClass:
+            @classmethod
+            def new(cls) -> Self:
+                return cls.__new__(cls)
+
+        try:
+            instance = MyClass()
+        except NoInitError as e:
+            assert str(e) == "Please create instances of MyClass using MyClass.new()"
+            print(e)
+        ```
+
+    Args:
+        cls: The class to be decorated.
+        error: The error to raise if __init__ is called, if `None` a default
+            [TypeError][] will be raised.
+
+    Returns:
+        A decorator that disables the `__init__` constructor of `cls`.
+    """
+
+    def decorator(inner_cls: TypeT) -> TypeT:
+        return cast(
+            TypeT,
+            NoInitConstructibleMeta(
+                inner_cls.__name__,
+                inner_cls.__bases__,
+                dict(inner_cls.__dict__),
+                no_init_constructible_error=error,
+            ),
+        )
+
+    if cls is None:
+        return decorator
+    return decorator(cls)
+
+
+class NoInitConstructibleMeta(type):
+    """A metaclass that disables the `__init__` constructor.
+
+    This metaclass can be used to disable the `__init__` constructor of a class. It is
+    intended to be used with classes that don't provide a default constructor and
+    require the use of a factory method to create instances.
+
+    When marking a class using this metaclass, the class cannot be even declared with a
+    `__init__` method, as it will raise a `TypeError` when the class is created, as soon
+    as the class is parsed by the Python interpreter. It will also raise a `TypeError`
+    when the `__init__` method is called.
+
+    To create an instance you must provide a factory method, using `__new__`.
+
+    Warning:
+        It is also recommended to apply this metaclass only to classes inheriting from
+        `object` directly (i.e. not explicitly inheriting from any other classes), as
+        things can also get tricky when applying the constructor to a sub-class for the
+        first time.
+
+    Example: Basic example defining a class with a factory method
+        To be able to type hint the class correctly, you can declare the instance
+        attributes in the class body, and then use a factory method to create instances.
+
+        ```python
+        from typing import Self
+
+        class MyClass(metaclass=NoInitConstructibleMeta):
+            value: int
+
+            @classmethod
+            def new(cls, value: int = 1) -> Self:
+                self = cls.__new__(cls)
+                self.value = value
+                return self
+
+        instance = MyClass.new()
+
+        # Calling the default constructor (__init__) will raise a TypeError
+        try:
+            instance = MyClass()
+        except TypeError as e:
+            print(e)
+        ```
+
+        Hint:
+            The [`@disable_init`][frequenz.core.typing.disable_init] decorator is a more
+            convenient way to use this metaclass.
+
+    Example: Example combining with other metaclass
+        A typical case where you might want this is to combine with
+        [`abc.ABCMeta`][abc.ABCMeta] to create an abstract class that doesn't provide a
+        default constructor.
+
+        ```python
+        from abc import ABCMeta, abstractmethod
+        from typing import Self
+
+        class NoInitConstructibleABCMeta(ABCMeta, NoInitConstructibleMeta):
+            pass
+
+        class MyAbstractClass(metaclas=NoInitConstructibleABCMeta):
+            @abstractmethod
+            def do_something(self) -> None:
+                ...
+
+        class MyClass(MyAbstractClass):
+            value: int
+
+            @classmethod
+            def new(cls, value: int = 1) -> Self:
+                self = cls.__new__(cls)
+                self.value = value
+                return self
+
+            def do_something(self) -> None:
+                print("Doing something")
+
+        instance = MyClass.new()
+        instance.do_something()
+
+        # Calling the default constructor (__init__) will raise a TypeError
+        try:
+            instance = MyClass()
+        except TypeError as e:
+            print(e)
+        ```
+
+    """
+
+    # We need to use noqa here because pydoclint can't figure out that
+    # _get_no_init_constructible_error() returns a TypeError.
+    def __new__(  # noqa: DOC503
+        mcs,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        **kwargs: Any,
+    ) -> type:
+        """Create a new class with a disabled __init__ constructor.
+
+        Args:
+            name: The name of the new class.
+            bases: The base classes of the new class.
+            namespace: The namespace of the new class.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The new class with a disabled __init__ constructor.
+
+        Raises:
+            TypeError: If the class provides a default constructor.
+        """
+        if "__init__" in namespace:
+            raise _get_no_init_constructible_error(name, bases, **kwargs)
+        return super().__new__(mcs, name, bases, namespace)
+
+    def __init__(
+        cls,
+        name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the new class."""
+        super().__init__(name, bases, namespace)
+        cls._no_init_constructible_error = kwargs.get("no_init_constructible_error")
+
+    # We need to use noqa here because pydoclint can't figure out that
+    # _get_no_init_constructible_error() returns a TypeError.
+    def __call__(cls, *args: Any, **kwargs: Any) -> NoReturn:  # noqa: DOC503
+        """Raise an error when the __init__ constructor is called.
+
+        Args:
+            *args: ignored positional arguments.
+            **kwargs: ignored keyword arguments.
+
+        Raises:
+            TypeError: Always.
+        """
+        raise _get_no_init_constructible_error(
+            cls.__name__,
+            cls.__bases__,
+            no_init_constructible_error=cls._no_init_constructible_error,
+        )
+
+
+def _get_no_init_constructible_error(
+    name: str, bases: tuple[type, ...], **kwargs: Any
+) -> Exception:
+    error = kwargs.get("no_init_constructible_error")
+    if error is None:
+        for base in bases:
+            if attr := getattr(base, "_no_init_constructible_error", None):
+                error = attr
+                break
+        else:
+            error = TypeError(
+                f"{name} doesn't provide a default constructor, you must use a "
+                "factory method to create instances."
+            )
+    assert isinstance(error, Exception)
+    return error

frequenz_core-1.0.0/src/frequenz_core.egg-info/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: frequenz-core
+Version: 1.0.0
+Summary: Core utilities to complement Python's standard library
+Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
+License: 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
+Project-URL: Repository, https://github.com/frequenz-floss/frequenz-core-python
+Project-URL: Support, https://github.com/frequenz-floss/frequenz-core-python/discussions/categories/support
+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
+Classifier: Typing :: Typed
+Requires-Python: <4,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing-extensions<5,>=4.13.0
+Provides-Extra: dev-flake8
+Requires-Dist: flake8==7.2.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.6; 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"
+Provides-Extra: dev-mkdocs
+Requires-Dist: Markdown==3.8; 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.7; extra == "dev-mkdocs"
+Requires-Dist: mkdocs-material==9.6.14; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings[python]==0.29.1; extra == "dev-mkdocs"
+Requires-Dist: mkdocstrings-python==1.16.11; extra == "dev-mkdocs"
+Requires-Dist: frequenz-repo-config[lib]==0.13.4; extra == "dev-mkdocs"
+Provides-Extra: dev-mypy
+Requires-Dist: mypy==1.16.0; extra == "dev-mypy"
+Requires-Dist: types-Markdown==3.8.0.20250415; 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.4; 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.3.5; extra == "dev-pytest"
+Requires-Dist: pylint==3.3.7; extra == "dev-pytest"
+Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.13.4; extra == "dev-pytest"
+Requires-Dist: pytest-mock==3.14.1; extra == "dev-pytest"
+Requires-Dist: pytest-asyncio==0.26.0; extra == "dev-pytest"
+Requires-Dist: async-solipsism==0.7; extra == "dev-pytest"
+Requires-Dist: hypothesis==6.132.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
+
+# Frequenz Core Library
+
+[![Build Status](https://github.com/frequenz-floss/frequenz-core-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-core-python/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/frequenz-core)](https://pypi.org/project/frequenz-core/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-core-python/)
+
+## Introduction
+
+Core utilities to complement Python's standard library.
+
+## Documentation
+
+For information on how to use this library, please refer to the
+[documentation](https://frequenz-floss.github.io/frequenz-core-python/).
+
+## Supported Platforms
+
+The following platforms are officially supported (tested):
+
+- **Python:** 3.11
+- **Operating System:** Ubuntu Linux 20.04
+- **Architectures:** amd64, arm64
+
+## Contributing
+
+If you want to know how to build this project and contribute to it, please
+check out the [Contributing Guide](CONTRIBUTING.md).

frequenz_core-1.0.0/src/frequenz_core.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+README.md
+RELEASE_NOTES.md
+pyproject.toml
+src/frequenz/core/__init__.py
+src/frequenz/core/conftest.py
+src/frequenz/core/datetime.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
+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/top_level.txt

frequenz_core-1.0.0/src/frequenz_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,48 @@
+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.2.0
+flake8-docstrings==1.7.0
+flake8-pyproject==1.2.3
+pydoclint==0.6.6
+pydocstyle==6.3.0
+
+[dev-formatting]
+black==25.1.0
+isort==6.0.1
+
+[dev-mkdocs]
+Markdown==3.8
+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.7
+mkdocs-material==9.6.14
+mkdocstrings[python]==0.29.1
+mkdocstrings-python==1.16.11
+frequenz-repo-config[lib]==0.13.4
+
+[dev-mypy]
+mypy==1.16.0
+types-Markdown==3.8.0.20250415
+frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]
+
+[dev-noxfile]
+nox==2025.5.1
+frequenz-repo-config[lib]==0.13.4
+
+[dev-pylint]
+frequenz-core[dev-mkdocs,dev-noxfile,dev-pytest]
+
+[dev-pytest]
+pytest==8.3.5
+pylint==3.3.7
+frequenz-repo-config[extra-lint-examples]==0.13.4
+pytest-mock==3.14.1
+pytest-asyncio==0.26.0
+async-solipsism==0.7
+hypothesis==6.132.0

frequenz_core-1.0.0/src/frequenz_core.egg-info/top_level.txt

@@ -0,0 +1 @@
+frequenz