andreferraro
6a45368cb0
- Added scripts/extract_article_contents.py for batch scraping with stealth Foxcape and triple extraction (Trafilatura, Newspaper4k, Readability) - Created unit, integration, and E2E test suite in tests/test_extract_article_contents.py (90/90 passing) - Updated specs/003-article-content-extractor and README.md with usage documentation and CLI contracts - Passed ruff linting/formatting and mypy type checking cleanly
48 lines
2.4 KiB
Markdown
48 lines
2.4 KiB
Markdown
# CLI Contract: Article Content Multi-Engine Extractor
|
|
|
|
## 1. Comando de Execução
|
|
|
|
```bash
|
|
python scripts/extract_article_contents.py [OPTIONS]
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Argumentos e Flags
|
|
|
|
| Flag Curta | Flag Longa | Tipo | Obrigatório | Padrão | Descrição |
|
|
|---|---|---|---|---|---|
|
|
| `-i` | `--input` | String (Path) | **Sim** | — | Caminho para o arquivo JSON de entrada (ex: `out/river_plate.json`). |
|
|
| `-o` | `--output` | String (Path) | Não | `<input_stem>_extracted.json` | Caminho do arquivo JSON de destino. Se omitido, salva no mesmo diretório com sufixo `_extracted.json`. |
|
|
| `-l` | `--limit` | Inteiro | Não | Todos | Limita a quantidade máxima de artigos a serem processados (útil para amostragem/testes). |
|
|
| `--lang` | `--language` | String | Não | Do JSON / `"en"` | Sobrescreve o código de idioma para o módulo de NLP do Newspaper4k (ex: `pt`, `es`, `en`). |
|
|
| `-t` | `--timeout` | Inteiro | Não | `30` | Timeout em segundos para o carregamento do DOM de cada página no Foxcape. |
|
|
| `-s` | `--silent` | Flag booleana | Não | `False` | Suprime mensagens visuais de progresso e logs em `stderr`. |
|
|
| `-h` | `--help` | Flag booleana | Não | `False` | Exibe manual de ajuda com todos os parâmetros disponíveis. |
|
|
|
|
---
|
|
|
|
## 3. Códigos de Saída (Exit Codes)
|
|
|
|
| Código | Significado | Condição |
|
|
|---|---|---|
|
|
| `0` | **Sucesso** | Execução concluída e arquivo JSON de saída gravado com êxito (mesmo que artigos individuais tenham falhado). |
|
|
| `1` | **Erro de Argumento** | Arquivo de entrada inexistente, formato inválido ou parâmetros numéricos fora dos limites. |
|
|
| `2` | **Erro de Inicialização** | Falha ao inicializar o motor Foxcape/navegador headless ou falta de dependências essenciais. |
|
|
|
|
---
|
|
|
|
## 4. Comportamento de Streams (I/O)
|
|
|
|
- **`stderr`**: Recebe mensagens de status informativas em tempo real:
|
|
```text
|
|
[INFO] 🚀 Iniciando extração de 10 artigos a partir de 'out/river_plate.json'
|
|
[INFO] 🌐 [1/10] Foxcape navegando: https://www.tycsports.com/...
|
|
[INFO] ⚙️ [1/10] Extraindo dados (Trafilatura, Newspaper4k, Readability)...
|
|
[INFO] ✅ [1/10] Sucesso (Título: "Los puntajes de River...")
|
|
...
|
|
[INFO] 💾 Relatório final gravado com sucesso em: 'out/river_plate_extracted.json'
|
|
[INFO] 📊 Resumo: 10 total | 10 sucessos | 0 falhas | Tempo: 14.2s
|
|
```
|
|
- **`stdout`**: Mantém-se silencioso se `--output` for fornecido (ou padrão), ou emite o JSON final caso o usuário redirecione a saída explicitamente.
|