Implement market metering client for ReceiveMarketLocationSamplesStream

- Add MarketMeteringApiClient with stream_samples() and stream() methods
- Define types: MarketLocationSample, MarketLocationSeries, MarketLocationRef, etc.
- Add CLI with 'stream' command and interactive REPL mode
- Restructure package to frequenz.client.marketmetering (matching dispatch pattern)

Signed-off-by: Mathias L. Baumann <[email protected]>

Author: Marenz

README.md

@@ -1,24 +1,123 @@
-# Frequenz Client Marketmetering Library
+# Frequenz Market Metering Client
 
 [![Build Status](https://github.com/frequenz-floss/frequenz-client-marketmetering-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-client-marketmetering-python/actions/workflows/ci.yaml)
 [![PyPI Package](https://img.shields.io/pypi/v/frequenz-client-marketmetering)](https://pypi.org/project/frequenz-client-marketmetering/)
 [![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-client-marketmetering-python/)
 
 ## Introduction
 
-Market Metering API client for Python
+A Python client for the Frequenz Market Metering API, providing access to
+historical and real-time metering samples from Market Locations across various
+energy markets (Germany, UK, US, Australia, etc.).
 
-TODO(cookiecutter): Improve the README file
+## Features
 
-## Supported Platforms
+- Stream metering samples from Market Locations
+- Support for multiple market identifier types (MaLo-ID, MPAN, ESI-ID, NMI)
+- Filtering by energy flow direction (import/export)
+- Multiple metric types (active energy, active power, reactive energy/power)
+- Optional resampling for time-series aggregation
+- CLI tool for quick access to metering data
+
+## Installation
+
+```bash
+pip install frequenz-client-marketmetering
+```
+
+For CLI support:
+
+```bash
+pip install "frequenz-client-marketmetering[cli]"
+```
+
+## Quick Start
+
+### Python API
+
+```python
+from datetime import datetime, timezone
+from frequenz.client.marketmetering import MarketMeteringApiClient
+from frequenz.client.marketmetering.types import (
+    EnergyFlowDirection,
+    MarketLocationId,
+    MarketLocationIdType,
+    MarketLocationRef,
+    MetricType,
+)
+
+# Create client
+client = MarketMeteringApiClient(
+    server_url="grpc://marketmetering.example.com",
+    auth_key="your-api-key",
+)
+
+# Define a Market Location (e.g., German MaLo)
+market_location = MarketLocationRef(
+    enterprise_id=42,
+    market_location_id=MarketLocationId(
+        value="DE01234567890",
+        type=MarketLocationIdType.MALO_ID,
+    ),
+)
+
+# Stream metering samples
+async for series in client.stream_samples(
+    market_locations=[market_location],
+    directions=[EnergyFlowDirection.IMPORT],
+    metric_types=[MetricType.ACTIVE_ENERGY],
+    start_time=datetime(2025, 1, 1, tzinfo=timezone.utc),
+):
+    for sample in series.samples:
+        print(f"{sample.sample_time}: {sample.value} {series.metric_unit.name}")
+```
+
+### CLI
 
-The following platforms are officially supported (tested):
+```bash
+# Set environment variables
+export MARKETMETERING_API_URL="grpc://marketmetering.example.com"
+export MARKETMETERING_API_AUTH_KEY="your-api-key"
 
-- **Python:** 3.11
-- **Operating System:** Ubuntu Linux 20.04
+# Stream samples from a German Market Location
+marketmetering-cli stream 42:DE01234567890:MALO_ID
+
+# Stream with specific options
+marketmetering-cli stream 42:DE01234567890:MALO_ID \
+    --direction IMPORT \
+    --metric ACTIVE_ENERGY \
+    --start-time "2025-01-01T00:00:00" \
+    --resolution MIN_15
+```
+
+## Market Location Types
+
+The client supports various market identifier types:
+
+| Type | Market | Example |
+|------|--------|---------|
+| `MALO_ID` | Germany | `DE01234567890` |
+| `MPAN` | United Kingdom | `18106612345678901234` |
+| `ESI_ID` | US (ERCOT) | `10443720000012345` |
+| `NMI` | Australia | `NEM1203456A` |
+
+## Supported Platforms
+
+- **Python:** 3.11+
+- **Operating System:** Ubuntu Linux 20.04+
 - **Architectures:** amd64, arm64
 
+## Documentation
+
+For detailed documentation, please visit:
+https://frequenz-floss.github.io/frequenz-client-marketmetering-python/
+
 ## Contributing
 
 If you want to know how to build this project and contribute to it, please
 check out the [Contributing Guide](CONTRIBUTING.md).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
+for details.

RELEASE_NOTES.md

@@ -1,17 +1,20 @@
-# Frequenz Client Marketmetering Library Release Notes
+# Frequenz Market Metering Client Release Notes
 
 ## Summary
 
-<!-- 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 -->
+Initial release of the Frequenz Market Metering API client for Python.
 
 ## 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 -->
+- `MarketMeteringApiClient`: Main client class for connecting to the Market Metering service
+- `stream_samples()`: Async iterator for streaming metering samples from Market Locations
+- `stream()`: Channel-based receiver for streaming with automatic reconnection
+- CLI tool (`marketmetering-cli`) for quick access to metering data
+- Support for multiple market identifier types:
+  - MaLo-ID (Germany)
+  - MPAN (United Kingdom)
+  - ESI-ID (US ERCOT)
+  - NMI (Australia)
+- Filtering by energy flow direction (IMPORT/EXPORT)
+- Multiple metric types (active energy, active power, reactive energy/power)
+- Optional resampling for time-series aggregation

pyproject.toml

@@ -3,9 +3,9 @@
 
 [build-system]
 requires = [
-  "setuptools == 75.8.0",
-  "setuptools_scm[toml] == 8.1.0",
-  "frequenz-repo-config[lib] == 0.13.1",
+  "setuptools == 80.9.0",
+  "setuptools_scm[toml] == 9.2.2",
+  "frequenz-repo-config[lib] == 0.13.8",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -14,8 +14,19 @@ name = "frequenz-client-marketmetering"
 description = "Market Metering API client for Python"
 readme = "README.md"
 license = { text = "MIT" }
-keywords = ["frequenz", "python", "lib", "library", "client-marketmetering", "marketmetering", "client", "api", "grpc"]
-# TODO(cookiecutter): Remove and add more classifiers if appropriate
+keywords = [
+  "frequenz",
+  "python",
+  "lib",
+  "library",
+  "marketmetering-client",
+  "marketmetering",
+  "client",
+  "api",
+  "grpc",
+  "energy",
+  "metering",
+]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
@@ -26,60 +37,69 @@ classifiers = [
   "Typing :: Typed",
 ]
 requires-python = ">= 3.11, < 4"
-# TODO(cookiecutter): Remove and add more dependencies if appropriate
 dependencies = [
-  "typing-extensions >= 4.14.1, < 5",
+  "typing-extensions >= 4.13.0, < 5",
+  "frequenz-api-market-metering >= 0.1.0, < 1",
+  "frequenz-client-base >= 0.11.0, < 0.12.0",
+  "grpcio >= 1.72.1, < 2",
 ]
 dynamic = ["version"]
 
+[project.scripts]
+marketmetering-cli = "frequenz.client.marketmetering.__main__:main"
+
 [[project.authors]]
 name = "Frequenz Energy-as-a-Service GmbH"
 email = "[email protected]"
 
-# TODO(cookiecutter): Remove and add more optional dependencies if appropriate
 [project.optional-dependencies]
+cli = [
+  "asyncclick == 8.3.0.7",
+  "prompt-toolkit == 3.0.52",
+]
+
 dev-flake8 = [
   "flake8 == 7.3.0",
   "flake8-docstrings == 1.7.0",
   "flake8-pyproject == 1.2.3",  # For reading the flake8 config from pyproject.toml
-  "pydoclint == 0.6.10",
+  "pydoclint == 0.7.6",
   "pydocstyle == 6.3.0",
 ]
-dev-formatting = ["black == 25.1.0", "isort == 6.0.0"]
+dev-formatting = ["black == 25.9.0", "isort == 6.0.1"]
 dev-mkdocs = [
-  "Markdown == 3.8.2",
-  "black == 25.1.0",
+  "black == 25.9.0",
+  "Markdown == 3.9",
   "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] == 1.0.0",
-  "mkdocstrings-python == 2.0.1",
-  "frequenz-repo-config[lib] == 0.13.1",
+  "frequenz-api-market-metering >= 0.1.0, < 1",
+  "mkdocs-macros-plugin == 1.4.1",
+  "mkdocs-material == 9.6.23",
+  "mkdocstrings[python] == 0.30.1",
+  "frequenz-repo-config[lib] == 0.13.8",
 ]
 dev-mypy = [
-  "mypy == 1.9.0",
-  "types-Markdown == 3.8.0.20250809",
+  "mypy == 1.18.2",
+  "types-Markdown == 3.9.0.20250906",
   # For checking the noxfile, docs/ script, and tests
-  "frequenz-client-marketmetering[dev-mkdocs,dev-noxfile,dev-pytest]",
-]
-dev-noxfile = [
-  "nox == 2025.5.1",
-  "frequenz-repo-config[lib] == 0.13.1",
+  "frequenz-client-marketmetering[cli,dev-mkdocs,dev-noxfile,dev-pytest]",
+  "grpc-stubs == 1.53.0.6",
+  "types-protobuf == 6.32.1.20250918",
 ]
+dev-noxfile = ["nox == 2025.10.16", "frequenz-repo-config[lib] == 0.13.8"]
 dev-pylint = [
-  # dev-pytest already defines a dependency to pylint because of the examples
+  "pylint == 3.3.9",
   # For checking the noxfile, docs/ script, and tests
-  "frequenz-client-marketmetering[dev-mkdocs,dev-noxfile,dev-pytest]",
+  "frequenz-client-marketmetering[cli,dev-mkdocs,dev-noxfile,dev-pytest]",
+  "frequenz-api-market-metering >= 0.1.0, < 1",
 ]
 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.1",
-  "pytest-mock == 3.14.0",
-  "pytest-asyncio == 1.1.0",
+  "pytest == 8.4.2",
+  "frequenz-repo-config[extra-lint-examples] == 0.13.8",
+  "pytest-mock == 3.15.1",
+  "pytest-asyncio == 1.2.0",
   "async-solipsism == 0.8",
+  "frequenz-client-marketmetering[cli]",
 ]
 dev = [
   "frequenz-client-marketmetering[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
@@ -118,7 +138,6 @@ check-yield-types = false
 arg-type-hints-in-docstring = false
 arg-type-hints-in-signature = true
 allow-init-docstring = true
-check-class-attributes = false
 
 [tool.pylint.similarities]
 ignore-comments = ['yes']
@@ -133,34 +152,33 @@ disable = [
   # disabled because it conflicts with isort
   "wrong-import-order",
   "ungrouped-imports",
-  # Checked by mypy (and pylint is very flaky checking these)
+  # 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 mypy
   "no-member",
-  "no-name-in-module",
   "possibly-used-before-assignment",
+  "no-name-in-module",
   # Checked by flake8
-  "f-string-without-interpolation",
+  "redefined-outer-name",
+  "unused-import",
   "line-too-long",
-  "missing-function-docstring",
   "redefined-outer-name",
   "unnecessary-lambda-assignment",
   "unused-import",
   "unused-variable",
 ]
 
 [tool.pytest.ini_options]
-addopts = "-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.
+  # We use a raw string (single quote) to avoid the need to escape special
+  # chars as this is a regex
   'ignore:Protobuf gencode version .*exactly one major version older.*:UserWarning',
 ]
+addopts = "-vv"
 testpaths = ["tests", "src"]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
@@ -175,11 +193,11 @@ namespace_packages = true
 # 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_marketmetering"]
+packages = ["frequenz.client.marketmetering"]
 strict = true
 
 [[tool.mypy.overrides]]
-module = ["mkdocs_macros.*", "sybil", "sybil.*"]
+module = ["mkdocs_macros.*"]
 ignore_missing_imports = true
 
 [tool.setuptools_scm]

src/frequenz/client/conftest.py

@@ -0,0 +1,4 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Pytest configuration for frequenz.client namespace."""