Metadata-Version: 2.4
Name: frequenz-client-marketmetering
Version: 0.1.2
Summary: Market Metering API client for Python
Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
License-Expression: MIT
Project-URL: Documentation, https://frequenz-floss.github.io/frequenz-client-marketmetering-python/
Project-URL: Changelog, https://github.com/frequenz-floss/frequenz-client-marketmetering-python/releases
Project-URL: Issues, https://github.com/frequenz-floss/frequenz-client-marketmetering-python/issues
Project-URL: Repository, https://github.com/frequenz-floss/frequenz-client-marketmetering-python
Project-URL: Support, https://github.com/frequenz-floss/frequenz-client-marketmetering-python/discussions/categories/support
Keywords: frequenz,python,lib,library,marketmetering-client,marketmetering,client,api,grpc,energy,metering
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
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
Requires-Dist: frequenz-api-marketmetering<0.2.0,>=0.1.0
Requires-Dist: frequenz-client-base<0.12.0,>=0.11.0
Requires-Dist: grpcio<2,>=1.81.1
Provides-Extra: cli
Requires-Dist: asyncclick==8.3.0.7; extra == "cli"
Requires-Dist: prompt-toolkit==3.0.52; extra == "cli"
Provides-Extra: dev-flake8
Requires-Dist: flake8==7.3.0; extra == "dev-flake8"
Requires-Dist: flake8-datetimez==20.10.0; extra == "dev-flake8"
Requires-Dist: flake8-docstrings==1.7.0; extra == "dev-flake8"
Requires-Dist: flake8-pyproject==1.2.4; extra == "dev-flake8"
Requires-Dist: pydoclint==0.9.1; extra == "dev-flake8"
Requires-Dist: pydocstyle==6.3.0; extra == "dev-flake8"
Provides-Extra: dev-formatting
Requires-Dist: black==26.5.1; extra == "dev-formatting"
Requires-Dist: isort==8.0.1; extra == "dev-formatting"
Provides-Extra: dev-mkdocs
Requires-Dist: black==26.5.1; extra == "dev-mkdocs"
Requires-Dist: Markdown==3.10.2; extra == "dev-mkdocs"
Requires-Dist: mike==2.2.0; extra == "dev-mkdocs"
Requires-Dist: mkdocs-gen-files==0.6.1; extra == "dev-mkdocs"
Requires-Dist: mkdocs-literate-nav==0.6.3; extra == "dev-mkdocs"
Requires-Dist: frequenz-api-marketmetering==0.1.0; extra == "dev-mkdocs"
Requires-Dist: mkdocs-macros-plugin==1.5.0; extra == "dev-mkdocs"
Requires-Dist: mkdocs-material==9.7.6; extra == "dev-mkdocs"
Requires-Dist: mkdocstrings[python]==1.0.6; extra == "dev-mkdocs"
Requires-Dist: frequenz-repo-config[lib]==0.18.0; extra == "dev-mkdocs"
Provides-Extra: dev-mypy
Requires-Dist: mypy==2.1.0; extra == "dev-mypy"
Requires-Dist: types-Markdown==3.10.2.20260518; extra == "dev-mypy"
Requires-Dist: frequenz-client-marketmetering[cli,dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
Requires-Dist: grpc-stubs==1.53.0.6; extra == "dev-mypy"
Requires-Dist: types-protobuf==7.34.1.20260518; extra == "dev-mypy"
Provides-Extra: dev-noxfile
Requires-Dist: nox==2026.4.10; extra == "dev-noxfile"
Requires-Dist: frequenz-repo-config[lib]==0.18.0; extra == "dev-noxfile"
Provides-Extra: dev-pylint
Requires-Dist: pylint==4.0.6; extra == "dev-pylint"
Requires-Dist: frequenz-client-marketmetering[cli,dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
Requires-Dist: frequenz-api-marketmetering==0.1.0; extra == "dev-pylint"
Provides-Extra: dev-pytest
Requires-Dist: pytest==9.0.3; extra == "dev-pytest"
Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.18.0; extra == "dev-pytest"
Requires-Dist: pytest-mock==3.15.1; extra == "dev-pytest"
Requires-Dist: pytest-asyncio==1.4.0; extra == "dev-pytest"
Requires-Dist: async-solipsism==0.9; extra == "dev-pytest"
Requires-Dist: frequenz-client-marketmetering[cli]; extra == "dev-pytest"
Provides-Extra: dev
Requires-Dist: frequenz-client-marketmetering[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"
Dynamic: license-file

# 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

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.).

## Features

- 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,
    MarketArea,
    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(
    market_area=MarketArea.EU_DE,
    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

```bash
# Set environment variables
export MARKETMETERING_API_URL="grpc://marketmetering.example.com"
export MARKETMETERING_API_AUTH_KEY="your-api-key"

# Stream samples from a German Market Location
marketmetering-cli stream EU_DE:DE01234567890:MALO_ID

# Stream with specific options
marketmetering-cli stream EU_DE: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.
