Metadata-Version: 2.1
Name: frequenz-reporting-python
Version: 0.2.0
Summary: A highlevel interface for the reporting API
Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
License: MIT
Project-URL: Documentation, https://frequenz-floss.github.io/frequenz-reporting-python/
Project-URL: Changelog, https://github.com/frequenz-floss/frequenz-reporting-python/releases
Project-URL: Issues, https://github.com/frequenz-floss/frequenz-reporting-python/issues
Project-URL: Repository, https://github.com/frequenz-floss/frequenz-reporting-python
Project-URL: Support, https://github.com/frequenz-floss/frequenz-reporting-python/discussions/categories/support
Keywords: frequenz,python,lib,library,reporting,highlevel,tooling,api
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
License-File: LICENSE
Requires-Dist: typing-extensions<5,>=4.6.1
Requires-Dist: frequenz-client-reporting<1,>=0.9.0
Requires-Dist: frequenz-client-common<0.3,>=0.2.0
Provides-Extra: dev-flake8
Requires-Dist: flake8==7.1.1; 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.5.9; extra == "dev-flake8"
Requires-Dist: pydocstyle==6.3.0; extra == "dev-flake8"
Provides-Extra: dev-formatting
Requires-Dist: black==24.10.0; extra == "dev-formatting"
Requires-Dist: isort==5.13.2; extra == "dev-formatting"
Provides-Extra: dev-mkdocs
Requires-Dist: Markdown==3.7; extra == "dev-mkdocs"
Requires-Dist: black==24.10.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.1; extra == "dev-mkdocs"
Requires-Dist: mkdocs-macros-plugin==1.3.7; extra == "dev-mkdocs"
Requires-Dist: mkdocs-material==9.5.47; extra == "dev-mkdocs"
Requires-Dist: mkdocstrings[python]==0.27.0; extra == "dev-mkdocs"
Requires-Dist: mkdocstrings-python==1.12.2; extra == "dev-mkdocs"
Requires-Dist: frequenz-repo-config[lib]==0.11.0; extra == "dev-mkdocs"
Provides-Extra: dev-mypy
Requires-Dist: mypy==1.13.0; extra == "dev-mypy"
Requires-Dist: types-Markdown==3.7.0.20240822; extra == "dev-mypy"
Requires-Dist: frequenz-reporting-python[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-mypy"
Provides-Extra: dev-noxfile
Requires-Dist: nox==2024.10.9; extra == "dev-noxfile"
Requires-Dist: frequenz-repo-config[lib]==0.11.0; extra == "dev-noxfile"
Provides-Extra: dev-pylint
Requires-Dist: frequenz-reporting-python[dev-mkdocs,dev-noxfile,dev-pytest]; extra == "dev-pylint"
Provides-Extra: dev-pytest
Requires-Dist: pytest==8.3.4; extra == "dev-pytest"
Requires-Dist: pylint==3.3.2; extra == "dev-pytest"
Requires-Dist: frequenz-repo-config[extra-lint-examples]==0.11.0; extra == "dev-pytest"
Requires-Dist: pytest-mock==3.14.0; extra == "dev-pytest"
Requires-Dist: pytest-asyncio==0.24.0; extra == "dev-pytest"
Requires-Dist: async-solipsism==0.7; extra == "dev-pytest"
Provides-Extra: dev
Requires-Dist: frequenz-reporting-python[dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]; extra == "dev"

# Reporting Highlevel Interface

[![Build Status](https://github.com/frequenz-floss/frequenz-reporting-python/actions/workflows/ci.yaml/badge.svg)](https://github.com/frequenz-floss/frequenz-reporting-python/actions/workflows/ci.yaml)
[![PyPI Package](https://img.shields.io/pypi/v/frequenz-reporting-python)](https://pypi.org/project/frequenz-reporting-python/)
[![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-reporting-python/)

## Introduction

A highlevel interface for the reporting API

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


### Installation

```bash
# Choose the version you want to install
VERSION=0.1.0
pip install frequenz-reporting-python==$VERSION
```


### Initialize the client

```python
from datetime import datetime

from frequenz.client.common.metric import Metric
from frequenz.client.reporting import ReportingApiClient
from frequenz.reporting._reporting import cumulative_energy

# Change server address if needed
SERVICE_ADDRESS = "reporting.api.frequenz.com:443"
API_KEY = open('api_key.txt').read().strip()
client = ReportingApiClient(service_address=SERVICE_ADDRESS, key=API_KEY)
```

### Calculate cumulative energy for a single microgrid and component:

If the component does not measure `Metric.AC_ACTIVE_ENERGY`, set `use_active_power=True`
to utilize `Metric.AC_ACTIVE_POWER` instead.

A resampling period can be set that alters how NaNs are handled, resulting in varying
results. NaN values are ignored in sums, which may lead to significant data loss
if many are present in the raw data. There is no universally correct method for
handling NaNs, as their causes can vary.

```python
energy_reading = await cumulative_energy(
			client=client,
                        microgrid_id=1,
                        component_id=100,
                        start_time=datetime.fromisoformat("2024-09-01T00:00:00"),
                        end_time=datetime.fromisoformat("2024-09-30T00:00:00"),
                        use_active_power=True,
                        resampling_period=timedelta(seconds=10),
    )

print(energy_reading)
```
