Uma classe TwitterSearcher para pesquisa REST agressiva do Twitter usando birdy

Eu realmente tenho gostado do birdy para o consumo da API do Twitter, principalmente por sua simplicidade. Mas, não é sem suas peculiaridades – algumas decorrentes da biblioteca de solicitações, algumas do tratamento de erros do birdy e algumas da própria API do Twitter.

Seja com o birdy ou qualquer outra biblioteca cliente da API do Twitter, parece que estou sempre escrevendo um monte de scaffolding para gerenciar o limite de taxa da API de pesquisa, paginação etc. Esta essência é uma tentativa de resolver esse tratamento de uma vez por todas, como bem como lidar com as peculiaridades que encontrei ao usar a API REST do Twitter em geral.

A classe é TwitterSearcher. Requer birdy e delorean. A essência está aqui: https://gist.github.com/scott2b/9219919

O uso dos cabeçalhos de resposta da API do Twitter para gerenciar a limitação de taxa elimina a necessidade de calcular atrasos e controlar suas consultas – mas espere que suas consultas atrasem se você estiver fazendo pesquisas agressivas.

Da forma como está, ele usa autenticação no nível do aplicativo. Deve ser fácil modificar a classe para lidar com a autenticação do usuário (resultando em menos taxa de transferência para uma determinada instância do pesquisador, devido às restrições da API).

O uso se parece com isto:

searcher = TwitterSearcher(
    TWITTER_CONSUMER_KEY,
    TWITTER_CONSUMER_SECRET,
    TWITTER_APP_CLIENT_ACCESS_TOKEN)
for query in my_query_generator():
    searcher.paginated_search(
        page_handler=my_page_handler,
        # see birdy AppClient docs and Twitter API docs for params
        # to pass in here:
        since_id=my_since_id,
        q=query,
        count=100,
        lang='en'
    )

O TwitterSearcher emitirá buscas (e paginações) tão rapidamente quanto você as chamar – até que o limite da taxa seja atingido, momento em que ele aguardará o tempo especificado pelo Twitter e então começará a agitar novamente.

Usa o tempo do cabeçalho fornecido pelo Twitter para evitar problemas de tempo fora de sincronia. Lida com o estranho problema de pool de conexão que as solicitações não se propagam corretamente – reconectando quando um TwitterClientError corresponde à string “HTTPSConnectionPool”. Paginará até quantas páginas fornecidas para a instância (default_max_pages) ou para o método paginated_search (max_pages). Passe em um page_handler que pode ser chamado para realmente fazer algo com respostas paginadas.