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
86 lines
4.5 KiB
Markdown
86 lines
4.5 KiB
Markdown
# Implementation Plan: Article Content Multi-Engine Extractor
|
|
|
|
**Branch**: `003-article-content-extractor` | **Date**: 2026-08-20 | **Spec**: [spec.md](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/003-article-content-extractor/spec.md)
|
|
|
|
**Input**: Feature specification from `specs/003-article-content-extractor/spec.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Construção do extrator de conteúdo de artigos em lote (`scripts/extract_article_contents.py`), que consome listagens de notícias em JSON, acessa e renderiza as páginas de forma stealth via `foxcape` em modo headless reutilizando sessão de navegador, e executa uma tríplice extração de conteúdo com **Trafilatura**, **Newspaper4k** e **Readability**, salvando o resultado consolidado e higienizado em JSON na pasta `out/`.
|
|
|
|
---
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: Python 3.10+
|
|
**Primary Dependencies**: `foxcape` (Camoufox / stealth scraping), `trafilatura` (artigo e metadados), `newspaper4k` (artigo e NLP), `readability-lxml` (miolo e legibilidade), `beautifulsoup4`, `lxml`
|
|
**Storage**: Arquivos JSON locais no diretório `out/`
|
|
**Testing**: `pytest` com testes unitários e de integração mockando/testando o pipeline
|
|
**Target Platform**: Windows / Linux / macOS (Terminal CLI)
|
|
**Project Type**: CLI tool & modular extraction engine
|
|
**Performance Goals**: Processamento em lote mantendo sessão de navegador ativa (estimativa de 1 a 2 segundos por notícia com DOMContentLoaded)
|
|
**Constraints**: Operação 100% headless, descarte de HTML bruto da memória após extração para conter volume, logs em `stderr`
|
|
**Scale/Scope**: Lotes de 1 a 100+ notícias por execução
|
|
|
|
---
|
|
|
|
## Constitution Check
|
|
|
|
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
|
|
|
| Princípio | Avaliação | Status |
|
|
|---|---|---|
|
|
| **I. Library / Modular Design** | Classes de extração desacopladas por motor (`TrafilaturaExtractor`, `NewspaperExtractor`, `ReadabilityExtractor`). | ✅ Aprovado |
|
|
| **II. CLI Interface** | CLI via `scripts/extract_article_contents.py` com flags descritivas, `stderr` para status e `stdout` para JSON. | ✅ Aprovado |
|
|
| **III. Test-First / Automated Tests** | Testes automatizados cobrindo parsing de JSON, orquestração dos 3 motores e resiliência a falhas de rede. | ✅ Aprovado |
|
|
| **IV. Simplicity & YAGNI** | Uso direto dos módulos especializados existentes sem sobre-engenharia desnecessária. | ✅ Aprovado |
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/003-article-content-extractor/
|
|
├── plan.md # Este plano de implementação
|
|
├── research.md # Decisões técnicas e tradeoffs
|
|
├── data-model.md # Entidades e modelos de dados
|
|
├── quickstart.md # Guia de validação e execução
|
|
├── contracts/
|
|
│ ├── cli-contract.md # Contrato de linha de comando
|
|
│ └── json-schema.md # Esquemas JSON de entrada e saída
|
|
└── checklists/
|
|
└── requirements.md # Checklist de validação da especificação
|
|
```
|
|
|
|
### Source Code Layout
|
|
|
|
```text
|
|
scripts/
|
|
├── extract_google_news.py # Extrator RSS do Google News existente
|
|
└── extract_article_contents.py # [NEW] Extrator e Parser Multimotor de Artigos
|
|
|
|
tests/
|
|
├── test_extract_google_news.py # Testes do extrator Google News existente
|
|
└── test_extract_article_contents.py # [NEW] Testes unitários e de integração do novo extrator
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 0: Outline & Research *(Completed)*
|
|
- Decisões de arquitetura consolidadas em [research.md](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/003-article-content-extractor/research.md).
|
|
- Definição do uso de sessão única de navegador `Foxcape(config=FoxcapeConfig(headless=True))` para aceleração em lote.
|
|
- Definição da estratégia de try/catch em 2 níveis para resiliência máxima.
|
|
|
|
### Phase 1: Design & Contracts *(Completed)*
|
|
- Entidades e contratos definidos em [data-model.md](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/003-article-content-extractor/data-model.md) e [contracts/](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/003-article-content-extractor/contracts/).
|
|
- Guia de execução rápida e validação em [quickstart.md](file:///c:/Users/aferr/Projects/AFTech/DunaMedia/TextNLPClassifierApp/specs/003-article-content-extractor/quickstart.md).
|
|
|
|
### Phase 2: Tasks & Execution *(Completed)*
|
|
- Decomposição das tarefas de implementação em `tasks.md` e execução 100% concluída.
|