scripts/scraper

🕷️ Web Scraper Avançado

Sistema completo de web scraping para sites complexos, fóruns e Reddit.

Author: Descomplicar® Crescimento Digital Link: https://descomplicar.pt Copyright: 2025 Descomplicar®

---

📋 ÍNDICE

1. Funcionalidades
2. Requisitos
3. Instalação
4. Configuração
5. Uso Básico
6. Uso Avançado
7. Estrutura de Ficheiros
8. Troubleshooting
9. Limitações

---

✨ FUNCIONALIDADES

Core

• ✅ Scraping com Playwright (suporta JavaScript)
• ✅ Conversão HTML → Markdown
• ✅ Limpeza automática de conteúdo
• ✅ Formatação AI opcional (OpenRouter)

Avançado

• ✅ Reddit API oficial (sem violar TOS)
• ✅ Batch processing (múltiplos sites)
• ✅ User-agent rotation
• ✅ Proxy support
• ✅ Rate limiting inteligente
• ✅ Retry logic com backoff exponencial
• ✅ Logging completo

Tipos de Sites Suportados

• 🌐 Sites WordPress
• 💬 Fóruns (vBulletin, phpBB, etc.)
• 🛒 E-commerce (apenas recursos/blog)
• 📰 Sites de notícias
• 📖 Documentação técnica

---

🔧 REQUISITOS

Sistema

• Python 3.8+
• 2GB RAM mínimo
• 5GB espaço livre (para output)

APIs (opcional)

• OpenRouter API (para formatação AI)
• Reddit API (para scraping Reddit)

---

📦 INSTALAÇÃO

1. Clonar/Descarregar

cd /media/ealmeida/Dados/Dev/Scripts/scraper/

2. Criar Virtual Environment

python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# ou
.venv\Scripts\activate  # Windows

3. Instalar Dependências

pip install -r requirements.txt

4. Instalar Browsers Playwright

python -m playwright install chromium

5. Configurar Environment

cp .env.example .env
nano .env  # Editar com tuas credenciais

---

⚙️ CONFIGURAÇÃO

1. Ficheiro .env

# API Keys
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# Reddit API (obter em https://reddit.com/prefs/apps)
REDDIT_CLIENT_ID=your-client-id
REDDIT_CLIENT_SECRET=your-client-secret
REDDIT_USER_AGENT=ScraperBot/1.0 by YourUsername

# Proxy (opcional)
PROXY_USER=username
PROXY_PASS=password

2. Configurar Sites

Edita sites_config.json:

{
  "sites": [
    {
      "name": "Meu Site",
      "url": "https://exemplo.com",
      "type": "wordpress",
      "max_depth": 2,
      "notes": "Descrição opcional"
    }
  ],
  "reddit_subreddits": ["subreddit1", "subreddit2"]
}

Tipos disponíveis:

• wordpress - Sites WordPress
• forum - Fóruns (auto-limitado a depth=1)
• ecommerce - E-commerce (apenas blog/recursos)
• website - Sites genéricos

---

🚀 USO BÁSICO

Opção 1: Batch Scraper (Recomendado)

# Processar TODOS os sites do config
python batch_scraper.py --all

# Apenas WordPress
python batch_scraper.py --types wordpress

# Apenas fóruns
python batch_scraper.py --types forum

# Múltiplos tipos
python batch_scraper.py --types wordpress forum

# Incluir Reddit
python batch_scraper.py --all --include-reddit

# Apenas Reddit
python batch_scraper.py --reddit-only

Opção 2: Scraper Individual

# Editar scraper.py (linha 489)
urls = ["https://meusite.com"]

# Executar
python scraper.py

Opção 3: Reddit Apenas

python reddit_scraper.py

---

🎯 USO AVANÇADO

Pipeline Completo (3 Fases)

Fase 1: Extração

python batch_scraper.py --all

Output: output_md/*.md (raw)

Fase 2: Limpeza

python clean_md.py output_md/ output_cleaned/

Output: output_cleaned/*.md (limpo)

Fase 3: Formatação AI (opcional)

python format_content.py

Output: formatted/*.md (formatado profissionalmente)

Config Personalizado

# Usar config alternativo
python batch_scraper.py --config meu_config.json --all

Filtros Avançados

Edita sites_config.json:

{
  "sites": [
    {
      "name": "Site Complexo",
      "url": "https://exemplo.com",
      "type": "forum",
      "max_depth": 1,
      "excluded_patterns": [
        "/admin/",
        "/private/",
        "/login/"
      ],
      "notes": "Fórum com muitas páginas"
    }
  ]
}

---

📁 ESTRUTURA DE FICHEIROS

scraper/
├── scraper.py              # Scraper principal (Playwright)
├── batch_scraper.py        # Batch processor
├── reddit_scraper.py       # Reddit API scraper
├── clean_md.py             # Limpeza de Markdown
├── format_content.py       # Formatação AI
├── sites_config.json       # Configuração de sites
├── requirements.txt        # Dependências Python
├── .env                    # Credenciais (NÃO commitar)
├── .env.example            # Template de credenciais
├── .gitignore             # Exclusões Git
├── README.md              # Esta documentação
│
├── output_md/             # Output fase 1 (raw)
├── output_cleaned/        # Output fase 2 (limpo)
├── formatted/             # Output fase 3 (formatado)
└── logs/                  # Logs de execução

---

🔍 TROUBLESHOOTING

Erro: "API key not found"

# Verifica .env existe
ls -la .env

# Verifica conteúdo
cat .env

# Se não existe, cria
cp .env.example .env
nano .env

Erro: "playwright not installed"

python -m playwright install chromium

Erro: "Timeout" ao scraping

# Editar scraper.py linha 475
request_timeout=120  # Aumenta para 120s

Site bloqueado (403/429)

# Adicionar proxy em .env
PROXY_USER=username
PROXY_PASS=password

# Ou aumentar politeness_delay
politeness_delay=(5, 10)  # 5-10s entre requests

Reddit: "Invalid credentials"

# Criar app Reddit:
# 1. Vai a https://reddit.com/prefs/apps
# 2. Clica "create app"
# 3. Tipo: "script"
# 4. Redirect URI: http://localhost:8080
# 5. Copia CLIENT_ID e CLIENT_SECRET para .env

Logs não aparecem

# Verifica permissões
ls -la *.log

# Executa com verbose
python batch_scraper.py --all 2>&1 | tee execution.log

---

⚠️ LIMITAÇÕES

Não Funciona Com

• ❌ Sites com Cloudflare aggressive (Challenge)
• ❌ Sites que requerem login obrigatório
• ❌ SPAs React/Vue sem SSR (sem HTML inicial)
• ❌ Sites com CAPTCHA

Limitações de Escala

• Memória: Carrega ficheiros na RAM (problema com ficheiros >100MB)
• Disco: Pode gerar milhares de ficheiros
• API Costs: Formatação AI pode ser cara em volumes grandes

Rate Limits

• Playwright: ~10-20 sites/hora (sites complexos)
• Reddit API: 60 requests/minuto (grátis)
• OpenRouter: Depende do plano

---

📊 PERFORMANCE ESTIMADA

Tipo Site	Páginas/hora	Tempo médio/página
WordPress simples	100-200	30-60s
Fórum	50-100	60-90s
E-commerce	20-50	90-120s
Reddit (API)	1000+	<1s

---

🔐 SEGURANÇA & ÉTICA

Boas Práticas

✅ Respeitar robots.txt ✅ Rate limiting (2-5s entre requests) ✅ User-agent identificável ✅ Não sobrecarregar servidores ✅ Usar APIs oficiais quando disponível (Reddit)

Não Fazer

❌ Scraping agressivo (>1 req/s) ❌ Ignorar rate limits ❌ Scraping de conteúdo protegido por login ❌ Redistribuir conteúdo sem permissão

---

📈 ROADMAP

v2.0 (Próximas melhorias)

• Suporte a mais APIs (Twitter, HackerNews)
• Database storage (SQLite/PostgreSQL)
• Dashboard web (Flask/FastAPI)
• Docker support
• Scraping agendado (cron)
• Detecção automática de mudanças

---

📞 SUPORTE

Issues/Bugs: Criar issue no repositório Dúvidas: contacto@descomplicar.pt Website: https://descomplicar.pt

---

📄 LICENÇA

Copyright 2025 Descomplicar® Crescimento Digital Todos os direitos reservados

---

Última atualização: 2025-11-05 Versão: 2.0