# Frequenz Core Library
[](https://github.com/frequenz-floss/frequenz-core-python/actions/workflows/ci.yaml)
[](https://pypi.org/project/frequenz-core/)
[](https://frequenz-floss.github.io/frequenz-core-python/)
## Introduction
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.
The `frequenz-core` library is designed to be lightweight, type-safe, and
follow modern Python best practices. It fills common gaps in the standard
library with utilities that are frequently needed across different projects.
## Supported Platforms
The following platforms are officially supported (tested):
- **Python:** 3.11
- **Operating System:** Ubuntu Linux 20.04
- **Architectures:** amd64, arm64
## Installation
You can install the library from PyPI using pip:
```bash
python -m pip install frequenz-core
```
Or add it to your project's dependencies in `pyproject.toml`:
```toml
[project]
dependencies = [
"frequenz-core >= 1.0.2, < 2",
]
```
> [!NOTE]
> We recommend pinning the dependency to the latest version for programs,
> like `"frequenz-core == 1.0.2"`, and specifying a version range spanning
> one major version for libraries, like `"frequenz-core >= 1.0.2, < 2"`.
> We follow [semver](https://semver.org/).
## Quick Start
Here's a quick overview of the main functionality:
```python
from frequenz.core.math import is_close_to_zero, Interval
from frequenz.core.datetime import UNIX_EPOCH
from frequenz.core.module import get_public_module_name
# Math utilities
print(is_close_to_zero(1e-10)) # True - check if float is close to zero
interval = Interval(1, 10)
print(5 in interval) # True - check if value is in range
# Datetime utilities
print(UNIX_EPOCH) # 1970-01-01 00:00:00+00:00
# Module utilities
public_name = get_public_module_name("my.package._private.module")
print(public_name) # "my.package"
```
## Code Examples
### Math Utilities
The math module provides utilities for floating-point comparisons and interval
checking:
```python
from frequenz.core.math import is_close_to_zero, Interval
# Robust floating-point zero comparison
assert is_close_to_zero(1e-10) # True
assert not is_close_to_zero(0.1) # False
# Interval checking with inclusive bounds
numbers = Interval(0, 100)
assert 50 in numbers # True
assert not (150 in numbers) # False - 150 is outside the interval
# Unbounded intervals
positive = Interval(0, None) # [0, ∞]
assert 1000 in positive # True
```
### `Enum` with deprecated members
Define enums with deprecated members that raise deprecation warnings when
accessed:
```python
from frequenz.core.enum import Enum, DeprecatedMember
class TaskStatus(Enum):
OPEN = 1
IN_PROGRESS = 2
PENDING = DeprecatedMember(1, "PENDING is deprecated, use OPEN instead")
DONE = DeprecatedMember(3, "DONE is deprecated, use FINISHED instead")
FINISHED = 4
status1 = TaskStatus.PENDING # Warns: "PENDING is deprecated, use OPEN instead"
assert status1 is TaskStatus.OPEN
```
### Typing Utilities
Disable class constructors to enforce factory pattern usage:
```python
from frequenz.core.typing import disable_init
@disable_init
class ApiClient:
@classmethod
def create(cls, api_key: str) -> "ApiClient":
# Factory method with validation
instance = cls.__new__(cls)
# Custom initialization logic here
return instance
# This will raise TypeError:
# client = ApiClient() # ❌ TypeError
# Use factory method instead:
client = ApiClient.create("my-api-key") # ✅ Works
```
### Strongly-Typed IDs
Create type-safe identifiers for different entities:
```python
from frequenz.core.id import BaseId
class UserId(BaseId, str_prefix="USR"):
pass
class OrderId(BaseId, str_prefix="ORD"):
pass
user_id = UserId(123)
order_id = OrderId(456)
print(f"User: {user_id}") # User: USR123
print(f"Order: {order_id}") # Order: ORD456
# Type safety prevents mixing different ID types
def process_user(user_id: UserId) -> None:
print(f"Processing user: {user_id}")
process_user(user_id) # ✅ Works
# process_user(order_id) # ❌ Type error
```
## Documentation
For information on how to use this library, please refer to the
[documentation](https://frequenz-floss.github.io/frequenz-core-python/).
## Contributing
If you want to know how to build this project and contribute to it, please
check out the [Contributing Guide](CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": null,
"name": "frequenz-core",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.11",
"maintainer_email": null,
"keywords": "asyncio, collections, core, datetime, frequenz, lib, library, math, python, stdlib, typing",
"author": null,
"author_email": "Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>",
"download_url": "https://files.pythonhosted.org/packages/7a/2f/13766fc5d5a76f40bfbfa7b0c21c3cae8f730a408f10b280310c04b37073/frequenz_core-1.1.0.tar.gz",
"platform": null,
"description": "# Frequenz Core Library\n\n[](https://github.com/frequenz-floss/frequenz-core-python/actions/workflows/ci.yaml)\n[](https://pypi.org/project/frequenz-core/)\n[](https://frequenz-floss.github.io/frequenz-core-python/)\n\n## Introduction\n\nCore utilities to complement Python's standard library. This library provides\nessential building blocks for Python applications, including mathematical\nutilities, datetime constants, typing helpers, strongly-typed identifiers, and\nmodule introspection tools.\n\nThe `frequenz-core` library is designed to be lightweight, type-safe, and\nfollow modern Python best practices. It fills common gaps in the standard\nlibrary with utilities that are frequently needed across different projects.\n\n## Supported Platforms\n\nThe following platforms are officially supported (tested):\n\n- **Python:** 3.11\n- **Operating System:** Ubuntu Linux 20.04\n- **Architectures:** amd64, arm64\n\n## Installation\n\nYou can install the library from PyPI using pip:\n\n```bash\npython -m pip install frequenz-core\n```\n\nOr add it to your project's dependencies in `pyproject.toml`:\n\n```toml\n[project]\ndependencies = [\n \"frequenz-core >= 1.0.2, < 2\",\n]\n```\n\n> [!NOTE]\n> We recommend pinning the dependency to the latest version for programs,\n> like `\"frequenz-core == 1.0.2\"`, and specifying a version range spanning\n> one major version for libraries, like `\"frequenz-core >= 1.0.2, < 2\"`.\n> We follow [semver](https://semver.org/).\n\n## Quick Start\n\nHere's a quick overview of the main functionality:\n\n```python\nfrom frequenz.core.math import is_close_to_zero, Interval\nfrom frequenz.core.datetime import UNIX_EPOCH\nfrom frequenz.core.module import get_public_module_name\n\n# Math utilities\nprint(is_close_to_zero(1e-10)) # True - check if float is close to zero\ninterval = Interval(1, 10)\nprint(5 in interval) # True - check if value is in range\n\n# Datetime utilities\nprint(UNIX_EPOCH) # 1970-01-01 00:00:00+00:00\n\n# Module utilities\npublic_name = get_public_module_name(\"my.package._private.module\")\nprint(public_name) # \"my.package\"\n```\n\n## Code Examples\n\n### Math Utilities\n\nThe math module provides utilities for floating-point comparisons and interval\nchecking:\n\n```python\nfrom frequenz.core.math import is_close_to_zero, Interval\n\n# Robust floating-point zero comparison\nassert is_close_to_zero(1e-10) # True\nassert not is_close_to_zero(0.1) # False\n\n# Interval checking with inclusive bounds\nnumbers = Interval(0, 100)\nassert 50 in numbers # True\nassert not (150 in numbers) # False - 150 is outside the interval\n\n# Unbounded intervals\npositive = Interval(0, None) # [0, \u221e]\nassert 1000 in positive # True\n```\n\n### `Enum` with deprecated members\n\nDefine enums with deprecated members that raise deprecation warnings when\naccessed:\n\n```python\nfrom frequenz.core.enum import Enum, DeprecatedMember\n\nclass TaskStatus(Enum):\n OPEN = 1\n IN_PROGRESS = 2\n PENDING = DeprecatedMember(1, \"PENDING is deprecated, use OPEN instead\")\n DONE = DeprecatedMember(3, \"DONE is deprecated, use FINISHED instead\")\n FINISHED = 4\n\nstatus1 = TaskStatus.PENDING # Warns: \"PENDING is deprecated, use OPEN instead\"\nassert status1 is TaskStatus.OPEN\n```\n\n### Typing Utilities\n\nDisable class constructors to enforce factory pattern usage:\n\n```python\nfrom frequenz.core.typing import disable_init\n\n@disable_init\nclass ApiClient:\n @classmethod\n def create(cls, api_key: str) -> \"ApiClient\":\n # Factory method with validation\n instance = cls.__new__(cls)\n # Custom initialization logic here\n return instance\n\n# This will raise TypeError:\n# client = ApiClient() # \u274c TypeError\n\n# Use factory method instead:\nclient = ApiClient.create(\"my-api-key\") # \u2705 Works\n```\n\n### Strongly-Typed IDs\n\nCreate type-safe identifiers for different entities:\n\n```python\nfrom frequenz.core.id import BaseId\n\nclass UserId(BaseId, str_prefix=\"USR\"):\n pass\n\nclass OrderId(BaseId, str_prefix=\"ORD\"):\n pass\n\nuser_id = UserId(123)\norder_id = OrderId(456)\n\nprint(f\"User: {user_id}\") # User: USR123\nprint(f\"Order: {order_id}\") # Order: ORD456\n\n# Type safety prevents mixing different ID types\ndef process_user(user_id: UserId) -> None:\n print(f\"Processing user: {user_id}\")\n\nprocess_user(user_id) # \u2705 Works\n# process_user(order_id) # \u274c Type error\n```\n\n## Documentation\n\nFor information on how to use this library, please refer to the\n[documentation](https://frequenz-floss.github.io/frequenz-core-python/).\n\n## Contributing\n\nIf you want to know how to build this project and contribute to it, please\ncheck out the [Contributing Guide](CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Core utilities to complement Python's standard library",
"version": "1.1.0",
"project_urls": {
"Changelog": "https://github.com/frequenz-floss/frequenz-core-python/releases",
"Documentation": "https://frequenz-floss.github.io/frequenz-core-python/",
"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"
},
"split_keywords": [
"asyncio",
" collections",
" core",
" datetime",
" frequenz",
" lib",
" library",
" math",
" python",
" stdlib",
" typing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "087843365c19087e76455f34a461667133813d4954badc0cf17ccb7f582a50db",
"md5": "22ad9fc7bfadcc03d99a7087a66f3f41",
"sha256": "cb438a2ba276193ba14a326cc21c357c89a35a05bf21f9d24950abc7d7e3be8b"
},
"downloads": -1,
"filename": "frequenz_core-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "22ad9fc7bfadcc03d99a7087a66f3f41",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.11",
"size": 16489,
"upload_time": "2025-08-26T12:04:20",
"upload_time_iso_8601": "2025-08-26T12:04:20.175172Z",
"url": "https://files.pythonhosted.org/packages/08/78/43365c19087e76455f34a461667133813d4954badc0cf17ccb7f582a50db/frequenz_core-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7a2f13766fc5d5a76f40bfbfa7b0c21c3cae8f730a408f10b280310c04b37073",
"md5": "d1d46ae0443759c854b2401d26dcf993",
"sha256": "98768702df55f32406bf405d6d00bed025e26f1d2681bee9597cb9d31cbe9c2d"
},
"downloads": -1,
"filename": "frequenz_core-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "d1d46ae0443759c854b2401d26dcf993",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.11",
"size": 18227,
"upload_time": "2025-08-26T12:04:21",
"upload_time_iso_8601": "2025-08-26T12:04:21.728725Z",
"url": "https://files.pythonhosted.org/packages/7a/2f/13766fc5d5a76f40bfbfa7b0c21c3cae8f730a408f10b280310c04b37073/frequenz_core-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 12:04:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "frequenz-floss",
"github_project": "frequenz-core-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "frequenz-core"
}
JSON
