TextNLPClassifierApp/specs/002-google-news-extractor/plan.md

Implementation Plan: Google News Headlines Extractor

Branch: 002-google-news-extractor | Date: 2026-08-20 | Spec: spec.md

Input: Feature specification from specs/002-google-news-extractor/spec.md

Summary

Implementar um script CLI Python simples, robusto e autônomo (scripts/extract_google_news.py) para extrair manchetes do Google News RSS por assunto, idioma e região geográfica (locale). A solução utiliza a biblioteca foxcape em modo headless=True para garantir evasão anti-bot stealth, a biblioteca googlenewsdecoder para resolver automaticamente as URLs intermediárias para os links finais dos portais de notícias em paralelo (ThreadPoolExecutor), e logging em tempo real via sys.stderr.

Technical Context

Language/Version: Python >= 3.10 (3.11 / 3.12 / 3.13 / 3.14)
Primary Dependencies:

• foxcape>=0.1.1 (scraping stealth & evasão anti-bot Camoufox em modo headless)
• googlenewsdecoder>=0.1.7 (decodificação de URLs intermediárias do Google News)
• selectolax>=0.3.27 (parser ultra-rápido de nós e atributos)
• beautifulsoup4>=4.12.0 (limpeza HTML e higienização de resumos/snippets)
• argparse (parser CLI na biblioteca padrão)
• concurrent.futures (resolução paralela em pool de threads)

Storage: N/A (stateless; saída via stdout ou arquivo especificado por flag -o / --output)
Testing: pytest com fixtures de feeds RSS, testes unitários mockados e testes End-to-End (E2E) ao vivo
Target Platform: Multiplataforma (Windows / Linux / macOS)
Project Type: Standalone CLI script + módulo utilitário de scripts
Constraints: Separação estrita de streams (stdout para JSON e stderr para logs informativos/erros)

Architecture & Pipeline

flowchart LR
    A[SearchQuery CLI] --> B[Foxcape Headless Fetch]
    B --> C[parse_google_news_rss XML/HTML]
    C --> D[ThreadPoolExecutor URL Resolution]
    D --> E[ExtractionResult JSON Output]
    E --> F[stdout / File Output]

1. Ingestão & Validação: SearchQuery valida palavra-chave não-vazia, idioma e limites de páginas (1 a 10).
2. Coleta RSS via Foxcape: Foxcape.fetch(url, config=FoxcapeConfig(headless=True)) busca o feed com evasões anti-bot.
3. Higienização XML/HTML: parse_google_news_rss extrai nós, limpa resumos com BeautifulSoup e deduplica subtítulos redundantes.
4. Decodificação de Links: resolve_articles_urls decodifica as URLs intermediárias do Google News em paralelo via googlenewsdecoder.
5. Emissão Estruturada: JSON formatado no stdout ou gravado em arquivo (--output).

Project Structure

Documentation (this feature)

specs/002-google-news-extractor/
├── spec.md              # Especificação de requisitos da feature
├── plan.md              # Este plano de implementação
├── research.md          # Pesquisa técnica e decisões de design
├── data-model.md        # Entidades, DTOs e esquema JSON
├── contracts/
│   └── cli_contract.md  # Contrato de argumentos CLI e I/O streams
├── quickstart.md        # Guia rápido de execução e validação
└── checklists/
    ├── requirements.md  # Checklist de qualidade dos requisitos
    └── readiness.md     # Checklist de prontidão e completude

Source Code

scripts/
├── __init__.py                # Identificador de pacote Python
└── extract_google_news.py     # Script CLI principal e lógica de extração

tests/
├── fixtures/
│   └── google_news_sample.xml # Amostra de feed RSS para testes offline
└── test_extract_google_news.py# Testes unitários, integração e E2E ao vivo