From 123c43aa05229941c87685d2c195d5e3f83d4f99 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20GUEZO?= Date: Sun, 1 Mar 2026 22:35:30 +0100 Subject: [PATCH] ajout: documentation --- docs/index.md | 6 +-- docs/scraper.md | 3 ++ docs/scraperdata.md | 4 ++ src/scraper.py | 123 +++++++++++++++++++++++++------------------- 4 files changed, 79 insertions(+), 57 deletions(-) create mode 100644 docs/scraper.md create mode 100644 docs/scraperdata.md diff --git a/docs/index.md b/docs/index.md index 549fea5..8e44418 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1 @@ -# Bienvenue sur la doc de Millesima - -Voici la documentation technique de mon scraper. - -::: scraper.Scraper \ No newline at end of file +# Millesima \ No newline at end of file diff --git a/docs/scraper.md b/docs/scraper.md new file mode 100644 index 0000000..1141949 --- /dev/null +++ b/docs/scraper.md @@ -0,0 +1,3 @@ +# Scraper + +::: scraper.Scraper \ No newline at end of file diff --git a/docs/scraperdata.md b/docs/scraperdata.md new file mode 100644 index 0000000..9197c05 --- /dev/null +++ b/docs/scraperdata.md @@ -0,0 +1,4 @@ + +# _ScraperData + +::: scraper._ScraperData \ No newline at end of file diff --git a/src/scraper.py b/src/scraper.py index 4f7527f..0dcc474 100755 --- a/src/scraper.py +++ b/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 : - "Appelation,Parker,J.Robinson,J.Suckling,Prix" + Agrège les données clés pour l'export CSV. + + 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 + prix = self.prix() return f"{appellation},{parker},{robinson},{suckling},{prix}" class Scraper: """ - Scraper est une classe qui permet de gerer - de façon dynamique des requetes uniquement - sur le serveur https de Millesima + Client HTTP optimisé pour le scraping de millesima.fr. + + 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": - "Mozilla/5.0 (Windows NT 10.0; Win64; x64) \ + "User-Agent": "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": - "fr-FR,fr;q=0.9,en;q=0.8", + "Accept-Language": "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