Metadata-Version: 2.1
Name: indasuite-api-client
Version: 1
Summary: A client library for accessing Indasuite API
Author: Antoine Etchecopar
Author-email: antoine.etchecopar@cva-engineering.com
Requires-Python: >=3.9,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: attrs (>=21.3.0)
Requires-Dist: deprecated (>=1.2.14,<2.0.0)
Requires-Dist: httpx (>=0.20.0,<0.28.0)
Requires-Dist: pandas (>=2.2.2,<3.0.0)
Requires-Dist: python-dateutil (>=2.8.0,<3.0.0)
Description-Content-Type: text/markdown

# Indasuite-api-client

A client library for accessing Indasuite API.

## Getting started

First, create a client to communicate with API :

```python
from indasuite_api_client import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://api.example.com",
    access_token="mySuperSecretAccessToken",
)
```

Now use methods from ressources module :

```python
import pandas as pd
from indasuite_api_client import ModelX
from indasuite_api_client.ressources import get_X, add_new_X

with client as client:
    my_X_df: pd.DataFrame = get_X(client=client, x_id = x_id)

    new_X : ModelX = Model(attribute1= "attr1", ...)
    # or new_X : dict = {attribute1: "attr1", ...}
    add_new_X(client, new_X)
```

The models used in the methods are available in the base module. In this example : *from indasuite_api_client import ModelX*.


## Refreshing token

If you're using a device access token, you will have to refresh it everytime you need to use it.
This SDK provides a method to refresh it.

```python
from indasuite_api_client import refresh_access_token

access_token, refresh_token = refresh_access_token(
    device_auth_base_url="https://myFavouriteCompany.device-auth.SomeExtension.com", 
    api_key = "superSecretTokenLikeBearer"
    client_id="deviceX", 
    refresh_token="myOldRefreshToken"
)
```

> ## ⚠️ CAUTION ⚠️
> **YOU NEED TO REGISTER THE NEW REFRESH TOKEN IN YOUR PREFERRED SECRETS MANAGER**. As a reminder, each "refresh token" can only be used once. If you re-use a refresh token, the associated device will be blocked and you will have to repeat the procedure to register a new device with the help of the administrator.


# Available methods

The API provides 2 main types of resources:

+ Query : Databases list and metric values (instant, latest and range).
+ Metrics : Getting, adding, renaming, updating and deleting metrics.

Each following method is detailed in next sections.

+ Query
  + **get_databases** : Retrieve databases list.
  + **get_values_at** :  Retrieve metric values from one or multiple time series at a specific point in time.
  + **get_latest_value** : Retrieve latest metric value from one or multiple time series.
  + **get_range_values** : Retrieve metric values in given range.


+ Metrics
  + **get_metrics** : Get metric list.
  + **get_metric_by_id** : Get a single metric by its id
  + **add_new_metric** : Add new metric.
  + **update_metric** : Update metric information.
  + **update_metric_az_sr** : Update access zones or storage rule of a metric.
  + **rename_metric** : Rename metric.
  + **delete_metric** : Delete metric.



## Query

### get_databases

**Aim** : Retrieve databases list.

```python
from indasuite_api_client.ressources import get_databases

with client as client:
    databases_df = get_databases(client)
```

+ Parameters :
  + **client** (*AuthenticatedClient*) : HTTP client.
+ This methods returns database list as pandas DataFrame.

### get_values_at

**Aim** : Retrieve metric values from one or multiple time series at a specific point in time as pandas DataFrame.

```python
from indasuite_api_client import AuthenticatedClient, Instant
from indasuite_api_client.ressources import get_values_at

with client as client:
    datasource = "test"
    instant_data = {
        "moment": "2024-03-11T11:00:00+01:00",
        "metrics": [
            {"name": "maquette_prod_totale"},
            {"name": "maquette_prod_solaire"},
        ],
        "queryDirection": "Before_moment",
        "timezone": "Europe/Paris",
    }
    instant = Instant.from_dict(instant_data)
    metrics_instant_df = get_values_at(client, "test", instant)
```

+ Parameters :
  + **client** (*AuthenticatedClient*) : HTTP client.
  + **datasource** (*str*) : the datasource name.
  + **instant** (*Instant* or *dict*) : Structure that contains information of
    + metrics to retrieve values from.
    + specific point/moment.
    + query direction.

+ This methods returns a pandas DataFrame containing found value for each metric.

### get_latest_value

**Aim** : Retrieve latest metric value from one or multiple time series as pandas DataFrame.

```python
from indasuite_api_client import AuthenticatedClient, Latest
from indasuite_api_client.ressources import get_latest_value

with client as client:
    datasource = "test"
    latest_data = {
        "metrics": [
            {"name": "maquette_prod_totale"},
            {"name": "maquette_prod_solaire"},
        ],
        "timezone": "Europe/Paris",
        "returnUnit": True,
    }
    latest = Latest.from_dict(latest_data)
    metrics_latest_df = get_latest_value(client, "test", latest)
```

+ Parameters :
  + **client** (*AuthenticatedClient*) : HTTP client.
  + **datasource** (*str*) : the datasource name.
  + **latest** (*Latest* or *dict*) : Structure that contains information of
    + metrics to retrieve values from.
    + timezone.
    + whether you want the unit or not.

+ This methods returns a pandas DataFrame containing found value for each metric.

### get_range_values

**Aim** : Retrieve metric values in given range as pandas DataFrame.

```python
from indasuite_api_client import AuthenticatedClient, Range
from indasuite_api_client.ressources import get_range_values

with client as client:
    datasource = "test"
    range_data = {
        "start": "1924-03-11T10:26:00+01:00",
        "end": "2224-03-11T11:26:00+01:00",
        "metric": {"name": "maquette_prod_totale"},
        "timezone": "Europe/Paris",
        "limit": 50000,
        "showAnnotation": True,
        "aggregation": {
            "functions": [
                {"function": "Avg", "alias": "avg"},
                {"function": "Sum", "alias": "sum"},
            ]
        },
    }

    
    # OR
    # 
    # range_data = {
    #     "start": "1924-03-11T10:26:00+01:00",
    #     "end": "2224-03-11T11:26:00+01:00",
    #     "metric": {"name": "maquette_prod_totale"},
    #     "timezone": "Europe/Paris",
    #     "limit": 20,
    #     "showAnnotation": True,
    #     "aggregation": "none",
    # }

    range = Range.from_dict(range_data)
    metrics_range_df = get_range_values(client, "test", range)
```

+ Parameters :
  + **client** (*AuthenticatedClient*) : HTTP client.
  + **datasource** (*str*) : the datasource name.
  + **range** (*Range* or *dict*) : Structure that contains information of
    + range start and range end,
    + metric to retrieve values from,
    + values number,
    + whether you want the annotations or not.
    + aggregations applied. If you want raw values, specify it by *"none"* string as value.

+ This methods returns a pandas DataFrame containing raw or calculated/aggregated values.


## Metrics

### get_metrics

**Aim** : Get metric list.

```python
from indasuite_api_client.ressources import get_databases

with client as client:
    databases_df = get_metrics(client, datasource="test")
```

+ Parameters :
  + **client** (*AuthenticatedClient*) : HTTP client.
  + **datasource** (*str*) : the datasource name.
+ This methods returns metrics list as pandas DataFrame.

### get_metric_by_id

**Aim** : Retrieve a single metric data by its id.

```python
from indasuite_api_client import AuthenticatedClient
from indasuite_api_client.ressources import get_metric_by_id

with client as client:
    one_metric = get_metric_by_id(client, "test@maquette_prod_totale")
```

+ Parameters :
  + **client** (*AuthenticatedClient*) : HTTP client.
  + **metric_id** (*str*) : the metric id.

+ This methods returns a pandas DataFrame containing a single metric data.

### add_new_metric

**Aim** : Retrieve a single metric data by its id.

```python
from indasuite_api_client import AuthenticatedClient, MetricUpset
from indasuite_api_client.ressources import add_new_metric

with client as client:
    new_metric_data = {
        "storageRuleId": "5a663587-475a-402b-b204-d7e41ce1fed8",
        "accessZones": [
            "f03b8481-1dba-48d7-bbc1-187d7fb10104",
            "09c21936-2709-4ce2-adf9-79ad5f056656"
        ],
        "name": "cip_60",
        "datasource": "main",
        "description": "short description",
        "unit": "m2",
        "source": "Telex",
        "type": "Raw"
    }
    new_metric = MetricUpset.from_dict(new_metric_data)

    add_new_metric(client, new_metric)
```

+ Parameters :
  + **client** (*AuthenticatedClient*) : HTTP client.
  + **new_metric** (*MetricUpset* or *dict*) : Structure that contains all information of a metric.

### update_metric 

**Aim** : Update metric information.

```python
from indasuite_api_client import AuthenticatedClient, MetricUpset
from indasuite_api_client.ressources import update_metric

with client as client:
    metric_id = "main@cip_60"

    updated_metric_data = {
        "storageRuleId": "7520dff8-8697-49ae-9d7e-f2f3477252ac",
        "accessZones": [
            "83a36c56-ac0d-4198-91aa-f03f6c8283d5",
            "c7c5be8b-db58-4fce-882f-46e3a2d4347a"
        ],
        "name": "cip_60",
        "datasource": "main",
        "description": "short description",
        "unit": "m2",
        "source": "Telex",
        "type": "Raw"
    }

    updated_metric = MetricUpset.from_dict(updated_metric_data)

    update_metric(client, metric_id, updated_metric)
```

+ Parameters :
  + **client** (*AuthenticatedClient*) : HTTP client.
  + **metric_id** (*str*) : the metric id to update.
  + **update_metric** (*MetricUpset* or *dict*) : Structure that contains all updated information of metric.


  
### update_metric_az_sr 

**Aim** : Update access zones or storage rule of a metric.

```python
from indasuite_api_client import AuthenticatedClient, MetricPatch
from indasuite_api_client.ressources import update_metric_az_sr

with client as client:
    metric_id = "main@cip_60"

    updated_metric_data = {
        "accessZonesId": [
            "ef27d903-aa6c-41cf-abb3-b5dd686e3a73",
            "a370e10b-17f6-4d9e-a880-bfb164d5c3c1"
        ],
        "storageRuleId": "dcb8a50e-f4c7-47a3-9a68-34e01dffc65e"
    }
    metric_patch = MetricPatch.from_dict(updated_metric_data)

    update_metric_az_sr(client, metric_id, metric_patch)
```

+ Parameters :
  + **client** (*AuthenticatedClient*) : HTTP client.
  + **metric_id** (*str*) : the metric id to update.
  + **metric_patch** (*MetricPatch* or *dict*) : Structure that contains updated access zones and/or storage rule of metric.

### rename_metric

**Aim** : Rename metric.

```python
from indasuite_api_client import AuthenticatedClient
from indasuite_api_client.ressources import rename_metric

with client as client:
    rename_metric(client=client, metric_id="main@cip_60", new_name="TEST_NAME")
```

+ Parameters :
  + **client** (*AuthenticatedClient*) : HTTP client.
  + **metric_id** (*str*) : the metric id to rename.
  + **new_name** (*str*) : the new name.

### delete_metric

**Aim** : Delete metric.

```python
from indasuite_api_client import AuthenticatedClient
from indasuite_api_client.ressources import delete_metric

with client as client:
    delete_metric(client=client, metric_id="main@cip_60")
```

+ Parameters :
  + **client** (*AuthenticatedClient*) : HTTP client.
  + **metric_id** (*str*) : the metric id to delete.

