ajout: documentation

docs/index.md

@@ -1,5 +1 @@
-# Bienvenue sur la doc de Millesima
+# Millesima
-
-Voici la documentation technique de mon scraper.
-
-::: scraper.Scraper

docs/scraper.md

@@ -0,0 +1,3 @@
+# Scraper
+
+::: scraper.Scraper

docs/scraperdata.md

@@ -0,0 +1,4 @@
+
+# _ScraperData
+
+::: scraper._ScraperData

src/scraper.py

@@ -9,21 +9,28 @@ from json import JSONDecodeError, loads
 
 
 class _ScraperData:
-    """_summary_"""
+    """
+    Conteneur de données spécialisé pour extraire les informations des dictionnaires JSON.
+
+    Cette classe agit comme une interface simplifiée au-dessus du dictionnaire brut
+    renvoyé par la balise __NEXT_DATA__ du site Millesima.
+    """
 
     def __init__(self, data: dict[str, object]) -> None:
-        """_summary_
+        """
+        Initialise le conteneur avec un dictionnaire de données.
 
         Args:
-            data (dict[str, object]): _description_
+            data (dict[str, object]): Le dictionnaire JSON brut extrait de la page.
         """
         self._data: dict[str, object] = data
 
     def _getcontent(self) -> dict[str, object] | None:
-        """_summary_
+        """
+        Navigue dans l'arborescence Redux pour atteindre le contenu du produit.
 
         Returns:
-            dict[str, object]: _description_
+            dict[str, object] | None: Le dictionnaire du produit ou None si la structure diffère.
         """
         current_data: dict[str, object] = self._data
         for key in ["initialReduxState", "product", "content"]:
@@ -35,10 +42,11 @@ class _ScraperData:
         return current_data
 
     def _getattributes(self) -> dict[str, object] | None:
-        """_summary_
+        """
+        Extrait les attributs techniques (notes, appellations, etc.) du produit.
 
         Returns:
-            dict[str, object]: _description_
+            dict[str, object] | None: Les attributs du vin ou None.
         """
         current_data: object = self._getcontent()
         if current_data is None:
@@ -47,9 +55,13 @@ class _ScraperData:
 
     def prix(self) -> float | None:
         """
-        Retourne le prix unitaire d'une bouteille (75cl).
+        Calcule le prix unitaire d'une bouteille (standardisée à 75cl).
 
-        Si aucun prix n'est disponible, retourne None.
+        Le site vend souvent par caisses (6, 12 bouteilles) ou formats (Magnum).
+        Cette méthode normalise le prix pour obtenir celui d'une seule unité.
+
+        Returns:
+            float | None: Le prix calculé arrondi à 2 décimales, ou None.
         """
 
         content = self._getcontent()
@@ -91,10 +103,11 @@ class _ScraperData:
         return prix_calcule
 
     def appellation(self) -> str | None:
-        """_summary_
+        """
+        Extrait le nom de l'appellation du vin.
 
         Returns:
-            str: _description_
+            str | None: Le nom (ex: 'Pauillac') ou None.
         """
         attrs: dict[str, object] | None = self._getattributes()
 
@@ -105,13 +118,16 @@ class _ScraperData:
         return None
 
     def _getcritiques(self, name: str) -> str | None:
-        """_summary_
+        """
+        Méthode générique pour parser les notes des critiques (Parker, Suckling, etc.).
+
+        Gère les notes simples ("95") et les plages de notes ("95-97") en faisant la moyenne.
 
         Args:
-            name (str): _description_
+            name (str): La clé de l'attribut dans le JSON (ex: 'note_rp').
 
         Returns:
-            str | None: _description_
+            str | None: La note formatée en chaîne de caractères ou None.
         """
 
         current_value: dict[str, object] | None = self._getattributes()
@@ -130,45 +146,53 @@ class _ScraperData:
         return None
 
     def parker(self) -> str | None:
+        """Note Robert Parker."""
         return self._getcritiques("note_rp")
 
     def robinson(self) -> str | None:
+        """Note Jancis Robinson."""
         return self._getcritiques("note_jr")
 
     def suckling(self) -> str | None:
+        """Note James Suckling."""
         return self._getcritiques("note_js")
 
     def getdata(self) -> dict[str, object]:
+        """Retourne le dictionnaire de données complet."""
         return self._data
 
     def informations(self) -> str:
         """
-        Retourne toutes les informations sous la forme :
+        Agrège les données clés pour l'export CSV.
-        "Appelation,Parker,J.Robinson,J.Suckling,Prix"
+
+        Returns:
+            str: Ligne formatée : "Appellation,Parker,Robinson,Suckling,Prix".
         """
 
         appellation = self.appellation()
         parker = self.parker()
         robinson = self.robinson()
         suckling = self.suckling()
-        try:
         prix = self.prix()
-        except ValueError:
-            prix = None
 
         return f"{appellation},{parker},{robinson},{suckling},{prix}"
 
 
 class Scraper:
     """
-    Scraper est une classe qui permet de gerer
+    Client HTTP optimisé pour le scraping de millesima.fr.
-    de façon dynamique des requetes uniquement
+
-    sur le serveur https de Millesima
+    Gère la session persistante, les headers de navigation et un cache double
+    pour optimiser les performances et la discrétion.
     """
 
     def __init__(self) -> None:
         """
-        Initialise la session de scraping.
+        Initialise l'infrastructure de navigation:
+        
+         - créer une session pour éviter de faire un handshake pour chaque requête
+         - ajout d'un header pour éviter le blocage de l'accès au site
+         - ajout d'un système de cache
         """
         self._url: str = "https://www.millesima.fr/"
         # Très utile pour éviter de renvoyer toujours les mêmes handshake
@@ -178,16 +202,16 @@ class Scraper:
         # bloque car on serait des robots
         self._session.headers.update(
             {
-                "User-Agent": 
+                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) \
-                    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) \
                      AppleWebKit/537.36 (KHTML, like Gecko) \
                      Chrome/122.0.0.0 Safari/537.36",
-                "Accept-Language": 
+                "Accept-Language": "fr-FR,fr;q=0.9,en;q=0.8",
-                    "fr-FR,fr;q=0.9,en;q=0.8",
             }
         )
         # Système de cache pour éviter de solliciter le serveur inutilement
+        # utilise pour _request
         self._latest_request: tuple[(str, Response)] | None = None
+        # utilise pour getsoup
         self._latest_soups: OrderedDict[str, BeautifulSoup] = OrderedDict[
             str, BeautifulSoup
         ]()
@@ -202,7 +226,7 @@ class Scraper:
         Returns:
             Response: L'objet réponse de la requête.
 
-        Raise:
+        Raises:
             HTTPError: Si le serveur renvoie un code d'erreur (4xx, 5xx).
         """
         target_url: str = self._url + subdir.lstrip("/")
@@ -223,7 +247,7 @@ class Scraper:
         Returns:
             Response: L'objet réponse (cache ou nouvelle requête).
 
-        Raise:
+        Raises:
             HTTPError: Si le serveur renvoie un code d'erreur (4xx, 5xx).
         """
 
@@ -253,7 +277,7 @@ class Scraper:
         Returns:
             BeautifulSoup: L'objet parsé pour extraction de données.
 
-        Raise:
+        Raises:
             HTTPError: Si le serveur renvoie un code d'erreur (4xx, 5xx).
         """
 
@@ -274,23 +298,20 @@ class Scraper:
     def getjsondata(self, subdir: str, id: str = "__NEXT_DATA__") -> _ScraperData:
         """
         Extrait les données JSON contenues dans la balise __NEXT_DATA__ du site.
-        Beaucoup de sites modernes (Next.js) stockent leur état initial dans
-        une balise <script> pour l'hydratation côté client.
 
         Args:
             subdir (str): Le chemin de la page.
-            id (str, optional): L'identifiant de la balise script (par défaut __NEXT_DATA__).
+            id (str, optional): L'identifiant de la balise script.
 
         Raises:
-            HTTPError: Soulevée par `getresponse` si le serveur renvoie un code d'erreur (4xx, 5xx).
+            HTTPError: Erreur renvoyée par le serveur (4xx, 5xx).
-            JSONDecodeError: Soulevée par `loads` si le contenu de la balise n'est pas un JSON valide.
+            JSONDecodeError: Si le contenu de la balise n'est pas un JSON valide.
-            ValueError: Soulevée manuellement si l'une des clés attendues (props, pageProps, etc.)
+            ValueError: Si les clés 'props' ou 'pageProps' sont absentes.
-                        est absente de la structure JSON.
 
         Returns:
-            dict[str, object]: Un dictionnaire contenant les données utiles
+            _ScraperData: Instance contenant les données extraites.
-                                 ou un dictionnaire vide en cas d'erreur.
         """
+
         soup: BeautifulSoup = self.getsoup(subdir)
         script: Tag | None = soup.find("script", id=id)
 
@@ -308,13 +329,8 @@ class Scraper:
         return _ScraperData(cast(dict[str, object], current_data))
 
     def _geturlproductslist(self, subdir: str) -> list[str] | None:
-        """_summary_
+        """
-
+        Récupère la liste des produits d'une page de catégorie.
-        Args:
-            subdir (str): _description_
-
-        Returns:
-            _type_: _description_
         """
         try:
             data: dict[str, object] = self.getjsondata(subdir).getdata()
@@ -332,11 +348,13 @@ class Scraper:
             return None
 
     def getvins(self, subdir: str, filename: str, reset: bool) -> None:
-        """_summary_
+        """
+        Scrape récursivement toutes les pages d'une catégorie et sauvegarde en CSV.
 
         Args:
-            subdir (str): _description_
+            subdir (str): La catégorie (ex: '/vins-rouges').
-            filename (str): _description_
+            filename (str): Nom du fichier de sortie (ex: 'vins.csv').
+            reset (bool): (Optionnel) pour réinitialiser le processus.
         """
         with open(filename, "w") as f:
             cache: set[str] = set[str]()
@@ -345,8 +363,9 @@ class Scraper:
 
             while True:
                 page += 1
-                products_list: list[str] | None = \
+                products_list: list[str] | None = self._geturlproductslist(
-                    self._geturlproductslist(f"{subdir}?page={page}")
+                    f"{subdir}?page={page}"
+                )
 
                 if not products_list:
                     break