selectolax Web Scraping: Análise Rápida de HTML em Python

TL;DR:

• selectolax analisa HTML com seletores CSS e faz isso rapidamente, pois utiliza o mecanismo Lexbor baseado em C em vez de análise puramente em Python.
• O que selectolax não faz é buscar. Ele não possui um cliente HTTP e não renderiza JavaScript; basta passar bytes e ele os analisa, nada mais.
• A lacuna aparece em um script. Um simples GET em uma página de demonstração renderizada em JavaScript dá a selectolax 0 nós de citação; a mesma URL acessada através da API Universal Scraping do Scrapeless com js_render dá a ela todas as 10.
• A análise é real neste guia. Uma execução ao vivo extraiu todas as 10 citações com autores e arrays de tags intactas do HTML renderizado, usando css e css_first.
• As duas camadas estão claramente separadas. O Scrapeless busca e renderiza; o selectolax transforma os bytes em registros. Nenhum deles interfere no trabalho do outro.
• Gratuito para começar do lado da busca. Crie sua chave API do Scrapeless em app.scrapeless.com.

O que é selectolax e o que não é

selectolax é um analisador HTML em Python construído para velocidade. Ele se conecta ao mecanismo Lexbor, uma biblioteca em C que implementa o padrão HTML, de modo que a análise de um documento e a execução de seletores CSS aconteçam em código compilado em vez de no interpretador. Para extrações de alto volume - milhares de páginas, loops apertados - essa diferença é a razão pela qual as pessoas optam por ele em vez de analisadores mais pesados.

Ele é um analisador e apenas um analisador. O selectolax não possui cliente HTTP, não mantém sessão e não executa JavaScript. Dê-lhe uma string ou bytes e ele constrói uma árvore que você pode consultar; peça-lhe para acessar uma URL e não há método para isso, por design. Assim, cada configuração de "raspagem web com selectolax" é composta por duas camadas: algo que busca HTML fiel, e o selectolax que o transforma em dados. Este guia usa a API Universal Scraping do Scrapeless para a primeira camada, porque um cliente HTTP simples retorna os bytes errados em qualquer página que constrói seu conteúdo com JavaScript. Para uma visão mais ampla do lado Python, o tutorial de raspagem web em Python abrange o ecossistema ao redor disso.

Instalar

selectolax e requests são toda a cadeia de ferramentas. A versão contra a qual este guia foi escrito é selectolax 0.4.11:

pip install "selectolax==0.4.11" requests

Mantenha sua chave no ambiente, nunca no código-fonte:

export SCRAPELESS_API_KEY="sk_your_scrapeless_key"

Obter HTML que vale a pena analisar

A qualidade da análise é limitada pela fidelidade da busca, então comece por aí. Em uma página renderizada em JavaScript, o documento que um cliente HTTP simples recebe não é o documento que um leitor vê: o conteúdo chega apenas após os scripts construírem o DOM, um ciclo de vida definido pela especificação de scripting HTML. Um script contabiliza a diferença através do selectolax:

# fidelity.py — o que selectolax vê: GET simples vs renderização do lado do servidor
import os

import requests
from selectolax.lexbor import LexborHTMLParser

URL = "https://quotes.toscrape.com/js/"

plain = requests.get(URL, timeout=60).text
print("caracteres GET simples:", len(plain), "| nós de citação:", len(LexborHTMLParser(plain).css("div.quote")))

resp = requests.post(
    "https://api.scrapeless.com/api/v2/unlocker/request",
    headers={"Content-Type": "application/json", "x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    json={"actor": "unlocker.webunlocker", "input": {"url": URL, "js_render": True}},
    timeout=120,
)
resp.raise_for_status()
rendered = resp.json().get("data", "")
print("caracteres renderizados:", len(rendered), "| nós de citação:", len(LexborHTMLParser(rendered).css("div.quote")))

A execução imprime 0 nós de citação para a busca simples e 10 para a renderizada:

caracteres GET simples: 5806 | nós de citação: 0
caracteres renderizados: 8940 | nós de citação: 10

Renderização, desbloqueio e roteamento proxy acontecem todos do lado do servidor nesse único POST — a API Universal Scraping é a camada de busca, e os bytes renderizados são o que selectolax deve analisar.

Análise com selectolax

Com o HTML real em mãos, selectolax faz a extração. css retorna cada nó que corresponde a um seletor; css_first retorna o primeiro, para que você possa extrair um campo de cada registro. Os seletores seguem a especificação de Seletores W3C, a mesma sintaxe que você já usa em CSS:

# extract.py — busque a página renderizada e depois extraia registros com selectolax
import os

import requests
from selectolax.lexbor import LexborHTMLParser

resp = requests.post(
    "https://api.scrapeless.com/api/v2/unlocker/request",

headers={"Content-Type": "application/json", "x-api-token": os.environ["SCRAPELESS_API_KEY"]},
    json={"actor": "unlocker.webunlocker", "input": {"url": "https://quotes.toscrape.com/js/", "js_render": True}},
    timeout=120,
)
resp.raise_for_status()
tree = LexborHTMLParser(resp.json().get("data", ""))

records = []
for quote in tree.css("div.quote"):
    records.append({
        "text": quote.css_first("span.text").text(),
        "author": quote.css_first("small.author").text(),
        "tags": [tag.text() for tag in quote.css("a.tag")],
    })

print("registros:", len(records))
print("primeiro autor:", records[0]["author"])
print("primeiras tags:", records[0]["tags"])

A execução ao vivo retornou todos os 10 registros, com o autor e a matriz de tags intactos no primeiro:

registros: 10
primeiro autor: Albert Einstein
primeiras tags: ['mudança', 'pensamentos profundos', 'pensando', 'mundo']

Esse é o scraper inteiro: um POST para buscar e renderizar, uma árvore para consultar. text() retorna o conteúdo de texto de um nó, e construir uma lista de dicionários por registro é o padrão que se escala para qualquer bloco repetido em uma página.

Obtenha sua chave de API no plano gratuito: app.scrapeless.com

Padrões avançados

• Use LexborHTMLParser para velocidade, HTMLParser para o backend Modest. selectolax transporta ambos os mecanismos por trás da mesma API; Lexbor é o mais novo, mais rápido e o padrão certo para volume.
• Prefira css_first com um default. node.css_first("span.text", default=None) retorna None em vez de levantar uma exceção quando um campo está faltando, o que evita que um loop sobre registros desiguais travasse na única página que difere.
• Leia atributos com .attributes. Para links e imagens, node.attributes.get("href") obtém o atributo do nó — seletores encontram o elemento, .attributes lê seus dados.
• Busque markdown quando você não precisa da árvore. Se você só quer texto legível, a API Scrapeless pode retornar conteúdo renderizado diretamente; recorra ao selectolax quando precisar de controle a nível de seletor sobre campos estruturados.

Resolução de problemas

• Zero nós de uma página que você pode ver em um navegador. O conteúdo é renderizado em JavaScript e sua busca retornou o HTML pré-renderizado. Conte um seletor conhecido da maneira como o primeiro script faz; uma árvore quase vazia é um problema de busca, corrigido com js_render, não um problema de seletor.
• AttributeError: 'NoneType' object has no attribute 'text'. Um css_first não encontrou nada e você chamou .text() em None. Passe default=None e verifique antes de ler, ou confirme se o seletor corresponde à marcação renderizada.
• O texto tem espaço em branco extra. text() retorna o texto bruto do nó; chame .strip() ou passe opções deep=True/separator quando um nó aninha filhos cujo texto você quer juntar.
• A codificação parece errada. Passe os bytes da resposta em vez de uma string mal decodificada; selectolax lê a codificação declarada do documento quando você fornece bytes.

Conclusão

selectolax ganha seu lugar como a camada de análise que nunca toca a rede: entrega HTML fiel e retorna registros rapidamente, com seletores CSS que você já conhece. A camada que decide se tudo isso é possível é a busca — a contagem 0 versus 10 do primeiro script resolve isso — e um POST renderizado no servidor fecha a lacuna. Conecte os dois e as dez citações da página de demonstração chegam como dicionários limpos, tags e tudo.

Crie uma conta gratuita no Scrapeless para obter uma chave de API, e a documentação para desenvolvedores cobre os parâmetros unlocker.webunlocker. Verifique preços do Scrapeless quando planejar um trabalho recorrente.

FAQ

Q: O selectolax pode scrapear sites por conta própria?

Não. O selectolax analisa HTML que você já possui; não possui um cliente HTTP e não renderiza JavaScript. Combine-o com uma camada de busca — aqui, a API de Scraping Universal Scrapeless, que renderiza a página no lado do servidor — e o selectolax lida com a extração dos bytes retornados.

Q: Por que usar selectolax em vez de BeautifulSoup?

Velocidade. O selectolax envolve o mecanismo Lexbor baseado em C, então a análise e as consultas de seletor são executadas em código compilado, o que importa em alto volume de páginas. A troca é uma superfície de recursos menor; para extração baseada em seletores em muitas páginas, essa geralmente é a troca certa.

Q: Qual é a diferença entre css e css_first?

`css` retorna uma lista de todos os nós que correspondem ao seletor; `css_first` retorna apenas a primeira correspondência (ou um `padrão` que você fornecer). Use `css` para percorrer blocos repetidos, como resultados de pesquisa, e `css_first` para extrair um único campo de cada bloco.

**Q: O selectolax lida com páginas renderizadas por JavaScript?**

Não por si só — ele nunca executa scripts. Se o conteúdo carregar após o HTML inicial, um fetch simples entrega ao selectolax uma árvore vazia. Busque a página através da API Scrapeless com `js_render` primeiro, depois analise o HTML renderizado, como este guia faz.

**Q: É legal fazer scraping com selectolax?**

O parser não muda as regras de coleta. Busque apenas páginas públicas, respeite os termos do site e as diretrizes de robôs padronizadas pelo <a href="https://datatracker.ietf.org/doc/html/rfc9309" rel="nofollow"><strong>Protocolo de Exclusão de Robôs</strong></a>, mantenha os volumes limitados e trate quaisquer dados pessoais de acordo com as leis que se aplicam a você.