1"""
 2Módulo csv_writer.py
 3=====================
 4
 5[PT-BR]
 6Função utilitária para gravar listas de objetos ``Pokemon`` em arquivos CSV.
 7O módulo aplica uma limpeza básica nos dados, removendo quebras de linha e
 8espaços em excesso, além de pular linhas vazias ou inválidas.
 9
10Também registra no log a quantidade de registros exportados e quaisquer
11linhas ignoradas por estarem praticamente vazias.
12
13[EN]
14Utility function to write lists of ``Pokemon`` objects to CSV files.
15The module applies basic data cleaning, removing line breaks and
16extra spaces, and skips empty or invalid rows.
17
18It also logs the number of exported records and any skipped entries
19due to being nearly empty.
20
21Uso típico / Typical usage:
22    from services.csv_writer import write_pokemon_csv
23
24    written = write_pokemon_csv(pokemon_list, "output/pokemons.csv")
25    print(f"{written} Pokémon saved.")
26"""
27import csv
28import logging
29from typing import Iterable, Protocol, runtime_checkable
30from pathlib import Path
31from contextlib import suppress
32
33@runtime_checkable
34class HasToDict(Protocol):
35    def to_dict(self) -> dict[str, object]: ...
36
37def clean_csv_value(value: object) -> object:
38    """
39    [PT-BR] Limpa valores para escrita em CSV (quebras de linha, espaços).
40    [EN] Cleans values for CSV output (line breaks, extra spaces).
41    """
42    if isinstance(value, str):
43        return value.replace("\n", " ").strip()
44    return value
45
46def is_effectively_empty(row: dict[str, object]) -> bool:
47    """
48    [PT-BR] Verifica se a linha está vazia (ignora apenas None ou strings vazias).
49    [EN] Checks if the row is effectively empty (ignores None or empty strings).
50    """
51    return all(v in (None, "") for v in row.values())
52
53def write_pokemon_csv(pokemons: Iterable[HasToDict], path: str | Path, skip_empty: bool = True) -> int:
54    """
55    [PT-BR] Grava objetos `Pokemon` no CSV, com limpeza básica e validação de linhas.
56    [EN] Writes `Pokemon` objects to CSV, with basic cleaning and row validation.
57
58    Parâmetros:
59        pokemons (Iterable[HasToDict]): lista de objetos com .to_dict().
60        path (str | Path): caminho do arquivo de saída.
61        skip_empty (bool): se True, ignora linhas consideradas vazias.
62
63    Retorna:
64        int: quantidade de linhas efetivamente gravadas.
65    """
66    pokemons = list(pokemons)
67    if not pokemons:
68        logging.warning("Empty Pokémon list: nothing to write.")
69        return 0
70
71    try:
72        fieldnames = sorted({k for p in pokemons for k in p.to_dict().keys()})
73        written = 0
74
75        with open(path, "w", encoding="utf-8", newline="") as csvfile:
76            writer = csv.DictWriter(csvfile, fieldnames=fieldnames)
77            writer.writeheader()
78
79            for p in pokemons:
80                row = {k: clean_csv_value(v) for k, v in p.to_dict().items()}
81
82                if skip_empty and is_effectively_empty(row):
83                    logging.warning("Row skipped—effectively empty: %s", row)
84                    continue
85
86                writer.writerow(row)
87                written += 1
88
89        logging.info("%d Pokémon exported to '%s'.", written, path)
90        return written
91
92    except (IOError, OSError) as e:
93        logging.error("Failed to write CSV file '%s': %s", path, str(e), exc_info=True)
94        return 0