Metadata-Version: 2.4
Name: dtvr
Version: 1.0.0
Summary: Python client for Dataverse
Author: Terraverse IT
Author-email: it@terraverse.info
Requires-Python: >=3.14,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: pandas (>=3.0.2,<4.0.0)
Requires-Dist: requests (>=2.33.1,<3.0.0)
Description-Content-Type: text/markdown

# Dataverse Python Client

Python client for Dataverse platform.

## Pre-requisites

1. Python version 3.14+
2. Environment variable `DATAVERSE_BASE_URL`
3. Environment variable `DATAVERSE_AUTH_TOKEN`
4. or both can be passed explicitly to `create_client` function as arguments.

You can generate an authentication token in the Terraverse SmartCube portal.
Intial values for both `DATAVERSE_BASE_URL` and `DATAVERSE_AUTH_TOKEN` will be issued once your SmartCube account
will become active and if your subscription plan includes Dataverse.

## Quickstart

```python
from dtvr.client import create_client

client = create_client()
with client.last_exchange_rates() as resp:
    reader = resp.as_csv_rows()
    for row in reader:
        print(row)  # use the data here

```

```python
from dtvr.client import create_client, CEPS_AREA_DOMAIN
from dtvr.timeutil import today_start_end

client = create_client()
start, end = today_start_end()
with client.procured_balancing_capacity_daily(CEPS_AREA_DOMAIN, start, end) as resp:
    df = resp.as_pandas()
    df.info(memory_usage=True)
    # use the dataframe here
```

#### DateLike arguments
Several methods of the client accepts arguments representing start and end of some date range for which you need
to download the data.
To pass something as date-like argument you can either:
* use [datetime](https://docs.python.org/3/library/datetime.html#datetime-objects)
* use [date](https://docs.python.org/3/library/datetime.html#date-objects)
* use string with the format `yyyy-MM-dd`, `yyyy-MM-dd HH:mm` or `yyyy-MM-dd HH:mm:ss`

## Features

* Easy to use client library that will help you to consume Datavere endpoints quickly.
* Response containing data can be converted to either:
  * iterator representing CSV rows (list of string and numeric values)
  * pandas [DataFrame](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.html)
* Several convenience functions for manipulating date &amp; time in module `dtvr.timeutil`.

## Available Dataverse Endpoints

| method                                  | short description                                                                                                    |
|-----------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| last_exchange_rates                     | Returns the last known exchange rates. Data source is the Czech National Bank (CNB); rates are expressed in CZK.     |
| balancing_energy_bid                    | Returns ENTSOE balancing energy bid data for the specified connecting domain and time interval.                       |
| balancing_energy_bid_raw                | Returns raw ENTSOE balancing energy bid data for the specified connecting domain and time interval.                   |
| procured_balancing_capacity_daily       | Returns ENTSOE daily-auction procured balancing capacity data for the specified area domain and time interval.        |
| procured_balancing_capacity_yearly      | Returns ENTSOE yearly-auction procured balancing capacity data for the specified area domain and year.                |
| exchanged_volume                        | Returns TransnetBW cross-border exchanged balancing volumes for the specified day.                                   |
| cross_border_marginal_price             | Returns TransnetBW cross-border marginal prices for the specified day.                                               |
| ceps_current_system_imbalance_actual    | Returns the last ~15 minutes of system imbalance (ACE) data.                                                         |
| ceps_current_system_imbalance_daily     | Returns system imbalance (ACE) data for the specified day.                                                           |
| ceps_svr_activations_actual             | Returns the last ~15 minutes of SVR (balancing services) activation data.                                            |
| ceps_svr_activations_daily              | Returns SVR (balancing services) activation data for the specified day.                                              |
| ceps_svr_export_import_actual           | Returns the last ~15 minutes of SVR cross-border balancing energy exchange data.                                     |
| ceps_svr_export_import_daily            | Returns SVR cross-border balancing energy exchange data for the specified day.                                       |
| ceps_svr_maximum_dt_price               | Returns SVR daily price caps for ancillary service activations on the specified day.                                 |
| ceps_cross_border_power_flows_actual    | Returns the last ~15 minutes of real-time cross-border power flows data.                                             |
| ceps_cross_border_power_flows_daily     | Returns real-time cross-border power flows data for the specified day.                                               |
| ceps_emergency_exchange                 | Returns emergency exchange data for the specified day.                                                               |
| ceps_generation                         | Returns actual electricity generation data for the specified day, broken down by source type.                        |
| ceps_generation_plan                    | Returns the generation plan for the specified day.                                                                   |
| ceps_generation_renewable_source_actual | Returns the last ~15 minutes of real-time renewable energy generation data.                                          |
| ceps_generation_renewable_source_daily  | Returns real-time renewable energy generation data for the specified day.                                            |
| ceps_imbalance_price_prediction         | Returns the hourly imbalance price prediction for the specified day.                                                 |
| ceps_power_balance                      | Returns the power balance report for the specified year.                                                             |
| procured_balancing_capacity_daily_raw   | Returns raw ENTSOE daily-auction procured balancing capacity data for the specified area domain and time interval.   |
| procured_balancing_capacity_yearly_raw  | Returns raw ENTSOE yearly-auction procured balancing capacity data for the specified area domain and time interval.  |
| evaluation_party                        | Returns MMS party (subject) hourly evaluation data for the specified business date.                                  |
| evaluation_party_contract               | Returns MMS party contract hourly evaluation data for the specified business date.                                   |
| evaluation_party_additional_costs       | Returns MMS party additional costs hourly evaluation data for the specified business date.                           |
| evaluation_monthly_party                | Returns MMS monthly party (subject) evaluation data for the specified business month.                                |
| evaluation_monthly_contract             | Returns MMS monthly contract evaluation data for the specified business month.                                       |
| evaluation_asset_hourly                 | Returns MMS asset hourly evaluation data for the specified business date.                                            |
| evaluation_asset_quarter_hourly         | Returns MMS asset quarter-hour (QH) evaluation data for the specified business date.                                 |
| evaluation_marginal_price               | Returns MMS marginal price evaluation data for the specified business date.                                          |
| evaluation_reg_energy_unit              | Returns MMS regulating energy unit QH evaluation data for the specified business date.                               |
| evaluation_reg_energy_unit_ans          | Returns MMS regulating energy unit per ancillary service (ANS) QH evaluation data for the specified business date.  |
| evaluation_reg_energy_contract          | Returns MMS regulating energy contract QH evaluation data for the specified business date.                           |
| evaluation_reg_energy_hourly_contract   | Returns MMS regulating energy hour-contract evaluation data for the specified business date.                         |
| evaluation_reg_energy_hourly_party      | Returns MMS regulating energy hour-party evaluation data for the specified business date.                            |
| evaluation_reg_energy_minute            | Returns MMS regulating energy minute evaluation data for the specified business date.                                |

