Metadata-Version: 2.4
Name: cofy-api
Version: 0.7.0
Summary: An open-source modular framework for ingesting, standardising, storing, and computing energy-related data.
Author: Jorg
Author-email: EnergyID <info@energieid.be>
License-Expression: MIT
Project-URL: Source, https://github.com/EnergieID/cofy-api
Project-URL: Changelog, https://github.com/EnergieID/cofy-api/releases
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi[standard]>=0.128.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: starlette>=0.41.0
Provides-Extra: timeseries
Requires-Dist: isodate>=0.7.2; extra == "timeseries"
Requires-Dist: narwhals>=2.15.0; extra == "timeseries"
Provides-Extra: tariff
Requires-Dist: cofy-api[timeseries]; extra == "tariff"
Requires-Dist: energy-cost==0.7.0; extra == "tariff"
Requires-Dist: entsoe-py>=0.7.10; extra == "tariff"
Requires-Dist: pandas>=3.0.0; extra == "tariff"
Provides-Extra: billing
Requires-Dist: cofy-api[timeseries]; extra == "billing"
Requires-Dist: energy-cost>=0.7.0; extra == "billing"
Requires-Dist: pandas>=3.0.0; extra == "billing"
Provides-Extra: production
Requires-Dist: cofy-api[timeseries]; extra == "production"
Requires-Dist: polars>=1.38.1; extra == "production"
Requires-Dist: requests>=2.32.0; extra == "production"
Provides-Extra: members
Requires-Dist: energy-cost==0.7.0; extra == "members"
Provides-Extra: directive
Requires-Dist: cofy-api[timeseries]; extra == "directive"
Requires-Dist: narwhals>=2.15.0; extra == "directive"
Provides-Extra: debug
Requires-Dist: yappi>=1.7.6; extra == "debug"
Provides-Extra: all
Requires-Dist: cofy-api[billing,debug,directive,members,production,tariff,timeseries]; extra == "all"

# Cofy API

Cofy API is an open-source modular framework for ingesting, standardising, storing, and computing energy-related data.

This package contains the runtime API and module system: the piece you need for route 1 in the
[root README](../../README.md), running a single energy community yourself. If you'd rather
start from a ready-made repo than from this package directly, see
[cofy-api-template](https://github.com/EnergieID/cofy-api-template).

## Install

```sh
pip install "cofy-api[all]"
```

Cofy is modular — install only what you need via [extras](https://packaging.python.org/en/latest/specifications/dependency-specifiers/#extras).
Example — install with only the tarrif and members modules:

```sh
pip install "cofy-api[tariff,members]"
```

## Quick start

Create an app.py file with a minimal Cofy API:

```python
from cofy.api import CofyAPI
from cofy.modules.tariff import TariffModule

app = CofyAPI()
app.register_module(TariffModule(api_key="YOUR_ENTSOE_KEY", name="entsoe"))
```

Run it:

```sh
fastapi dev app.py
```

The API is now available at `http://127.0.0.1:8000` with interactive docs at `/docs`.

## Authentication

Protect the API with bearer-token authentication:

```python
from cofy.api import CofyAPI, TokenAuth, TokenInfo

app = CofyAPI(auth=TokenAuth({"my-secret-token": TokenInfo(name="Admin")}))
```

Clients authenticate via header (`Authorization: Bearer my-secret-token`) or query parameter (`?token=my-secret-token`).


## Development

We use [astral](https://docs.astral.sh/) python tooling for our development environment.
We use [poethepoet](https://poethepoet.natn.io) to define some essential tasks.
The demo run task is also available as vscode execution task, making it easy to run and debug the demo application from within vscode.

### Install/update dependencies:
First install [uv](https://docs.astral.sh/uv/) if you don't have it yet.

Then install/update dependencies:
```sh
uv sync
```

Install [poethepoet](https://poethepoet.natn.io) and [pre-commit](https://pre-commit.com/)
```sh
uv tool install poethepoet
uv tool install pre-commit
```

Activate [pre-commit](https://pre-commit.com/) hooks that enforce code style on every commit:
```sh
pre-commit install
```

### Tests and linting

```sh
uv sync --group dev
poe test
poe lint
poe format
poe check
```
