feat(extractor): add Google News headlines extractor with Foxcape headless and URL resolution
- Add standalone CLI script scripts/extract_google_news.py for Google News RSS scraping - Integrate foxcape in headless mode as primary stealth anti-bot engine - Implement parallel article URL resolution using googlenewsdecoder and ThreadPoolExecutor - Support language and regional locale mapping (-l, --lang, --locale) - Implement real-time progress logging in stderr and --silent flag - Add unit, integration, and live E2E tests in tests/test_extract_google_news.py - Add full SpecKit documentation (specs/002-google-news-extractor/) - Create comprehensive README.md covering both NLP Classifier and Google News Extractor
This commit is contained in:
@@ -0,0 +1,78 @@
|
||||
# Quickstart: Google News Headlines Extractor
|
||||
|
||||
Guia rápido para execução e validação de ponta a ponta do extrator de notícias via linha de comando.
|
||||
|
||||
---
|
||||
|
||||
## 1. Pré-requisitos e Instalação
|
||||
|
||||
Instale as dependências necessárias no ambiente Python:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
Baixe os binários de browser stealth do Camoufox (executado uma única vez):
|
||||
```bash
|
||||
python -m camoufox fetch
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Cenários Práticos de Uso
|
||||
|
||||
### Cenário 1: River Plate — Argentina (Espanhol / 2 Páginas / Salvar em Arquivo)
|
||||
```bash
|
||||
python scripts/extract_google_news.py -q "River Plate" -l es --locale AR -p 2 -o out/river_plate.json
|
||||
```
|
||||
* **Logs no terminal**:
|
||||
```text
|
||||
[INFO] 🔍 Consultando Google News: 'River Plate' (idioma: es, locale: AR, max_pages: 2)...
|
||||
[INFO] 📥 Feed RSS recebido (162117 bytes).
|
||||
[INFO] 📰 20 artigos extraídos do feed XML.
|
||||
[INFO] 🔗 Decodificando 20 URLs do Google News para os portais reais...
|
||||
[INFO] ✅ 20/20 URLs resolvidas com sucesso para os domínios de origem.
|
||||
[INFO] 💾 Arquivo salvo com sucesso: 'out/river_plate.json' (20 notícias).
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cenário 2: Cruzeiro — Brasil (Português / Formatado no Terminal)
|
||||
```bash
|
||||
python scripts/extract_google_news.py --query "Cruzeiro" --lang pt --locale BR --pretty
|
||||
```
|
||||
* Retorna JSON formatado com 10 manchetes e links diretos (*ge.globo.com, lance.com.br, gazetaesportiva.com*).
|
||||
|
||||
---
|
||||
|
||||
### Cenário 3: Fórmula 1 — Reino Unido (Inglês)
|
||||
```bash
|
||||
python scripts/extract_google_news.py --query "Formula 1" --lang en --locale GB --pretty
|
||||
```
|
||||
* Retorna notícias de veículos britânicos (*BBC Sport, Sky Sports F1, Autosport*).
|
||||
|
||||
---
|
||||
|
||||
### Cenário 4: Integração em Pipeline com `jq` (Modo Silencioso)
|
||||
```bash
|
||||
python scripts/extract_google_news.py -q "inteligência artificial" -s | jq '.items[].url'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Cenário 5: Extração Rápida com Links Brutos (Sem Resolução de URLs)
|
||||
```bash
|
||||
python scripts/extract_google_news.py -q "São Paulo" --no-resolve-urls --pretty
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Validação dos Testes Automatizados e Linter
|
||||
|
||||
```bash
|
||||
# Executa todos os testes unitários e E2E ao vivo
|
||||
pytest tests/test_extract_google_news.py -v
|
||||
|
||||
# Validação estática com Ruff e Mypy
|
||||
ruff check scripts/extract_google_news.py tests/test_extract_google_news.py
|
||||
mypy scripts/ tests/test_extract_google_news.py
|
||||
```
|
||||
Reference in New Issue
Block a user