Como usar o Ladybug para automação e scraping de dados
O Ladybug é uma biblioteca Python construída sobre Scrapy, então tecnicamente ela herda toda a infraestrutura dele. Muita gente acha que é um framework independente. Não é. Se você já instalou Scrapy, metade do trabalho já está feito. A instalação em si é trivial: pip install scrapy-ladybug. Eu costumo recomendar usar virtualenv ou venv junto porque a dependência do Twisted pode causar conflitos com outras libs no projeto. Depois que você instala, o primeiro erro que quase todo mundo comete é tentar rodar sem configurar o spider corretamente. O comando padrão pra criar o template é ladybug startproject nome_do_projeto pasta_do_projeto. Isso vai gerar a estrutura padrão do Scrapy. A diferença prática aparece quando você começa a definir os seletores CSS nos seus spiders. O Ladybug usa seletores da mesma forma que o Scrapy faria, mas com uma camada extra de utilitários que facilita a navegação em páginas dinâmicas que carregam conteúdo via JavaScript.
o que é ladybug para desenhar fluxos de automação
Aqui tem um ponto que a documentação não deixa claro. O termo "desenhar" não se aplica ao ato visual do código. Se você está procurando um guia de como desenhar uma joaninha (o inseto) para ilustração, esse não é o artigo certo. O que o Ladybug permite fazer é modelar e orquestrar fluxos de extração de dados. A confusão acontece porque alguns tutoriais em português usam "desenhar um scraper" no sentido figurado de projetar a arquitetura da coleta. Fique atento a isso antes de seguir algum tutorial pelo título. Vou direto pro que funciona na prática. Você cria um spider, define os allowed_domains, coloca os selectors no campo css ou xpath, e roda com scrapy crawl nome_do_spider. O que o Ladybug adiciona de real é uma coleção de middlewares prontos para lidar com sessões, cookies persistentes e redirecionamentos complexos. Num projeto real que eu fiz recentemente, eu precisava extrair dados de uma plataforma que fazia validação por token JWT. O Scrapy puro simplesmente batia 401 depois de três requisições. Eu configurei o middleware de sessão do Ladybug para manter o cookie jar entre as chamadas e o problema sumiu. A parte chata é que esse middleware não é habilitado por padrão no settings.py. Você precisa adicionar ele manualmente na lista de DOWNLOADER_MIDDLEWARES.
Outro detalhe importante que as pessoas ignoram é a questão dos rate limits. O Ladybug não resolve mágica. Se você rodar cem requisições seguidas sem delay, seu IP vai cair. O Scrapy já tem o AUTO throttling nativo, mas eu recomendo ajustar manualmente o download delay pros testes. Comece com 2 segundos entre cada requisição. Se o servidor alvo não reclamar, você pode ir diminuindo gradualmente. Isso elimina aquela frustração de passar horas debugando um spider que para de funcionar porque o site bloqueou seu IP por excesso de tráfego.
Configuração básica passo a passo
Crie o projeto com ladybug startproject meu_scraper . Vá até a pasta do projeto e edite o settings.py. Adicione as configurações abaixo, ajustando os valores conforme sua necessidade real. ROBOTSTXT_OBEY = False se você já sabe que pode acessar as páginas. BOT_NAME = 'meu_scraper'. CONCURRENT_REQUESTS = 16 é um bom ponto de partida. Eu geralmente baixo pra 8 quando o target é mais sensível. DOWNLOAD_DELAY = 2. ITEM_PIPELINES = {'scrapy.pipelines.images.ImagesPipeline': 1} se você precisa baixar imagens dos resultados.
Depois crie o spider com ladybug genspider meu_site www.exemplo.com. Abra o arquivo gerado em spiders/meu_site.py. Defina start_urls com a lista de URLs iniciais. No parse, use response.css('seletor').get() para extrair cada campo. Um exemplo realista seria response.css('.preco-produto::text').get(), que pega o texto dentro de uma classe específica. Se a página tiver paginação, você vai precisar fazer uma nova requisição pra próxima página dentro do próprio método parse, usando yield scrapy.Request(next_page_url, callback=self.parse). A parte que gera mais dor de cabeça é quando o site usa lazy loading. O conteúdo não aparece no HTML inicial. Você precisa inspecionar a rede no DevTools do navegador, achar a API que carrega os dados e mirar nela diretamente. Isso evita ter que rodar Selenium ou Puppeteer só pra esperar o carregamento. Eu descobri isso num projeto de monitoramento de preços de e-commerce onde os produtos só apareciam após scroll. A API interna retornava JSON, então eu burlava o front-end completamente e extraía direto do endpoint. Reduziu o tempo de processamento de cada página de cerca de quarenta segundos pra aproximadamente dois.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Erros comuns e como evitar
O erro número um é esquecer de usar get() ou getall() nos seletores. Se você chamar response.css('...') sem nenhum desses métodos, recebe um objeto SelectorList e não o texto em si. O parser vai quebrar silenciosamente ou vai salvar dados incompletos no item. Sempre verifique o tipo do retorno antes de prosseguir. O segundo erro comum é não tratar erros de rede. Se uma requisição falhar, o Scrapy loga mas continua. O problema é que seu pipeline pode receber um item com campos vazios e você só descobre semanas depois. Use o errback nos callbacks ou configure handle_httpstatus_list no spider para capturar os status code que importam.
O terceiro erro que vejo todo dia é construir o spider sem testar os seletores isoladamente. Abra o terminal, importe a response do site que você quer raspar e teste cada seletor CSS antes de colocar no código. Isso economiza horas de depuração. Achei um jeito produtivo de fazer isso usando o IPython com o módulo requests e BeautifulSoup. Carrego a página, aplico os seletores e vejo o resultado na hora, sem rodar o spider inteiro a cada alteração.
Quando não usar o Ladybug
O Ladybug não é solução pra tudo. Se o site alvo depende inteiramente de JavaScript renderizado pelo cliente e não expõe APIs REST, o Scrapy puro e o Ladybug vão te dar trabalho dobrado. Nesse cenário, considere usar Selenium WebDriver ou Playwright. O Playwright é mais rápido e tem suporte nativo pra captura de páginas dinâmicas. Eu tive um caso onde um site de leilões online carregava todos os preços via WebSocket. Consegui extrair os dados interceptando os frames da rede com Playwright, o que seria impraticável apenas com Scrapy. O custo aqui é que scripts com Playwright são mais lentos e consomem mais memória, então o throughput cai drasticamente. Um spider Scrapy puro faz milhares de requisições por minuto. Com Playwright, você conta em dezenas. Outro cenário onde o Ladybug não se adequa bem é quando você precisa de autenticação multifatorial. O fluxo de login com SMS ou app autenticador não se integra naturalmente a um pipeline automatizado. Nesses casos, ou você mantém uma sessão persistente exportada do navegador ou recorre a soluções proprietárias de proxy residencial que já incluem gerenciamento de sessão.
Instalação e dependencies
Além do pip install scrapy-ladybug, certifique-se de ter o Python 3.8 ou superior instalado. A versão do Scrapy recomendada é 2.5+. Versões mais antigas têm bugs conhecidos na manipulação de headers personalizados. Se você estiver no macOS, pode precisar instalar o lxml com brew install libxml2 libxslt. No Windows, geralmente o Wheels já vêm compilados, mas as versões do Twisted às vezes dão problema. Se o pip falhar na instalação do Twisted, baixe o arquivo wheel diretamente do site do autor e instale offline. Eu também recomendo manter um requirements.txt versionado. A versão do Scrapy evolui rápido e uma atualização não testada pode quebrar middleware que depende de APIs internas. Num projeto que eu mantinha, a atualização do Scrapy de 2.5 pra 2.11 quebrou um middleware de retry que eu tinha adaptado. Levei duas horas pra identificar e corrigir porque a mensagem de erro era genérica demais.
Boas práticas finais
Use nomes de campos claros nos seus items. data_produto, preco_unitario, disponibilidade. Evite atalhos como a, b, c porque quando o scraper cresce pra cinquenta campos, você não lembra o que significa cada um. Faça parse dos dados em formato estruturado e salve em JSON ou CSV separado por tipo de produto. Deixe o pipeline lidar com a conversão final. Isso permite reprocessar os dados sem precisar refazer o scraping. Mantenha os logs detalhados mas sem exagerar. O log padrão do Scrapy já mostra requisições, respostas e erros. Adicione logs customizados apenas para eventos que acontecem raramente, como falhas de timeout ou redirecionamentos em cadeia. Logar cada item processado enche o arquivo em minutos e dificulta encontrar o que importa de verdade.
Sempre respeite os termos de uso do site alvo. Isso parece óbvio mas é o que mais gera problemas. Alguns sites têm cláusulas explícitas contra scraping. Outros permitem desde que você não sobrecarregue o servidor. Um site que eu monitorava semanalmente mudou a política sem aviso e bloqueou faixas inteiras de IP. Perdi uns três dias ajustando proxies rotate quando teria sido mais simples enviar um e-mail pedindo acesso à API deles. Muitos sites oferecem APIs oficiais para parceiros. Vale sempre verificar antes de construir um scraper do zero.
