thorcast_api_client 0.1.4.2__tar.gz → 0.2.0__tar.gz

thorcast_api_client-0.2.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: thorcast_api_client
+Version: 0.2.0
+Summary: Un client Python pour interagir avec l'API ThorCast
+Author: JBCAYRE
+Author-email: jcayre@mint.eco
+Requires-Python: >=3.8,<4.0
+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)

{thorcast_api_client-0.1.4.2 → thorcast_api_client-0.2.0}/pyproject.toml

@@ -1,14 +1,13 @@
-[tool.poetry]
-name = "thorcast_api_client"
-version = "0.1.4.2"
-description = "Un client Python pour interagir avec l'API ThorCast"
-authors = ["JBCAYRE <jcayre@mint.eco>"]
-readme = "README.md"  
-
-[tool.poetry.dependencies]
-python = "^3.8"
-requests = "^2.26.0"
-
-[build-system]
-requires = ["poetry-core>=1.0.0"]
-build-backend = "poetry.core.masonry.api"
+[tool.poetry]
+name = "thorcast_api_client"
+version = "0.2.0"
+description = "Un client Python pour interagir avec l'API ThorCast"
+authors = ["JBCAYRE <jcayre@mint.eco>"]
+
+[tool.poetry.dependencies]
+python = "^3.8"
+requests = "^2.26.0"
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"

{thorcast_api_client-0.1.4.2 → thorcast_api_client-0.2.0}/thorcast_api_client/auth.py

@@ -14,6 +14,7 @@ class AuthManager:
         """Récupère un token JWT"""
         url = f"{API_BASE_URL}/backend/auth/token/"
         payload = {"email": self.username, "password": self.password}
+        
         response = requests.post(url, json=payload)
         if response.status_code == 200:
             data = response.json()

thorcast_api_client-0.2.0/thorcast_api_client/client.py

@@ -0,0 +1,98 @@
+import time
+
+import requests
+from thorcast_api_client.auth import AuthManager
+from thorcast_api_client.config import API_BASE_URL, DEFAULT_RETRY_AFTER, MAX_REQUESTS_PER_MINUTE
+from thorcast_api_client.exceptions import APIClientError, AuthenticationError, RateLimitExceeded, ServerError
+from thorcast_api_client.rate_limit import SlidingWindowRateLimiter
+
+
+def _parse_retry_after(response):
+    """Délai Retry-After en secondes, None s'il est absent ou non numérique."""
+    value = response.headers.get("Retry-After")
+    try:
+        return max(float(value), 0.0)
+    except (TypeError, ValueError):
+        return None
+
+
+class ThorCastClient:
+    """Client pour interagir avec l'API ThorCast.
+
+    - max_requests_per_minute : plafond d'appels par minute glissante, appliqué
+      côté client et partagé entre threads (None = pas de limitation). Par défaut,
+      le quota documenté par l'API ; à baisser si d'autres applications utilisent
+      le même compte.
+    - max_retries : nombre de nouvelles tentatives sur une réponse 429, après
+      l'attente indiquée par l'en-tête Retry-After.
+    - timeout : timeout HTTP en secondes passé à requests (None = aucun).
+    """
+
+    def __init__(self, username: str, password: str,
+                 max_requests_per_minute: int = MAX_REQUESTS_PER_MINUTE,
+                 max_retries: int = 3, timeout: float = None):
+        self.auth = AuthManager(username, password)
+        self.auth.authenticate()
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._rate_limiter = (SlidingWindowRateLimiter(max_requests_per_minute)
+                              if max_requests_per_minute else None)
+
+    def _send(self, method: str, url: str, **kwargs):
+        if self._rate_limiter:
+            self._rate_limiter.acquire()
+        return requests.request(method, url, headers=self.auth.get_headers(),
+                                timeout=self.timeout, **kwargs)
+
+    def _request(self, method: str, endpoint: str, **kwargs):
+        """Méthode générique pour effectuer une requête.
+
+        Un 429 est retenté jusqu'à max_retries fois après l'attente Retry-After."""
+        url = f"{API_BASE_URL}{endpoint}"
+
+        response = self._send(method, url, **kwargs)
+
+        retries = 0
+        while response.status_code == 429 and retries < self.max_retries:
+            retries += 1
+            time.sleep(_parse_retry_after(response) or DEFAULT_RETRY_AFTER)
+            response = self._send(method, url, **kwargs)
+
+        if response.status_code == 401:
+            raise AuthenticationError(401, "Echec d'authentification, token invalide.")
+        elif response.status_code == 429:
+            raise RateLimitExceeded(429, "Limite de requêtes dépassée.",
+                                    retry_after=_parse_retry_after(response))
+        elif response.status_code >= 500:
+            raise ServerError(response.status_code, "Erreur interne du serveur.")
+        elif not response.ok:
+            raise APIClientError(response.status_code, "Erreur inconnue.")
+
+        return response.json()
+
+    def get_lt_curves_versions(self, prms: list):
+        """Liste les versions disponibles des courbes de charge LT."""
+        endpoint = f"/backend/thorcast/v1/lt_curves/versions/?prms={','.join(prms)}"
+        return self._request("GET", endpoint)
+
+    def get_lt_curves(self, prms: list, sd: str, ed: str, versions: list = None, tz: str = "UTC"):
+        """Récupère les courbes de charge LT."""
+        endpoint = f"/backend/thorcast/v1/lt_curves/?prms={','.join(prms)}&sd={sd}&ed={ed}&tz={tz}"
+        if versions:
+            endpoint += f"&versions={','.join(versions)}"
+        return self._request("GET", endpoint)
+    
+    def get_historical_curves(self, prms: list, sd: str, ed: str, tz: str = "UTC"):
+        """Récupère les courbes de charge historiques."""
+        endpoint = f"/backend/thorcast/v1/historical_load_curves/?prms={','.join(prms)}&sd={sd}&ed={ed}&tz={tz}"
+        return self._request("GET", endpoint)
+    
+    def get_catalog_versions(self, catalogs: list, sd: str, ed: str):
+        """Liste les versions disponibles des courbes de charge LT."""
+        endpoint = f"/backend/thorcast/v1/catalog_curves/versions/?catalogs={','.join(catalogs)}&sd={sd}&ed={ed}"
+        return self._request("GET", endpoint)
+    
+    def get_catalog_curves(self, ids: list, tz: str = "UTC"):
+        """Récupère les courbes de charge catalog."""
+        endpoint = f"/backend/thorcast/v1/catalog_curves/?ids={','.join(ids)}&tz={tz}"
+        return self._request("GET", endpoint)

thorcast_api_client-0.2.0/thorcast_api_client/config.py

@@ -0,0 +1,11 @@
+API_BASE_URL = "https://profilage-api.holmium-consulting.com"
+HEADERS = {
+    "Accept": "application/json",
+    "Content-Type": "application/json",
+}
+
+# Quota de l'API : 60 requêtes par minute glissante (documentation v1.8, §5)
+MAX_REQUESTS_PER_MINUTE = 60
+# Attente avant nouvelle tentative sur 429 quand l'en-tête Retry-After manque :
+# une fenêtre glissante complète
+DEFAULT_RETRY_AFTER = 60.0

{thorcast_api_client-0.1.4.2 → thorcast_api_client-0.2.0}/thorcast_api_client/exceptions.py

@@ -11,8 +11,14 @@ class AuthenticationError(APIClientError):
     pass
 
 class RateLimitExceeded(APIClientError):
-    """Erreur lorsque la limite de requêtes est dépassée."""
-    pass
+    """Erreur lorsque la limite de requêtes est dépassée.
+
+    `retry_after` : délai d'attente en secondes indiqué par l'API (en-tête
+    Retry-After), None s'il est absent ou illisible."""
+
+    def __init__(self, status_code, message, retry_after=None):
+        super().__init__(status_code, message)
+        self.retry_after = retry_after
 
 class ServerError(APIClientError):
     """Erreur interne du serveur API."""

thorcast_api_client-0.2.0/thorcast_api_client/rate_limit.py

@@ -0,0 +1,36 @@
+import threading
+import time
+from collections import deque
+
+
+class SlidingWindowRateLimiter:
+    """Limite le nombre d'appels sur une fenêtre glissante (thread-safe).
+
+    L'API ThorCast renvoie 429 au-delà de 60 requêtes par minute glissante
+    (documentation de l'API v1.8, §5) : on attend une place libre côté client
+    plutôt que de consommer le quota et d'encaisser des 429.
+    """
+
+    def __init__(self, max_calls: int, period: float = 60.0,
+                 clock=time.monotonic, sleep=time.sleep):
+        if max_calls < 1:
+            raise ValueError("max_calls doit être >= 1")
+        self.max_calls = max_calls
+        self.period = period
+        self._clock = clock
+        self._sleep = sleep
+        self._calls = deque()
+        self._lock = threading.Lock()
+
+    def acquire(self):
+        """Bloque jusqu'à ce qu'un appel soit autorisé, puis l'enregistre."""
+        while True:
+            with self._lock:
+                now = self._clock()
+                while self._calls and now - self._calls[0] >= self.period:
+                    self._calls.popleft()
+                if len(self._calls) < self.max_calls:
+                    self._calls.append(now)
+                    return
+                wait = self.period - (now - self._calls[0])
+            self._sleep(wait)

thorcast_api_client-0.1.4.2/PKG-INFO

@@ -1,78 +0,0 @@
-Metadata-Version: 2.3
-Name: thorcast_api_client
-Version: 0.1.4.2
-Summary: Un client Python pour interagir avec l'API ThorCast
-Author: JBCAYRE
-Author-email: jcayre@mint.eco
-Requires-Python: >=3.8,<4.0
-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
-Requires-Dist: requests (>=2.26.0,<3.0.0)
-Description-Content-Type: text/markdown
-
-# ThorCast API Client V0.1
-
-## 📌 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**
-
-## 🚀 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")
-```
-#### 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)
-```
-

thorcast_api_client-0.1.4.2/README.md

@@ -1,60 +0,0 @@
-# ThorCast API Client V0.1
-
-## 📌 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**
-
-## 🚀 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")
-```
-#### 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)
-```

thorcast_api_client-0.1.4.2/thorcast_api_client/client.py

@@ -1,56 +0,0 @@
-import requests
-from thorcast_api_client.auth import AuthManager
-from thorcast_api_client.config import API_BASE_URL
-from thorcast_api_client.exceptions import APIClientError, AuthenticationError, RateLimitExceeded, ServerError
-
-class ThorCastClient:
-    """Client pour interagir avec l'API ThorCast."""
-    
-    def __init__(self, username: str, password: str):
-        self.auth = AuthManager(username, password)
-        self.auth.authenticate()
-
-    def _request(self, method: str, endpoint: str, **kwargs):
-        """Méthode générique pour effectuer une requête."""
-        url = f"{API_BASE_URL}{endpoint}"
-        headers = self.auth.get_headers()
-
-        response = requests.request(method, url, headers=headers, **kwargs)
-        
-        if response.status_code == 401:
-            raise AuthenticationError(401, "Echec d'authentification, token invalide.")
-        elif response.status_code == 429:
-            raise RateLimitExceeded(429, "Limite de requêtes dépassée.")
-        elif response.status_code >= 500:
-            raise ServerError(response.status_code, "Erreur interne du serveur.")
-        elif not response.ok:
-            raise APIClientError(response.status_code, "Erreur inconnue.")
-
-        return response.json()
-
-    def get_lt_curves_versions(self, prms: list):
-        """Liste les versions disponibles des courbes de charge LT."""
-        endpoint = f"/backend/thorcast/v1/lt_curves/versions/?prms={','.join(prms)}"
-        return self._request("GET", endpoint)
-
-    def get_lt_curves(self, prms: list, sd: str, ed: str, versions: list = None, tz: str = "UTC"):
-        """Récupère les courbes de charge LT."""
-        endpoint = f"/backend/thorcast/v1/lt_curves/?prms={','.join(prms)}&sd={sd}&ed={ed}&tz={tz}"
-        if versions:
-            endpoint += f"&versions={','.join(versions)}"
-        return self._request("GET", endpoint)
-    
-    def get_historical_curves(self, prms: list, sd: str, ed: str, tz: str = "UTC"):
-        """Récupère les courbes de charge historiques."""
-        endpoint = f"/backend/thorcast/v1/historical_load_curves/?prms={','.join(prms)}&sd={sd}&ed={ed}&tz={tz}"
-        return self._request("GET", endpoint)
-    
-    def get_catalog_versions(self, catalogs: list, sd: str, ed: str):
-        """Liste les versions disponibles des courbes de charge LT."""
-        endpoint = f"/backend/thorcast/v1/catalog_curves/versions/?catalogs={','.join(catalogs)}&sd={sd}&ed={ed}"
-        return self._request("GET", endpoint)
-    
-    def get_catalog_curves(self, ids: list, tz: str = "UTC"):
-        """Récupère les courbes de charge catalog."""
-        endpoint = f"/backend/thorcast/v1/catalog_curves/?ids={','.join(ids)}&tz={tz}"
-        return self._request("GET", endpoint)

thorcast_api_client-0.1.4.2/thorcast_api_client/config.py

@@ -1,5 +0,0 @@
-API_BASE_URL = "https://profilage-api.holmium-consulting.com"
-HEADERS = {
-    "Accept": "application/json",
-    "Content-Type": "application/json",
-}