Script de linha de comandos robusto em Python, com testes

1. Explique a tarefa com um exemplo real de entrada e de saída.
2. Diga se pode instalar dependências ou se tem de se limitar à biblioteca padrão.
3. Guarde o script e os testes e execute o pytest antes de o usar com dados reais.
4. Experimente sempre primeiro com --dry-run.

Script: renomear-faturas · Tarefa: renomear PDFs de faturas com a data e o fornecedor indicados num CSV · Apenas biblioteca padrão.

2. Código (excerto de renomear_faturas.py)

from __future__ import annotations

import argparse
import csv
import logging
import sys
from pathlib import Path

log = logging.getLogger("renomear-faturas")


def novo_nome(data: str, fornecedor: str) -> str:
    """Função pura: '2025-03-14', 'Papelaria Sol' -> '2025-03-14_papelaria-sol.pdf'."""
    return f"{data}_{'-'.join(fornecedor.lower().split())}.pdf"


def ler_csv(caminho: Path) -> dict[str, str]:
    with caminho.open(newline="", encoding="utf-8") as f:
        return {linha["ficheiro"]: novo_nome(linha["data"], linha["fornecedor"]) for linha in csv.DictReader(f)}


def main(argv: list[str] | None = None) -> int:
    p = argparse.ArgumentParser(prog="renomear-faturas", description="Renomeia faturas PDF a partir de um CSV.")
    p.add_argument("pasta", type=Path)
    p.add_argument("csv", type=Path)
    p.add_argument("--dry-run", action="store_true", help="mostra as alterações sem as aplicar")
    nivel = p.add_mutually_exclusive_group()
    nivel.add_argument("-v", "--verbose", action="store_true")
    nivel.add_argument("-q", "--quiet", action="store_true")
    args = p.parse_args(argv)
    logging.basicConfig(level=logging.DEBUG if args.verbose else logging.ERROR if args.quiet else logging.INFO)

    try:
        alteracoes = ler_csv(args.csv)
    except (OSError, KeyError) as e:
        log.error("Não foi possível ler o CSV: %s", e)
        return 2
    for antigo, novo in alteracoes.items():
        origem, destino = args.pasta / antigo, args.pasta / novo
        if not origem.exists() or destino.exists():
            log.warning("Ignorado: %s", antigo)
            continue
        print(f"{antigo} -> {novo}")
        if not args.dry_run:
            origem.rename(destino)
    return 0


if __name__ == "__main__":
    sys.exit(main())

Códigos de saída: 0 sucesso, 1 erro de utilização (o argparse devolve 2 por omissão: [PREENCHER] se os quiser uniformizar), 2 erro nos dados. O formato da data no CSV não foi descrito: [PREENCHER]…