frequenz-client-common 0.1.0__tar.gz

frequenz-client-common-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright © 2023 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-client-common-0.1.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-client-common-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.1
+Name: frequenz-client-common
+Version: 0.1.0
+Summary: Common code and utilities for Frequenz API clients
+Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
+License: MIT
+Project-URL: Documentation, https://frequenz-floss.github.io/frequenz-client-common-python/
+Project-URL: Changelog, https://github.com/frequenz-floss/frequenz-client-common-python/releases
+Project-URL: Issues, https://github.com/frequenz-floss/frequenz-client-common-python/issues
+Project-URL: Repository, https://github.com/frequenz-floss/frequenz-client-common-python
+Project-URL: Support, https://github.com/frequenz-floss/frequenz-client-common-python/discussions/categories/support
+Keywords: frequenz,python,lib,library,client-common
+Classifier: Development Status :: 3 - Alpha
+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
+Provides-Extra: dev-flake8
+Provides-Extra: dev-formatting
+Provides-Extra: dev-mkdocs
+Provides-Extra: dev-mypy
+Provides-Extra: dev-noxfile
+Provides-Extra: dev-pylint
+Provides-Extra: dev-pytest
+Provides-Extra: dev
+License-File: LICENSE
+
+# Frequenz Client Common Library
+
+[![Build Status](https://github.com/frequenz-floss/frequenz-client-common-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-client-common-python/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/frequenz-client-common)](https://pypi.org/project/frequenz-client-common/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-client-common-python/)
+
+## Introduction
+
+Common code and utilities for Frequenz API clients
+
+TODO(cookiecutter): Improve the README file
+
+## 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-client-common-0.1.0/README.md

@@ -0,0 +1,24 @@
+# Frequenz Client Common Library
+
+[![Build Status](https://github.com/frequenz-floss/frequenz-client-common-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-client-common-python/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/frequenz-client-common)](https://pypi.org/project/frequenz-client-common/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-client-common-python/)
+
+## Introduction
+
+Common code and utilities for Frequenz API clients
+
+TODO(cookiecutter): Improve the README file
+
+## 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-client-common-0.1.0/RELEASE_NOTES.md

@@ -0,0 +1,22 @@
+# Frequenz Client Common Library Release Notes
+
+## Summary
+
+This is the initial release of the Frequenz Client Common Library.
+It provides wrappers around the types from Frequenz's common API protobuf definitions.
+This version contains types to support pagination in gRPC requests
+and enum types for components and metrics to be used in a microgrid.
+
+<!-- Here goes a general summary of what this release is about -->
+
+## Upgrading
+
+<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+
+## New Features
+
+<!-- Here goes the main new features and examples or instructions on how to use them -->
+
+## Bug Fixes
+
+<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

frequenz-client-common-0.1.0/pyproject.toml

@@ -0,0 +1,164 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+[build-system]
+requires = [
+  "setuptools == 68.1.0",
+  "setuptools_scm[toml] == 7.1.0",
+  "frequenz-repo-config[lib] == 0.9.1",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "frequenz-client-common"
+description = "Common code and utilities for Frequenz API clients"
+readme = "README.md"
+license = { text = "MIT" }
+keywords = ["frequenz", "python", "lib", "library", "client-common"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "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.5.0, < 5",
+  "frequenz-api-common >= 0.5.4, < 6",
+]
+dynamic = ["version"]
+
+[[project.authors]]
+name = "Frequenz Energy-as-a-Service GmbH"
+email = "floss@frequenz.com"
+
+[project.optional-dependencies]
+dev-flake8 = [
+  "flake8 == 7.0.0",
+  "flake8-docstrings == 1.7.0",
+  "flake8-pyproject == 1.2.3",  # For reading the flake8 config from pyproject.toml
+  "pydoclint == 0.4.1",
+  "pydocstyle == 6.3.0",
+]
+dev-formatting = ["black == 24.2.0", "isort == 5.13.2"]
+dev-mkdocs = [
+  "black == 24.2.0",
+  "Markdown==3.5.2",
+  "mike == 2.0.0",
+  "mkdocs-gen-files == 0.5.0",
+  "mkdocs-literate-nav == 0.6.1",
+  "mkdocs-macros-plugin == 1.0.5",
+  "mkdocs-material == 9.5.12",
+  "mkdocstrings[python] == 0.24.1",
+  "frequenz-repo-config[lib] == 0.9.1",
+]
+dev-mypy = [
+  "mypy == 1.8.0",
+  "types-Markdown == 3.5.0.20240129",
+  # For checking the noxfile, docs/ script, and tests
+  "frequenz-client-common[dev-mkdocs,dev-noxfile,dev-pytest]",
+]
+dev-noxfile = [
+  "nox == 2023.4.22",
+  "frequenz-repo-config[lib] == 0.9.1",
+]
+dev-pylint = [
+  "pylint == 3.1.0",
+  # For checking the noxfile, docs/ script, and tests
+  "frequenz-client-common[dev-mkdocs,dev-noxfile,dev-pytest]",
+]
+dev-pytest = [
+  "pytest == 8.1.0",
+  "frequenz-repo-config[extra-lint-examples] == 0.9.1",
+  "pytest-mock == 3.12.0",
+  "pytest-asyncio == 0.23.5",
+  "async-solipsism == 0.5",
+]
+dev = [
+  "frequenz-client-common[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-client-common-python/"
+Changelog = "https://github.com/frequenz-floss/frequenz-client-common-python/releases"
+Issues = "https://github.com/frequenz-floss/frequenz-client-common-python/issues"
+Repository = "https://github.com/frequenz-floss/frequenz-client-common-python"
+Support = "https://github.com/frequenz-floss/frequenz-client-common-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
+  "redefined-outer-name",
+  "unused-import",
+  "line-too-long",
+  "unused-variable",
+  "unnecessary-lambda-assignment",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src"]
+asyncio_mode = "auto"
+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.client.common"]
+strict = true
+
+[[tool.mypy.overrides]]
+module = ["mkdocs_macros.*", "sybil", "sybil.*"]
+ignore_missing_imports = true
+
+[tool.setuptools_scm]
+version_scheme = "post-release"

frequenz-client-common-0.1.0/setup.cfg

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

frequenz-client-common-0.1.0/src/frequenz/client/common/__init__.py

@@ -0,0 +1,4 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Common code and utilities for Frequenz API clients."""

frequenz-client-common-0.1.0/src/frequenz/client/common/conftest.py

@@ -0,0 +1,13 @@
+# License: MIT
+# Copyright © 2023 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-client-common-0.1.0/src/frequenz/client/common/metric/__init__.py

@@ -0,0 +1,140 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Module to define the metrics used with the common client."""
+
+from enum import Enum
+from typing import Self
+
+# pylint: disable=no-name-in-module
+from frequenz.api.common.v1.metrics.metric_sample_pb2 import Metric as PBMetric
+
+# pylint: enable=no-name-in-module
+
+
+class Metric(Enum):
+    """List of supported metrics."""
+
+    # Default value
+    UNSPECIFIED = PBMetric.METRIC_UNSPECIFIED
+
+    # DC electricity metrics
+    DC_VOLTAGE = PBMetric.METRIC_DC_VOLTAGE
+    DC_CURRENT = PBMetric.METRIC_DC_CURRENT
+    DC_POWER = PBMetric.METRIC_DC_POWER
+
+    # General AC electricity metrics
+    AC_FREQUENCY = PBMetric.METRIC_AC_FREQUENCY
+    AC_VOLTAGE = PBMetric.METRIC_AC_VOLTAGE
+    AC_VOLTAGE_PHASE_1 = PBMetric.METRIC_AC_VOLTAGE_PHASE_1
+    AC_VOLTAGE_PHASE_2 = PBMetric.METRIC_AC_VOLTAGE_PHASE_2
+    AC_VOLTAGE_PHASE_3 = PBMetric.METRIC_AC_VOLTAGE_PHASE_3
+    AC_APPARENT_CURRENT = PBMetric.METRIC_AC_APPARENT_CURRENT
+    AC_APPARENT_CURRENT_PHASE_1 = PBMetric.METRIC_AC_APPARENT_CURRENT_PHASE_1
+    AC_APPARENT_CURRENT_PHASE_2 = PBMetric.METRIC_AC_APPARENT_CURRENT_PHASE_2
+    AC_APPARENT_CURRENT_PHASE_3 = PBMetric.METRIC_AC_APPARENT_CURRENT_PHASE_3
+
+    # AC power metrics
+    AC_APPARENT_POWER = PBMetric.METRIC_AC_APPARENT_POWER
+    AC_APPARENT_POWER_PHASE_1 = PBMetric.METRIC_AC_APPARENT_POWER_PHASE_1
+    AC_APPARENT_POWER_PHASE_2 = PBMetric.METRIC_AC_APPARENT_POWER_PHASE_2
+    AC_APPARENT_POWER_PHASE_3 = PBMetric.METRIC_AC_APPARENT_POWER_PHASE_3
+    AC_ACTIVE_POWER = PBMetric.METRIC_AC_ACTIVE_POWER
+    AC_ACTIVE_POWER_PHASE_1 = PBMetric.METRIC_AC_ACTIVE_POWER_PHASE_1
+    AC_ACTIVE_POWER_PHASE_2 = PBMetric.METRIC_AC_ACTIVE_POWER_PHASE_2
+    AC_ACTIVE_POWER_PHASE_3 = PBMetric.METRIC_AC_ACTIVE_POWER_PHASE_3
+    AC_REACTIVE_POWER = PBMetric.METRIC_AC_REACTIVE_POWER
+    AC_REACTIVE_POWER_PHASE_1 = PBMetric.METRIC_AC_REACTIVE_POWER_PHASE_1
+    AC_REACTIVE_POWER_PHASE_2 = PBMetric.METRIC_AC_REACTIVE_POWER_PHASE_2
+    AC_REACTIVE_POWER_PHASE_3 = PBMetric.METRIC_AC_REACTIVE_POWER_PHASE_3
+
+    # AC power factor
+    AC_POWER_FACTOR = PBMetric.METRIC_AC_POWER_FACTOR
+    AC_POWER_FACTOR_PHASE_1 = PBMetric.METRIC_AC_POWER_FACTOR_PHASE_1
+    AC_POWER_FACTOR_PHASE_2 = PBMetric.METRIC_AC_POWER_FACTOR_PHASE_2
+    AC_POWER_FACTOR_PHASE_3 = PBMetric.METRIC_AC_POWER_FACTOR_PHASE_3
+
+    # AC energy metrics
+    AC_APPARENT_ENERGY = PBMetric.METRIC_AC_APPARENT_ENERGY
+    AC_APPARENT_ENERGY_PHASE_1 = PBMetric.METRIC_AC_APPARENT_ENERGY_PHASE_1
+    AC_APPARENT_ENERGY_PHASE_2 = PBMetric.METRIC_AC_APPARENT_ENERGY_PHASE_2
+    AC_APPARENT_ENERGY_PHASE_3 = PBMetric.METRIC_AC_APPARENT_ENERGY_PHASE_3
+    AC_ACTIVE_ENERGY = PBMetric.METRIC_AC_ACTIVE_ENERGY
+    AC_ACTIVE_ENERGY_PHASE_1 = PBMetric.METRIC_AC_ACTIVE_ENERGY_PHASE_1
+    AC_ACTIVE_ENERGY_PHASE_2 = PBMetric.METRIC_AC_ACTIVE_ENERGY_PHASE_2
+    AC_ACTIVE_ENERGY_PHASE_3 = PBMetric.METRIC_AC_ACTIVE_ENERGY_PHASE_3
+    AC_ACTIVE_ENERGY_CONSUMED = PBMetric.METRIC_AC_ACTIVE_ENERGY_CONSUMED
+    AC_ACTIVE_ENERGY_CONSUMED_PHASE_1 = (
+        PBMetric.METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_1
+    )
+    AC_ACTIVE_ENERGY_CONSUMED_PHASE_2 = (
+        PBMetric.METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_2
+    )
+    AC_ACTIVE_ENERGY_CONSUMED_PHASE_3 = (
+        PBMetric.METRIC_AC_ACTIVE_ENERGY_CONSUMED_PHASE_3
+    )
+    AC_ACTIVE_ENERGY_DELIVERED = PBMetric.METRIC_AC_ACTIVE_ENERGY_DELIVERED
+    AC_ACTIVE_ENERGY_DELIVERED_PHASE_1 = (
+        PBMetric.METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_1
+    )
+    AC_ACTIVE_ENERGY_DELIVERED_PHASE_2 = (
+        PBMetric.METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_2
+    )
+    AC_ACTIVE_ENERGY_DELIVERED_PHASE_3 = (
+        PBMetric.METRIC_AC_ACTIVE_ENERGY_DELIVERED_PHASE_3
+    )
+    AC_REACTIVE_ENERGY = PBMetric.METRIC_AC_REACTIVE_ENERGY
+    AC_REACTIVE_ENERGY_PHASE_1 = PBMetric.METRIC_AC_REACTIVE_ENERGY_PHASE_1
+    AC_REACTIVE_ENERGY_PHASE_2 = PBMetric.METRIC_AC_REACTIVE_ENERGY_PHASE_2
+    AC_REACTIVE_ENERGY_PHASE_3 = PBMetric.METRIC_AC_REACTIVE_ENERGY_PHASE_3
+
+    # AC harmonics
+    AC_THD_CURRENT = PBMetric.METRIC_AC_THD_CURRENT
+    AC_THD_CURRENT_PHASE_1 = PBMetric.METRIC_AC_THD_CURRENT_PHASE_1
+    AC_THD_CURRENT_PHASE_2 = PBMetric.METRIC_AC_THD_CURRENT_PHASE_2
+    AC_THD_CURRENT_PHASE_3 = PBMetric.METRIC_AC_THD_CURRENT_PHASE_3
+
+    # General BMS metrics
+    BATTERY_CAPACITY = PBMetric.METRIC_BATTERY_CAPACITY
+    BATTERY_SOC_PCT = PBMetric.METRIC_BATTERY_SOC_PCT
+    BATTERY_TEMPERATURE = PBMetric.METRIC_BATTERY_TEMPERATURE
+
+    # General inverter metrics
+    INVERTER_TEMPERATURE = PBMetric.METRIC_INVERTER_TEMPERATURE
+    INVERTER_TEMPERATURE_CABINET = PBMetric.METRIC_INVERTER_TEMPERATURE_CABINET
+    INVERTER_TEMPERATURE_HEATSINK = PBMetric.METRIC_INVERTER_TEMPERATURE_HEATSINK
+    INVERTER_TEMPERATURE_TRANSFORMER = PBMetric.METRIC_INVERTER_TEMPERATURE_TRANSFORMER
+
+    # EV charging station metrics
+    EV_CHARGER_TEMPERATURE = PBMetric.METRIC_EV_CHARGER_TEMPERATURE
+
+    # General sensor metrics
+    SENSOR_WIND_SPEED = PBMetric.METRIC_SENSOR_WIND_SPEED
+    SENSOR_WIND_DIRECTION = PBMetric.METRIC_SENSOR_WIND_DIRECTION
+    SENSOR_TEMPERATURE = PBMetric.METRIC_SENSOR_TEMPERATURE
+    SENSOR_RELATIVE_HUMIDITY = PBMetric.METRIC_SENSOR_RELATIVE_HUMIDITY
+    SENSOR_DEW_POINT = PBMetric.METRIC_SENSOR_DEW_POINT
+    SENSOR_AIR_PRESSURE = PBMetric.METRIC_SENSOR_AIR_PRESSURE
+    SENSOR_IRRADIANCE = PBMetric.METRIC_SENSOR_IRRADIANCE
+
+    @classmethod
+    def from_proto(cls, metric: PBMetric.ValueType) -> Self:
+        """Convert a protobuf Metric value to Metric enum.
+
+        Args:
+            metric: Metric to convert.
+        Returns:
+            Enum value corresponding to the protobuf message.
+        """
+        if not any(m.value == metric for m in cls):
+            return cls(Metric.UNSPECIFIED)
+
+        return cls(metric)
+
+    def to_proto(self) -> PBMetric.ValueType:
+        """Convert a Metric object to protobuf Metric.
+
+        Returns:
+            Protobuf message corresponding to the Metric object.
+        """
+        return self.value

frequenz-client-common-0.1.0/src/frequenz/client/common/microgrid/__init__.py

@@ -0,0 +1,4 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Frequenz microgrid definition."""

frequenz-client-common-0.1.0/src/frequenz/client/common/microgrid/components/__init__.py

@@ -0,0 +1,67 @@
+# License: MIT
+# Copyright © 2022 Frequenz Energy-as-a-Service GmbH
+
+"""Defines the components that can be used in a microgrid."""
+from __future__ import annotations
+
+from enum import Enum
+
+# pylint: disable=no-name-in-module
+from frequenz.api.common.v1.microgrid.components.components_pb2 import (
+    ComponentCategory as PBComponentCategory,
+)
+
+# pylint: enable=no-name-in-module
+
+
+class ComponentCategory(Enum):
+    """Possible types of microgrid component."""
+
+    UNSPECIFIED = PBComponentCategory.COMPONENT_CATEGORY_UNSPECIFIED
+    """An unknown component category.
+
+    Useful for error handling, and marking unknown components in
+    a list of components with otherwise known categories.
+    """
+
+    GRID = PBComponentCategory.COMPONENT_CATEGORY_GRID
+    """The point where the local microgrid is connected to the grid."""
+
+    METER = PBComponentCategory.COMPONENT_CATEGORY_METER
+    """A meter, for measuring electrical metrics, e.g., current, voltage, etc."""
+
+    INVERTER = PBComponentCategory.COMPONENT_CATEGORY_INVERTER
+    """An electricity generator, with batteries or solar energy."""
+
+    BATTERY = PBComponentCategory.COMPONENT_CATEGORY_BATTERY
+    """A storage system for electrical energy, used by inverters."""
+
+    EV_CHARGER = PBComponentCategory.COMPONENT_CATEGORY_EV_CHARGER
+    """A station for charging electrical vehicles."""
+
+    CHP = PBComponentCategory.COMPONENT_CATEGORY_CHP
+    """A heat and power combustion plant (CHP stands for combined heat and power)."""
+
+    @classmethod
+    def from_proto(
+        cls, component_category: PBComponentCategory.ValueType
+    ) -> ComponentCategory:
+        """Convert a protobuf ComponentCategory message to ComponentCategory enum.
+
+        Args:
+            component_category: protobuf enum to convert
+
+        Returns:
+            Enum value corresponding to the protobuf message.
+        """
+        if not any(t.value == component_category for t in ComponentCategory):
+            return ComponentCategory.UNSPECIFIED
+        return cls(component_category)
+
+    def to_proto(self) -> PBComponentCategory.ValueType:
+        """Convert a ComponentCategory enum to protobuf ComponentCategory message.
+
+        Returns:
+            Enum value corresponding to the protobuf message.
+        """
+        return self.value

frequenz-client-common-0.1.0/src/frequenz/client/common/pagination/__init__.py

@@ -0,0 +1,87 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Module to define the pagination used with the common client."""
+
+from __future__ import annotations  # required for constructor type hinting
+
+from dataclasses import dataclass
+from typing import Self
+
+# pylint: disable=no-name-in-module
+from frequenz.api.common.v1.pagination.pagination_info_pb2 import PaginationInfo
+from frequenz.api.common.v1.pagination.pagination_params_pb2 import PaginationParams
+
+# pylint: enable=no-name-in-module
+
+
+@dataclass(frozen=True, kw_only=True)
+class Params:
+    """Parameters for paginating list requests."""
+
+    page_size: int | None = None
+    """The maximum number of results to be returned per request."""
+
+    page_token: str | None = None
+    """The token identifying a specific page of the list results."""
+
+    @classmethod
+    def from_proto(cls, pagination_params: PaginationParams) -> Self:
+        """Convert a protobuf Params to PaginationParams object.
+
+        Args:
+            pagination_params: Params to convert.
+        Returns:
+            Params object corresponding to the protobuf message.
+        """
+        return cls(
+            page_size=pagination_params.page_size,
+            page_token=pagination_params.page_token,
+        )
+
+    def to_proto(self) -> PaginationParams:
+        """Convert a Params object to protobuf PaginationParams.
+
+        Returns:
+            Protobuf message corresponding to the Params object.
+        """
+        return PaginationParams(
+            page_size=self.page_size,
+            page_token=self.page_token,
+        )
+
+
+@dataclass(frozen=True, kw_only=True)
+class Info:
+    """Information about the pagination of a list request."""
+
+    total_items: int
+    """The total number of items that match the request."""
+
+    next_page_token: str | None = None
+    """The token identifying the next page of results."""
+
+    @classmethod
+    def from_proto(cls, pagination_info: PaginationInfo) -> Self:
+        """Convert a protobuf PBPaginationInfo to Info object.
+
+        Args:
+            pagination_info: Info to convert.
+        Returns:
+            Info object corresponding to the protobuf message.
+        """
+        return cls(
+            total_items=pagination_info.total_items,
+            next_page_token=pagination_info.next_page_token,
+        )
+
+    def to_proto(self) -> PaginationInfo:
+        """Convert a Info object to protobuf PBPaginationInfo.
+
+        Returns:
+            Protobuf message corresponding to the Info object.
+        """
+        return PaginationInfo(
+            total_items=self.total_items,
+            next_page_token=self.next_page_token,
+        )

frequenz-client-common-0.1.0/src/frequenz_client_common.egg-info/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.1
+Name: frequenz-client-common
+Version: 0.1.0
+Summary: Common code and utilities for Frequenz API clients
+Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
+License: MIT
+Project-URL: Documentation, https://frequenz-floss.github.io/frequenz-client-common-python/
+Project-URL: Changelog, https://github.com/frequenz-floss/frequenz-client-common-python/releases
+Project-URL: Issues, https://github.com/frequenz-floss/frequenz-client-common-python/issues
+Project-URL: Repository, https://github.com/frequenz-floss/frequenz-client-common-python
+Project-URL: Support, https://github.com/frequenz-floss/frequenz-client-common-python/discussions/categories/support
+Keywords: frequenz,python,lib,library,client-common
+Classifier: Development Status :: 3 - Alpha
+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
+Provides-Extra: dev-flake8
+Provides-Extra: dev-formatting
+Provides-Extra: dev-mkdocs
+Provides-Extra: dev-mypy
+Provides-Extra: dev-noxfile
+Provides-Extra: dev-pylint
+Provides-Extra: dev-pytest
+Provides-Extra: dev
+License-File: LICENSE
+
+# Frequenz Client Common Library
+
+[![Build Status](https://github.com/frequenz-floss/frequenz-client-common-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-client-common-python/actions/workflows/ci.yaml)
+[![PyPI Package](https://img.shields.io/pypi/v/frequenz-client-common)](https://pypi.org/project/frequenz-client-common/)
+[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-client-common-python/)
+
+## Introduction
+
+Common code and utilities for Frequenz API clients
+
+TODO(cookiecutter): Improve the README file
+
+## 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-client-common-0.1.0/src/frequenz_client_common.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+MANIFEST.in
+README.md
+RELEASE_NOTES.md
+pyproject.toml
+src/frequenz/client/common/__init__.py
+src/frequenz/client/common/conftest.py
+src/frequenz/client/common/py.typed
+src/frequenz/client/common/metric/__init__.py
+src/frequenz/client/common/microgrid/__init__.py
+src/frequenz/client/common/microgrid/components/__init__.py
+src/frequenz/client/common/pagination/__init__.py
+src/frequenz_client_common.egg-info/PKG-INFO
+src/frequenz_client_common.egg-info/SOURCES.txt
+src/frequenz_client_common.egg-info/dependency_links.txt
+src/frequenz_client_common.egg-info/requires.txt
+src/frequenz_client_common.egg-info/top_level.txt

frequenz-client-common-0.1.0/src/frequenz_client_common.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

frequenz-client-common-0.1.0/src/frequenz_client_common.egg-info/requires.txt

@@ -0,0 +1,47 @@
+typing-extensions<5,>=4.5.0
+frequenz-api-common<6,>=0.5.4
+
+[dev]
+frequenz-client-common[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]
+
+[dev-flake8]
+flake8==7.0.0
+flake8-docstrings==1.7.0
+flake8-pyproject==1.2.3
+pydoclint==0.4.1
+pydocstyle==6.3.0
+
+[dev-formatting]
+black==24.2.0
+isort==5.13.2
+
+[dev-mkdocs]
+black==24.2.0
+Markdown==3.5.2
+mike==2.0.0
+mkdocs-gen-files==0.5.0
+mkdocs-literate-nav==0.6.1
+mkdocs-macros-plugin==1.0.5
+mkdocs-material==9.5.12
+mkdocstrings[python]==0.24.1
+frequenz-repo-config[lib]==0.9.1
+
+[dev-mypy]
+mypy==1.8.0
+types-Markdown==3.5.0.20240129
+frequenz-client-common[dev-mkdocs,dev-noxfile,dev-pytest]
+
+[dev-noxfile]
+nox==2023.4.22
+frequenz-repo-config[lib]==0.9.1
+
+[dev-pylint]
+pylint==3.1.0
+frequenz-client-common[dev-mkdocs,dev-noxfile,dev-pytest]
+
+[dev-pytest]
+pytest==8.1.0
+frequenz-repo-config[extra-lint-examples]==0.9.1
+pytest-mock==3.12.0
+pytest-asyncio==0.23.5
+async-solipsism==0.5

frequenz-client-common-0.1.0/src/frequenz_client_common.egg-info/top_level.txt

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