Metadata-Version: 2.4
Name: thorcast_api_client
Version: 0.2.1
Summary: Client Python de l'API ThorCast (Holmium) : courbes de charge LT, historiques et catalogues, avec respect du quota de requêtes
Keywords: thorcast,holmium,api,electricity,load-curves
Author: JBCAYRE
Author-email: jcayre@mint.eco
Requires-Python: >=3.8,<4.0
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Requires-Dist: requests (>=2.26.0,<3.0.0)
Description-Content-Type: text/markdown

# ThorCast API Client V0.2

## 📌 Description (je suis nul en Markdown , j'espère que ce sera lisible)

`thorcast_api_client` est un client Python permettant d'interagir avec l'API **ThorCast** mise en place par Holmium pour MINT.

Il prend en charge (normalement) :
- L'**authentification JWT**
- La récupération des **courbes de charge prévues**
- La récupération des **courbes de charge historiques**
- La gestion des **erreurs API**
- Le respect du **quota de requêtes** (depuis la 0.2.0)

## 🚀 Installation

### Via `pip`
```sh
pip install thorcast_api_client
```

### Via `poetry` pour les amateurs de Baudelaire
```sh
poetry add thorcast_api_client
```

## 📜 Utilisation 

### 🔒 Authentification : 

L'authentification passe par la requête d'un token JWS en injectant un MDP/Username :

```sh
from thorcast_api_client.client import ThorCastClient

client = ThorCastClient("mon_user", "mon_mdp")
```

### ⏱️ Quota de requêtes (0.2.0)

L'API limite à **60 requêtes par minute glissante** et renvoie `429 Too Many Requests` au-delà, avec un en-tête `Retry-After` (documentation Holmium v1.8, §5). Le client :
- **attend une place libre** avant chaque appel (limiteur partagé entre threads), plafonné par défaut au quota de l'API ;
- sur un 429, **attend le délai `Retry-After`** (60 s s'il est absent) puis retente, jusqu'à `max_retries` fois ; ensuite `RateLimitExceeded` est levée, avec le délai dans `exc.retry_after`.

```sh
client = ThorCastClient(
    "mon_user", "mon_mdp",
    max_requests_per_minute=50,  # sous le quota si d'autres applications partagent le compte ; None = pas de limite
    max_retries=3,               # nouvelles tentatives sur 429
    timeout=120,                 # timeout HTTP en secondes (None par défaut)
)
```

Rappel : 50 PRM au maximum par requête (`413` au-delà).
#### Lister les versions disponibles pour une ou plusieurs courbes LT

```sh
versions = client.get_lt_curves_versions(["prm1", "prm2"])
print(versions)
```
#### Récupérer les courbes de charge LT

```sh
courbes = client.get_lt_curves(["prm1", "prm2"], "2023-01-01T00:00:00Z", "2025-01-01T00:00:00Z")
print(courbes)
```

#### Récupérer les versions des courbes de catalogue 🤷 (rien compris à ce que ça remonte)

```sh
version_catalogues = client.get_catalog_versions(["catalogue1", "catalogue2"], "2023-01-01T00:00:00Z", "2025-01-01T00:00:00Z")
print(version_catalogues)
```
#### Récupérer les courbes de charge historiques

```sh
courbes_catalogue = client.get_catalog_curves(["id_catalogue1", "id_catalogue2"])
print(courbes_catalogue)
```

## 🗂️ Historique des versions

| Version | Date | Changements |
| --- | --- | --- |
| 0.2.1 | 2026-11-09 | Métadonnées PyPI uniquement : description, README affiché sur la page du projet, historique des versions. Code identique à la 0.2.0. |
| 0.2.0 | 2026-11-09 | Respect du quota de l'API (60 requêtes par minute glissante, limiteur partagé entre threads, paramètre `max_requests_per_minute`). Sur un `429`, attente du délai `Retry-After` puis nouvelle tentative (`max_retries`) ; `RateLimitExceeded` porte le délai dans `retry_after`. Paramètre `timeout` optionnel. Tests sans appel réseau. |
| 0.1.4.2 | 2025-07-25 | Retrait des affichages de débogage de l'authentification (URL et contenu de la requête). |
| 0.1.4.1 | 2025-07-25 | Retour à l'URL `profilage-api.holmium-consulting.com` et à l'identification par `email`. |
| 0.1.3 | 2025-06-19 | Passage à l'URL `api.thorcast.com` ; paramètre `username` au lieu de `identifier`. |
| 0.1.2 | 2025-02-18 | Première version publiée : authentification JWT, courbes LT et versions, courbes historiques, catalogues. |

Montée de version : incrémenter `version` dans `pyproject.toml`, ajouter une ligne à ce tableau, puis `python -m build` et `python -m twine upload dist/*`.


