"""Pipeline orchestration. The three stages from the design document are exposed both individually (:func:`fetch`, :func:`render`, :func:`impose`) and combined (:func:`build`) so each step can be inspected before continuing. """ from __future__ import annotations import json from collections.abc import Sequence from dataclasses import dataclass from pathlib import Path from genshin_tcg.config import Settings from genshin_tcg.data.assets import download_required_assets from genshin_tcg.data.catalog import Catalog, load_catalog, load_raw_source, save_catalog from genshin_tcg.data.fandom import ( FactionIconReport, FactionIconSource, FactionResolution, FactionSource, FandomSource, resolve_factions, sync_faction_icons, ) from genshin_tcg.data.paimon import DownloadReport, PaimonSource from genshin_tcg.logging_setup import get_logger from genshin_tcg.models import parse_catalog from genshin_tcg.pdf.imposition import ImpositionGrid, ImpositionResult, impose_pdf from genshin_tcg.rendering.context import load_faction_overrides from genshin_tcg.rendering.converters import HtmlConverter, PlaywrightConverter, Viewport from genshin_tcg.rendering.renderer import CardRenderer, RenderedCard, safe_name __all__ = [ "BuildResult", "FactionResult", "FetchResult", "build", "factions", "fetch", "impose", "render", ] _logger = get_logger("pipeline") @dataclass(frozen=True, slots=True) class FetchResult: catalog: Catalog downloads: DownloadReport | None source_json: Path @dataclass(frozen=True, slots=True) class BuildResult: fetch: FetchResult rendered: list[RenderedCard] imposition: ImpositionResult @dataclass(frozen=True, slots=True) class FactionResult: """Outcome of :func:`factions` (wiki resolution + override file update).""" resolution: FactionResolution output: Path written: bool added: tuple[str, ...] = () conflicts: tuple[str, ...] = () icons: FactionIconReport | None = None def fetch( settings: Settings, *, only: Sequence[str] | None = None, force: bool = False, with_assets: bool = True, ) -> FetchResult: """Stage 1 - download the localised JSON (+ assets) and build the catalogue.""" settings.ensure_directories() with PaimonSource(settings.source_base_url) as source: source.save_to(source.data_url(settings.language), settings.source_json, force=force) source.save_to(source.tags_url(settings.language), settings.tags_json, force=force) catalog = Catalog(cards=tuple(parse_catalog(load_raw_source(settings.source_json)))) _logger.info( "Parsed %d card(s): %d character(s), %d action(s)", len(catalog), len(catalog.characters), len(catalog.actions), ) if only: catalog = catalog.select(only) save_catalog(catalog, settings.catalog_path) downloads: DownloadReport | None = None if with_assets: downloads = download_required_assets( catalog.cards, assets_dir=settings.assets_dir, base_url=settings.source_base_url, force=force, ) if not downloads.ok: _logger.warning("%d asset(s) could not be downloaded", len(downloads.failed)) return FetchResult(catalog=catalog, downloads=downloads, source_json=settings.source_json) def render( settings: Settings, *, only: Sequence[str] | None = None, screenshot: bool = True, converter: HtmlConverter | None = None, ) -> list[RenderedCard]: """Stage 2 - emit HTML for every card and (optionally) rasterise to PNG. *converter* lets callers inject a pre-opened :class:`HtmlConverter` (useful in tests); when omitted a :class:`PlaywrightConverter` is created and closed. """ catalog = _load_catalogue(settings) if only: catalog = catalog.select(only) renderer = CardRenderer(settings) rendered = renderer.write_html(renderer.build_views(catalog)) if not screenshot: return rendered if converter is not None: return renderer.rasterise(rendered, converter) card = settings.card viewport = Viewport( width_px=card.design_width_px, height_px=card.design_height_px, scale_factor=card.scale_factor, ) with PlaywrightConverter(viewport, timeout_ms=settings.render.timeout_ms) as runner: return renderer.rasterise(rendered, runner) def impose( settings: Settings, *, only: Sequence[str] | None = None, output: Path | None = None, ) -> ImpositionResult: """Stage 3 - lay every rendered PNG out on A4 sheets and write a PDF.""" catalog = _load_catalogue(settings) if only: catalog = catalog.select(only) images = [settings.png_dir / f"{safe_name(card.id)}.png" for card in catalog] grid = _grid_from_settings(settings) return impose_pdf(images, output or settings.pdf_path, grid) def build( settings: Settings, *, only: Sequence[str] | None = None, force: bool = False, with_assets: bool = True, screenshot: bool = True, ) -> BuildResult: """Run all three stages in sequence.""" fetch_result = fetch(settings, only=only, force=force, with_assets=with_assets) rendered = render(settings, only=only, screenshot=screenshot) imposition = impose(settings, only=only, output=settings.pdf_path) return BuildResult(fetch=fetch_result, rendered=rendered, imposition=imposition) def factions( settings: Settings, *, overwrite: bool = False, force: bool = False, write: bool = True, icons: bool = True, source: FactionSource | None = None, icon_source: FactionIconSource | None = None, ) -> FactionResult: """Resolve card factions from the wiki and refresh the override file. Playable characters are matched to their wiki region and enemies to their family (see :mod:`genshin_tcg.data.fandom`). Unless *overwrite* is set, the existing ``assets/overrides/factions.json`` is preserved: hand-made entries win over scraped ones and only missing keys are added, so the file stays safe to edit by hand. When *icons* is set, the nation emblems are downloaded into ``assets/tcg/icons/factions/.png`` so the renderer shows an image instead of the text label. *source* / *icon_source* inject a fake wiki (tests); *write* ``False`` performs a dry run. """ catalog = _load_catalogue(settings) icon_report: FactionIconReport | None = None if source is None: with FandomSource(cache_dir=settings.wiki_dir, force=force) as wiki: resolution = resolve_factions(catalog, source=wiki) if icons: icon_report = sync_faction_icons( resolution, source=icon_source or wiki, assets_dir=settings.faction_icons_dir, force=force, ) else: resolution = resolve_factions(catalog, source=source) if icons and icon_source is not None: icon_report = sync_faction_icons( resolution, source=icon_source, assets_dir=settings.faction_icons_dir, force=force, ) existing = {} if overwrite else load_faction_overrides(settings.factions_override) added = tuple(sorted(set(resolution.assignments) - set(existing))) conflicts = tuple( sorted( card_id for card_id, faction in resolution.assignments.items() if card_id in existing and existing[card_id] != faction ) ) merged: dict[str, str] = {**resolution.assignments, **existing} if conflicts: _logger.warning( "Kept %d hand-made faction entry/entries over the wiki values: %s", len(conflicts), ", ".join(conflicts), ) output = settings.factions_override written = False if write: output.parent.mkdir(parents=True, exist_ok=True) payload = json.dumps(dict(sorted(merged.items())), ensure_ascii=False, indent=2) output.write_text(payload + "\n", encoding="utf-8") written = True _logger.info("Wrote %d faction override(s) to %s", len(merged), output) return FactionResult( resolution=resolution, output=output, written=written, added=added, conflicts=conflicts, icons=icon_report, ) def _load_catalogue(settings: Settings) -> Catalog: if not settings.catalog_path.is_file(): raise FileNotFoundError( f"No catalogue at {settings.catalog_path}. Run the 'fetch' command first." ) return load_catalog(settings.catalog_path) def _grid_from_settings(settings: Settings) -> ImpositionGrid: page = settings.page card = settings.card return ImpositionGrid( page_width_mm=page.width_mm, page_height_mm=page.height_mm, card_width_mm=card.width_mm, card_height_mm=card.height_mm, columns=page.columns, rows=page.rows, margin_mm=page.margin_mm, gutter_mm=page.gutter_mm, cut_marks=page.cut_marks, mark_length_mm=page.mark_length_mm, )