riftbound-scraper 1.0.0__py3-none-any.whl

riftbound_scraper/__init__.py

@@ -0,0 +1,3 @@
+"""Package principal de l'application CLI Riftbound Scraper."""
+
+__version__: str = "1.0.0"

riftbound_scraper/application/__init__.py

@@ -0,0 +1 @@
+"""Couche application : cas d'usage et orchestration."""

riftbound_scraper/application/assets/__init__.py

@@ -0,0 +1 @@
+"""Cas d'usage de synchronisation des assets."""

riftbound_scraper/application/assets/card_asset_sync_service.py

@@ -0,0 +1,118 @@
+"""Synchronisation des assets liés à une carte normalisée."""
+
+from __future__ import annotations
+
+from baobab_database.core.unit_of_work import UnitOfWork
+from sqlalchemy.orm import Session
+
+from riftbound_scraper.domain.assets.asset_download_gateway import AssetDownloadGateway
+from riftbound_scraper.domain.assets.asset_download_result import AssetDownloadResult
+from riftbound_scraper.domain.assets.asset_download_task import AssetDownloadTask
+from riftbound_scraper.domain.assets.asset_kind import AssetKind
+from riftbound_scraper.domain.card.asset_reference import AssetReference
+from riftbound_scraper.domain.card.normalized_card import NormalizedCard
+from riftbound_scraper.infrastructure.persistence.repositories import (
+    asset_record_repository,
+)
+
+
+class CardAssetSyncService:
+    """Orchestre le téléchargement des assets d'une carte persistée."""
+
+    def __init__(
+        self,
+        unit_of_work: UnitOfWork,
+        database_name: str,
+        download_gateway: AssetDownloadGateway,
+        asset_repository: asset_record_repository.AssetRecordRepository | None = None,
+    ) -> None:
+        self._unit_of_work = unit_of_work
+        self._database_name = database_name
+        self._download_gateway = download_gateway
+        self._asset_repository = (
+            asset_repository or asset_record_repository.AssetRecordRepository()
+        )
+
+    def sync_card_assets(
+        self,
+        card: NormalizedCard,
+    ) -> list[AssetDownloadResult]:
+        """Télécharge les assets liés à une carte normalisée.
+
+        :param card: Carte dont les références assets doivent être matérialisées.
+        :type card: NormalizedCard
+        :return: Résultats unitaires par asset traité.
+        :rtype: list[AssetDownloadResult]
+        """
+        with self._unit_of_work.begin(self._database_name) as session:
+            tasks = self._build_tasks(session, card)
+            return [
+                self._download_gateway.ensure_downloaded(session, task)
+                for task in tasks
+            ]
+
+    def _build_tasks(
+        self,
+        session: Session,
+        card: NormalizedCard,
+    ) -> list[AssetDownloadTask]:
+        tasks: list[AssetDownloadTask] = []
+        self._append_task(
+            tasks,
+            session,
+            card.card_image,
+            AssetKind.CARD_IMAGE,
+            card.source_id,
+        )
+        self._append_task(
+            tasks,
+            session,
+            card.rarity.icon,
+            AssetKind.RARITY_ICON,
+            card.rarity.rarity_id,
+        )
+        for domain in card.domains:
+            self._append_task(
+                tasks,
+                session,
+                domain.icon,
+                AssetKind.DOMAIN_ICON,
+                domain.domain_id,
+            )
+        for card_type in card.types:
+            self._append_task(
+                tasks,
+                session,
+                card_type.icon,
+                AssetKind.TYPE_ICON,
+                card_type.type_id,
+            )
+        for artist in card.artists:
+            self._append_task(
+                tasks,
+                session,
+                artist.icon,
+                AssetKind.ARTIST_ICON,
+                artist.artist_id,
+            )
+        return tasks
+
+    # pylint: disable=too-many-arguments,too-many-positional-arguments
+    def _append_task(
+        self,
+        tasks: list[AssetDownloadTask],
+        session: Session,
+        asset: AssetReference | None,
+        kind: AssetKind,
+        entity_slug: str,
+    ) -> None:
+        asset_id = self._asset_repository.get_id_by_url(session, asset)
+        if asset_id is None:
+            return
+        tasks.append(
+            AssetDownloadTask(
+                asset_id=asset_id,
+                kind=kind,
+                entity_slug=entity_slug,
+            ),
+        )

riftbound_scraper/application/normalization/__init__.py

@@ -0,0 +1 @@
+"""Cas d'usage de normalisation des données source."""

riftbound_scraper/application/normalization/ability_text_normalizer.py

@@ -0,0 +1,38 @@
+"""Convertit le HTML de compétence en texte lisible multiligne."""
+
+from __future__ import annotations
+
+import html
+import re
+
+from bs4 import BeautifulSoup, NavigableString, Tag
+
+
+class AbilityTextNormalizer:
+    """Normalise le contenu HTML des compétences en texte avec retours ligne."""
+
+    def normalize(self, ability_html: str | None) -> str | None:
+        """Convertit le HTML source en texte lisible.
+
+        :param ability_html: HTML brut de compétence.
+        :type ability_html: str | None
+        :return: Texte normalisé ou ``None`` si absent.
+        :rtype: str | None
+        """
+        if ability_html is None or not ability_html.strip():
+            return None
+        soup = BeautifulSoup(ability_html, "html.parser")
+        self._replace_breaks_with_newlines(soup)
+        raw_text = soup.get_text()
+        decoded = html.unescape(raw_text)
+        lines = [line.strip() for line in decoded.splitlines()]
+        compact = "\n".join(line for line in lines if line)
+        normalized = re.sub(r"\n{3,}", "\n\n", compact)
+        return normalized or None
+
+    def _replace_breaks_with_newlines(self, root: Tag) -> None:
+        for break_tag in root.find_all("br"):
+            break_tag.replace_with(NavigableString("\n"))
+        for paragraph in root.find_all("p"):
+            if paragraph.contents:
+                paragraph.append(NavigableString("\n"))

riftbound_scraper/application/normalization/card_variant_detector.py

@@ -0,0 +1,44 @@
+"""Détection des variantes de cartes depuis le code public."""
+
+from __future__ import annotations
+
+import re
+
+from riftbound_scraper.domain.card.card_variant_kind import CardVariantKind
+
+
+class CardVariantDetector:
+    """Détecte le type de variante à partir du ``public_code`` source."""
+
+    _VARIANT_PATTERN = re.compile(r"-(\d+)([a-z*]+)/", re.IGNORECASE)
+
+    def detect(self, public_code: str) -> tuple[CardVariantKind, str | None]:
+        """Analyse le code public et retourne le type de variante.
+
+        :param public_code: Code public source (ex. ``OGN-066a/298``).
+        :type public_code: str
+        :return: Type de variante et suffixe éventuel.
+        :rtype: tuple[CardVariantKind, str | None]
+        """
+        match = self._VARIANT_PATTERN.search(public_code)
+        if match is not None:
+            suffix = match.group(2)
+            if suffix == "*":
+                return CardVariantKind.SHOWCASE, "*"
+            return CardVariantKind.ALPHABETIC, suffix.lower()
+        if "*" in public_code:
+            return CardVariantKind.SHOWCASE, "*"
+        return CardVariantKind.STANDARD, None
+
+    def extract_collector_number_label(self, public_code: str) -> str:
+        """Extrait le numéro de collection affiché depuis le code public.
+
+        :param public_code: Code public source.
+        :type public_code: str
+        :return: Numéro affiché incluant variante (ex. ``066a``, ``227*``).
+        :rtype: str
+        """
+        match = re.search(r"-([^/]+)/", public_code)
+        if match is not None:
+            return match.group(1)
+        return public_code

riftbound_scraper/application/normalization/gallery_snapshot_normalizer.py

@@ -0,0 +1,61 @@
+"""Normalise un snapshot galerie complet en sets et cartes métier."""
+
+from __future__ import annotations
+
+from riftbound_scraper.application.normalization.normalized_gallery_result import (
+    NormalizedGalleryResult,
+)
+from riftbound_scraper.application.normalization.raw_card_normalizer import (
+    RawCardNormalizer,
+)
+from riftbound_scraper.domain.card.card_set import CardSet
+from riftbound_scraper.domain.dto.raw_card_dto import RawCardDto
+from riftbound_scraper.domain.dto.raw_set_dto import RawSetDto
+from riftbound_scraper.domain.source.raw_gallery_snapshot import RawGallerySnapshot
+
+
+class GallerySnapshotNormalizer:
+    """Orchestre la normalisation d'un ``RawGallerySnapshot`` complet."""
+
+    def __init__(
+        self,
+        card_normalizer: RawCardNormalizer | None = None,
+        default_locale: str = "fr-fr",
+    ) -> None:
+        self._card_normalizer: RawCardNormalizer = (
+            card_normalizer or RawCardNormalizer()
+        )
+        self._default_locale: str = default_locale
+
+    def normalize(self, snapshot: RawGallerySnapshot) -> NormalizedGalleryResult:
+        """Normalise sets et cartes d'un snapshot source.
+
+        :param snapshot: Snapshot brut issu du client source.
+        :type snapshot: RawGallerySnapshot
+        :return: Résultat normalisé prêt pour la persistence.
+        :rtype: NormalizedGalleryResult
+        """
+        normalized_sets = [
+            self._normalize_set(RawSetDto(raw_set)) for raw_set in snapshot.raw_sets
+        ]
+        normalized_cards = [
+            self._card_normalizer.normalize(
+                RawCardDto(raw_card),
+                source_page_url=snapshot.source_url,
+                source_locale=self._default_locale,
+            )
+            for raw_card in snapshot.raw_cards
+        ]
+        return NormalizedGalleryResult(
+            sets=normalized_sets,
+            cards=normalized_cards,
+            source_url=snapshot.source_url,
+            source_locale=self._default_locale,
+        )
+
+    def _normalize_set(self, raw_set: RawSetDto) -> CardSet:
+        return CardSet(
+            set_id=raw_set.set_id,
+            name=raw_set.name,
+            collector_number_max=raw_set.collector_number_max,
+        )

riftbound_scraper/application/normalization/normalized_gallery_result.py

@@ -0,0 +1,37 @@
+"""Résultat de normalisation d'un snapshot galerie complet."""
+
+from __future__ import annotations
+
+from riftbound_scraper.domain.card.card_set import CardSet
+from riftbound_scraper.domain.card.normalized_card import NormalizedCard
+
+
+class NormalizedGalleryResult:
+    """Ensemble des sets et cartes normalisés depuis un snapshot source.
+
+    :param sets: Sets normalisés.
+    :type sets: list[CardSet]
+    :param cards: Cartes normalisées.
+    :type cards: list[NormalizedCard]
+    :param source_url: URL source utilisée.
+    :type source_url: str
+    :param source_locale: Locale source déduite ou fournie.
+    :type source_locale: str | None
+    """
+
+    sets: list[CardSet]
+    cards: list[NormalizedCard]
+    source_url: str
+    source_locale: str | None
+
+    def __init__(
+        self,
+        sets: list[CardSet],
+        cards: list[NormalizedCard],
+        source_url: str,
+        source_locale: str | None = None,
+    ) -> None:
+        self.sets = sets
+        self.cards = cards
+        self.source_url = source_url
+        self.source_locale = source_locale

riftbound_scraper/application/normalization/raw_card_normalizer.py

@@ -0,0 +1,217 @@
+"""Normalise une carte brute en modèle métier ``NormalizedCard``."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from riftbound_scraper.application.normalization.ability_text_normalizer import (
+    AbilityTextNormalizer,
+)
+from riftbound_scraper.application.normalization.card_variant_detector import (
+    CardVariantDetector,
+)
+from riftbound_scraper.application.normalization.source_asset_mapper import (
+    SourceAssetMapper,
+)
+from riftbound_scraper.domain.card.card_artist import CardArtist
+from riftbound_scraper.domain.card.card_audit_metadata import CardAuditMetadata
+from riftbound_scraper.domain.card.card_domain import CardDomain
+from riftbound_scraper.domain.card.card_rarity import CardRarity
+from riftbound_scraper.domain.card.card_set import CardSet
+from riftbound_scraper.domain.card.card_type_entry import CardTypeEntry
+from riftbound_scraper.domain.card.normalized_card import NormalizedCard
+from riftbound_scraper.domain.dto.raw_card_dto import RawCardDto
+
+
+class RawCardNormalizer:
+    """Transforme un ``RawCardDto`` en ``NormalizedCard`` stable."""
+
+    def __init__(
+        self,
+        ability_text_normalizer: AbilityTextNormalizer | None = None,
+        variant_detector: CardVariantDetector | None = None,
+        asset_mapper: SourceAssetMapper | None = None,
+    ) -> None:
+        self._ability_text_normalizer: AbilityTextNormalizer = (
+            ability_text_normalizer or AbilityTextNormalizer()
+        )
+        self._variant_detector: CardVariantDetector = (
+            variant_detector or CardVariantDetector()
+        )
+        self._asset_mapper: SourceAssetMapper = asset_mapper or SourceAssetMapper()
+
+    def normalize(
+        self,
+        raw_card: RawCardDto,
+        source_page_url: str | None = None,
+        source_locale: str | None = None,
+    ) -> NormalizedCard:
+        """Normalise une carte source en modèle métier.
+
+        :param raw_card: DTO carte brute.
+        :type raw_card: RawCardDto
+        :param source_page_url: URL page galerie pour audit.
+        :type source_page_url: str | None
+        :param source_locale: Locale source pour audit.
+        :type source_locale: str | None
+        :return: Carte normalisée persistable.
+        :rtype: NormalizedCard
+        """
+        ability_html = raw_card.get_ability_html()
+        variant_kind, variant_suffix = self._variant_detector.detect(
+            raw_card.public_code
+        )
+        collector_label = self._variant_detector.extract_collector_number_label(
+            raw_card.public_code
+        )
+        audit = CardAuditMetadata(
+            raw_payload=raw_card.payload,
+            source_locale=source_locale,
+            source_page_url=source_page_url,
+            orientation=raw_card.orientation,
+            ability_html=ability_html,
+        )
+        return NormalizedCard(
+            source_id=raw_card.source_id,
+            public_code=raw_card.public_code,
+            name=raw_card.name,
+            collector_number_label=collector_label,
+            collector_number_base=raw_card.collector_number_base,
+            card_set=self._map_set(raw_card),
+            rarity=self._map_rarity(raw_card),
+            domains=self._map_domains(raw_card),
+            types=self._map_types(raw_card),
+            artists=self._map_artists(raw_card),
+            card_image=self._asset_mapper.map_optional(
+                raw_card.get_section("cardImage")
+            ),
+            energy=raw_card.get_int_stat("energy"),
+            runic_essence=raw_card.get_int_stat("power"),
+            might=raw_card.get_int_stat("might"),
+            ability_text=self._ability_text_normalizer.normalize(ability_html),
+            variant_kind=variant_kind,
+            variant_suffix=variant_suffix,
+            audit=audit,
+        )
+
+    def _map_set(self, raw_card: RawCardDto) -> CardSet:
+        set_section = raw_card.get_section("set")
+        if set_section is None:
+            return CardSet(set_id="", name="")
+        value = set_section.get("value")
+        if not isinstance(value, dict):
+            return CardSet(set_id="", name="")
+        set_id = str(value.get("id", ""))
+        name = str(value.get("label", ""))
+        return CardSet(set_id=set_id, name=name)
+
+    def _map_rarity(self, raw_card: RawCardDto) -> CardRarity:
+        rarity_section = raw_card.get_section("rarity")
+        if rarity_section is None:
+            return CardRarity(rarity_id="", label="")
+        value = rarity_section.get("value")
+        if not isinstance(value, dict):
+            return CardRarity(rarity_id="", label="")
+        icon_payload = value.get("icon")
+        icon = self._asset_mapper.map_optional(
+            cast(dict[str, Any], icon_payload)
+            if isinstance(icon_payload, dict)
+            else None
+        )
+        return CardRarity(
+            rarity_id=str(value.get("id", "")),
+            label=str(value.get("label", "")),
+            icon=icon,
+        )
+
+    def _map_domains(self, raw_card: RawCardDto) -> list[CardDomain]:
+        domain_section = raw_card.get_section("domain")
+        if domain_section is None:
+            return []
+        values = domain_section.get("values")
+        if not isinstance(values, list):
+            return []
+        domains: list[CardDomain] = []
+        for entry in values:
+            if not isinstance(entry, dict):
+                continue
+            icon_payload = entry.get("icon")
+            domains.append(
+                CardDomain(
+                    domain_id=str(entry.get("id", "")),
+                    label=str(entry.get("label", "")),
+                    icon=self._asset_mapper.map_optional(
+                        cast(dict[str, Any], icon_payload)
+                        if isinstance(icon_payload, dict)
+                        else None
+                    ),
+                )
+            )
+        return domains
+
+    def _map_types(self, raw_card: RawCardDto) -> list[CardTypeEntry]:
+        card_type_section = raw_card.get_section("cardType")
+        if card_type_section is None:
+            return []
+        types: list[CardTypeEntry] = []
+        types.extend(
+            self._map_type_entries(card_type_section.get("type"), is_super_type=False)
+        )
+        types.extend(
+            self._map_type_entries(
+                card_type_section.get("superType"),
+                is_super_type=True,
+            )
+        )
+        return types
+
+    def _map_type_entries(
+        self,
+        entries: object,
+        is_super_type: bool,
+    ) -> list[CardTypeEntry]:
+        if not isinstance(entries, list):
+            return []
+        mapped: list[CardTypeEntry] = []
+        for entry in entries:
+            if not isinstance(entry, dict):
+                continue
+            icon_payload = entry.get("icon")
+            mapped.append(
+                CardTypeEntry(
+                    type_id=str(entry.get("id", "")),
+                    label=str(entry.get("label", "")),
+                    icon=self._asset_mapper.map_optional(
+                        cast(dict[str, Any], icon_payload)
+                        if isinstance(icon_payload, dict)
+                        else None
+                    ),
+                    is_super_type=is_super_type,
+                )
+            )
+        return mapped
+
+    def _map_artists(self, raw_card: RawCardDto) -> list[CardArtist]:
+        illustrator_section = raw_card.get_section("illustrator")
+        if illustrator_section is None:
+            return []
+        values = illustrator_section.get("values")
+        if not isinstance(values, list):
+            return []
+        artists: list[CardArtist] = []
+        for entry in values:
+            if not isinstance(entry, dict):
+                continue
+            icon_payload = entry.get("icon")
+            artists.append(
+                CardArtist(
+                    artist_id=str(entry.get("id", "")),
+                    name=str(entry.get("label", "")),
+                    icon=self._asset_mapper.map_optional(
+                        cast(dict[str, Any], icon_payload)
+                        if isinstance(icon_payload, dict)
+                        else None
+                    ),
+                )
+            )
+        return artists

riftbound_scraper/application/normalization/source_asset_mapper.py

@@ -0,0 +1,36 @@
+"""Mappe les structures image/icône source vers ``AssetReference``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from riftbound_scraper.domain.card.asset_reference import AssetReference
+
+
+class SourceAssetMapper:
+    """Convertit les objets image du payload source en références normalisées."""
+
+    def map_optional(self, payload: dict[str, Any] | None) -> AssetReference | None:
+        """Mappe un objet image source optionnel.
+
+        :param payload: Objet image source.
+        :type payload: dict[str, Any] | None
+        :return: Référence asset ou ``None``.
+        :rtype: AssetReference | None
+        """
+        if payload is None:
+            return None
+        url = payload.get("url")
+        if not isinstance(url, str) or not url:
+            return None
+        provider = payload.get("provider")
+        mime_type = payload.get("mimeType")
+        accessibility = payload.get("accessibilityText")
+        return AssetReference(
+            url=url,
+            provider=str(provider) if isinstance(provider, str) else None,
+            mime_type=str(mime_type) if isinstance(mime_type, str) else None,
+            accessibility_text=(
+                str(accessibility) if isinstance(accessibility, str) else None
+            ),
+        )

riftbound_scraper/application/sync/__init__.py

@@ -0,0 +1 @@
+"""Cas d'usage de synchronisation et vérification locale."""

riftbound_scraper/application/sync/gallery_sync_service.py

@@ -0,0 +1,115 @@
+"""Orchestration source → normalisation → persistence → assets."""
+
+from __future__ import annotations
+
+from riftbound_scraper.application.assets.card_asset_sync_service import (
+    CardAssetSyncService,
+)
+from riftbound_scraper.application.normalization.gallery_snapshot_normalizer import (
+    GallerySnapshotNormalizer,
+)
+from riftbound_scraper.application.sync.set_not_found_error import SetNotFoundError
+from riftbound_scraper.application.sync.sync_execution_report import (
+    SyncExecutionReport,
+)
+from riftbound_scraper.domain.card.card_set import CardSet
+from riftbound_scraper.domain.card.normalized_card import NormalizedCard
+from riftbound_scraper.domain.persistence.card_persistence_gateway import (
+    CardPersistenceGateway,
+)
+from riftbound_scraper.domain.source.raw_gallery_snapshot import RawGallerySnapshot
+from riftbound_scraper.infrastructure.source.riftbound_source_client import (
+    RiftboundSourceClient,
+)
+
+
+class GallerySyncService:
+    """Synchronise sets, cartes et assets depuis la galerie Riftbound."""
+
+    def __init__(
+        self,
+        source_client: RiftboundSourceClient,
+        snapshot_normalizer: GallerySnapshotNormalizer,
+        card_gateway: CardPersistenceGateway,
+        asset_sync_service: CardAssetSyncService,
+    ) -> None:
+        self._source_client = source_client
+        self._snapshot_normalizer = snapshot_normalizer
+        self._card_gateway = card_gateway
+        self._asset_sync_service = asset_sync_service
+
+    def sync_all(self) -> SyncExecutionReport:
+        """Synchronise tous les sets et cartes détectés.
+
+        :return: Rapport d'exécution détaillé.
+        :rtype: SyncExecutionReport
+        """
+        return self._sync(target_set_id=None)
+
+    def sync_set(self, set_id: str) -> SyncExecutionReport:
+        """Synchronise un set identifié.
+
+        :param set_id: Identifiant métier du set (ex. ``UNL``).
+        :type set_id: str
+        :return: Rapport d'exécution détaillé.
+        :rtype: SyncExecutionReport
+        :raises SetNotFoundError: Si le set est absent du snapshot source.
+        """
+        return self._sync(target_set_id=set_id)
+
+    def _sync(self, target_set_id: str | None) -> SyncExecutionReport:
+        snapshot = self._source_client.fetch_snapshot()
+        normalized = self._snapshot_normalizer.normalize(snapshot)
+        warnings = self._build_warnings(snapshot)
+        sets, cards = self._filter_targets(
+            normalized.sets,
+            normalized.cards,
+            target_set_id,
+        )
+        report = SyncExecutionReport(
+            target_set_id=target_set_id,
+            warnings=warnings,
+        )
+        for card_set in sets:
+            self._card_gateway.upsert_set(card_set)
+            report.sets_processed += 1
+        for card in cards:
+            persisted = self._card_gateway.upsert_card(card)
+            report.cards_processed += 1
+            if persisted.created:
+                report.cards_created += 1
+            else:
+                report.cards_updated += 1
+            asset_results = self._asset_sync_service.sync_card_assets(card)
+            for asset_result in asset_results:
+                if asset_result.error_message:
+                    report.assets_failed += 1
+                elif asset_result.downloaded:
+                    report.assets_downloaded += 1
+                elif asset_result.skipped:
+                    report.assets_skipped += 1
+        return report
+
+    def _filter_targets(
+        self,
+        sets: list[CardSet],
+        cards: list[NormalizedCard],
+        target_set_id: str | None,
+    ) -> tuple[list[CardSet], list[NormalizedCard]]:
+        if target_set_id is None:
+            return sets, cards
+        filtered_sets = [
+            card_set for card_set in sets if card_set.set_id == target_set_id
+        ]
+        if not filtered_sets:
+            raise SetNotFoundError(target_set_id)
+        filtered_cards = [
+            card for card in cards if card.card_set.set_id == target_set_id
+        ]
+        return filtered_sets, filtered_cards
+
+    def _build_warnings(self, snapshot: RawGallerySnapshot) -> list[str]:
+        mismatch = snapshot.cards_count_mismatch
+        if mismatch is None or not mismatch.has_mismatch:
+            return []
+        return [str(mismatch)]