Sombras Do Sul

O que realmente é e como funciona na prática

Sombras do Sul é uma ferramenta de automação e coleta de dados que ganhou tração no Brasil por volta de 2022-2023. A proposta central é permitir que pesquisadores e analistas baixem conjuntos de dados públicos de forma programática, sem precisar depender de APIs oficiais ou scrapear manualmente cada página envolvida. O projeto foi construído originalmente como um wrapper em Python sobre rotinas de scrape, mas evoluiu para suportar múltiplas fontes: tribunais, câmaras municipais, diários oficiais, portais de transparência. A diferença em relação a escrever um scraper do zero é que o pacote já traz um sistema de caching, retry com backoff exponencial e rate limiting embutido, o que elimina a maior parte da dor de cabeça operacional.

Instalação e primeiro contato com sombras do sul

A instalação é padrão pip: pip install sombras-do-sul. Depois disso, o fluxo mais comum começa assim: Primeiro você importa o módulo e inicializa um cliente com os parâmetros básicos. Depois define a fonte de dados que quer consultar — digamos, um diário oficial de uma cidade específica — e roda a consulta. O pacote devolve um objeto pandas ou um JSON, dependendo da configuração.

O que muita gente não percebe na documentação oficial é que o cache por padrão fica em memória durante a execução do processo. Se você está rodando um job que leva horas e quer persistência entre rodadas, precisa configurar o path do cache explicitamente via argumento no construtor do cliente. Sem isso, cada reinício do script faz todas as requisições do zero. Eu perdi meio dia tentando entender por que meu pipeline demorava 40 minutos em vez dos 6 que levava na primeira execução, até perceber que o cache não estava sendo persistido em disco.

Limitações que ninguém menciona nos tutoriais

A principal restrição do Sombras do Sul é que ele depende inteiramente da estrutura das páginas públicas que consome. Quando um portal governo muda o layout, quebra a seleção CSS, ou implementa Cloudflare ou outro sistema anti-bot, o pacote para de funcionar naquele endpoint específico. Não há muito o que fazer além de esperar a correção ou ajustar manualmente o seletor. Outro problema real é a falta de suporte a autenticação. Muitas fontes exigem login ou cookie session. O pacote não lida com sessões persistentes fora do que é estritamente necessário para a requisição em si. Se você precisa operar com dados que exigem credenciais, terá que fazer um workaround com requests.session antes de passar para o cliente do Sombras do Sul.

Existe ainda o limite de taxa imposto pelos servidores públicos. Mesmo com o rate limiting embutido, alguns domínios são mais agressivos. No meu caso, ao tentar extrair anos de diários oficiais de uma capital do Nordeste, o servidor bloqueou o IP após cerca de 800 requisições consecutivas. A solução foi configurar o intervalo entre requisições para 3 segundos e adicionar um pause aleatório de até 5 segundos, o que reduziu a velocidade mas manteve o IP ativo por semanas sem novo bloqueio.

Cenários onde a ferramenta realmente compensa

O uso mais eficiente do Sombras do Sul é para consultas recorrentes em fontes estáveis. Se você precisa acompanhar mensalmente as licitações de uma secretaria ou monitorar contratos de um município ao longo de dois anos, o pacote paga o esforço de setup rapidamente. O tempo de coleta cai de algo em torno de 2 horas de scraping manual para cerca de 15 minutos com o wrapper pronto. Para análises pontuais de uma única fonte, vale a pena dar uma olhada, mas se o volume for grande e a fonte instável, o ganho desaparece. Nesses casos, construir um scraper dedicado com Playwright ou Selenium pode ser mais produtivo a longo prazo, apesar do custo inicial maior.

O projeto também tem uma comunidade ativa no GitHub onde issues de quebras de seletores são relatadas e corrigidas com frequência. Fica de olho nas issues abertas se a fonte que você quer usar aparecer lá como problemática. Às vezes a correção já está em pull request e só precisa ser mergesada.