oma-helen-cli 1.5.0
Oma Helen API library and CLI
License: MIT
Requires Python: >=3.9
Keywords: helen, electricity, api, cli, finland

# Oma Helen CLI

[![Tests](https://github.com/carohauta/oma-helen-cli/actions/workflows/tests.yml/badge.svg)](https://github.com/carohauta/oma-helen-cli/actions/workflows/tests.yml)

An interactive CLI to use [Oma Helen](https://www.helen.fi/kirjautuminen) from your command line. Offers an API client to get contract data and electricity measurements in JSON format.

### What is Oma Helen?

Oma Helen is the user portal for a Finnish electricity company, Helen Oy.

### How to install and use

Install from [pypi](https://pypi.org/project/oma-helen-cli/) and run:

```sh
pip install oma-helen-cli
oma-helen-cli
```

Then just enter you Oma Helen credentials and start entering commands.

Tip: in order to list all the commands within the CLI, enter `?`

### Available functions

| Function name                                    | What it does                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| get_api_access_token                             | Get the access token to the Oma Helen API. With the token, you can make manual curl requests to the API                                                                                                                                                                                                                                                                          |
| get_contract_base_price                          | Get the monthly base price of your current electricity contract                                                                                                                                                                                                                                                                                                                  |
| get_contract_data_json                           | Returns the whole contract data as JSON. Will return all active contracts you have with Helen                                                                                                                                                                                                                                                                                    |
| get_daily_measurements_json                      | Returns your daily energy consumption for the on-going month of the on-going year as JSON                                                                                                                                                                                                                                                                                        |
| get_market_prices_json                           | Returns the prices for the Market Price Electricity contract as JSON. The JSON includes the price for last month, the current month and next month if available                                                                                                                                                                                                                  |
| get_monthly_measurements_json                    | Returns your monthly energy consumption for the on-going year as JSON                                                                                                                                                                                                                                                                                                            |
| calculate_the_impact_of_usage_between_dates      | Calculates your impact of usage (in c/kwh) between given dates for the Helen Smart Electricity Guarantee                                                                                                                                                                                                                                                                         |
| calculate_spot_cost_between_dates                | Calculates the total costs (eur) between given dates of a spot price contract in an hourly precision                                                                                                                                                                                                                                                                             |
| get_exchange_margin_price_json                   | Get the margin price of the Exchange Electricity contract                                                                                                                                                                                                                                                                                                                        |
| get_contract_energy_unit_price                   | Get the energy unit price (c/kwh) from your contract data. Note that this only works for fixed price contracts. For spot electricity contract, this returns 0.0                                                                                                                                                                                                                  |
| get_contract_transfer_fee                        | Get the transfer fees (c/kwh) from your contract. Note that if Helen is not your transfer company, this returns 0.0                                                                                                                                                                                                                                                              |
| calculate_transfer_fees_between_dates            | Calculates total transfer fees (eur) based on your consumption between dates                                                                                                                                                                                                                                                                                                     |
| get_contract_transfer_base_price                 | Get the monthly transfer base price (eur) from your contract. Note that if Helen is not your transfer company, this returns 0.0                                                                                                                                                                                                                                                  |
| get_all_delivery_sites                           | Get all delivery sites across your active contracts                                                                                                                                                                                                                                                                                                                              |
| get_all_gsrn_ids                                 | Get all GSRN ids across your active contracts                                                                                                                                                                                                                                                                                                                                    |
| select_delivery_site                             | Select a delivery site by id for the CLI to use. Accepts both GSRN ids and delivery site ids as input. Useful if you have multiple contracts with Helen. Use `get_all_delivery_sites` or `get_all_gsrn_ids` to find out all your delivery sites / GSRN ids. After selecting a delivery site, all measurements and other requested data will be about the selected delivery site. |
| get_contract_type                                | Get the contract type (e.g., exchange electricity, market price) from your contract data                                                                                                                                                                                                                                                                                         |
| get_spot_prices_chart_data                       | Get spot prices from chart data API for a single day, including 15-minute intervals                                                                                                                                                                                                                                                                                              |
| get_hourly_measurements_with_spot_prices_json    | Get the measurements with spot prices for each hour between given dates                                                                                                                                                                                                                                                                                                          |
| get_quarterly_measurements_with_spot_prices_json | Get the measurements with spot prices for each quarter between given dates                                                                                                                                                                                                                                                                                                       |
| exit                                             | Exit the CLI application                                                                                                                                                                                                                                                                                                                                                         |

### Installing from sources and running the project for local development

First clone this repo.

Use virtual env to keep the project isolated. Developed using Python 3.9.9

1. In the project root folder run `python -m venv .venv`
2. Activate the venv with `source .venv/bin/activate`
3. Install requirements `pip install -r requirements.txt`
4. Launch the CLI as a python module `python -m helenservice.cli`
5. Enter your username and password as they are prompted
6. Type `?` into the CLI prompt to see all available functions

Deactivate venv when not needed: `deactivate`

### Testing

Install test dependencies
`pip install -e ".[test]"`

Run tests
`pytest tests/test_api_client.py`

Run with verbose output
`pytest tests/test_api_client.py -v`