Snippets da Biblioteca Requests Python

1 Introdução às Requisições em Python

A biblioteca requests é o cliente HTTP elegante do Python que faz com que as chamadas de API pareçam naturais. Ela abstrai os detalhes complicados do HTTP, mantendo o poder sob o capô. Pense nela como seu mensageiro confiável para a internet — lida com tudo, desde simples buscas de páginas até fluxos de autenticação complexos.

Por que os desenvolvedores a adoram:

Amigável ao ser humano: A API é lida como inglês simples em vez de jargão críptico de HTTP.
JSON embutido: Análise automática elimina a necessidade de código repetitivo para análise.
Suporte a sessão: Mantém cookies e pool de conexões para você automaticamente.
Tratamento robusto de erros: Exceções claras em vez de códigos de status crípticos.
Verificação SSL: Seguro por padrão, flexível quando necessário.

Pronto para buscar alguns dados? Vamos começar com o básico.

2 Pré-requisitos: Python & Pip

Você precisará do Python 3.6+ e do pip para instalar a biblioteca requests. Vamos verificar sua configuração:

python --version && pip --version

Se esses comandos funcionarem, você está pronto. Caso contrário, baixe o Python de python.org e o pip virá junto.

3 Instale a Biblioteca Requests

Primeiro, vamos criar um ambiente virtual novo — isso mantém suas dependências de projeto limpas e evita conflitos de versão:

python -m venv .venv && source .venv/bin/activate  # macOS/Linux
# ou
python -m venv .venv && .venv\Scripts\activate  # Windows

Agora, instale o requests usando pip:

pip install requests

4 Sua Primeira Requisição GET

Vamos começar com a operação mais comum — buscar dados. Este snippet simples obtém uma resposta JSON de uma API pública:

import requests

response = requests.get('https://httpbin.org/json')
print(f"Status: {response.status_code}")
print(f"Content-Type: {response.headers['content-type']}")

# Análise automática de JSON
data = response.json()
print(f"Chaves: {list(data.keys())}")

Note a análise automática de JSON — requests detecta o tipo de conteúdo e o analisa para você. Nenhuma dança manual de json.loads() é necessária.

5 Requisições POST com Dados

Enviando dados para um servidor? Requisições POST lidam com dados de formulário, JSON e arquivos de forma transparente. Aqui estão os padrões comuns:

import requests

# Enviar dados de formulário
form_data = {'username': 'alice', 'password': 'secret123'}
response = requests.post('https://httpbin.org/post', data=form_data)

# Enviar dados JSON (define automaticamente o cabeçalho Content-Type)
json_data = {'name': 'Alice', 'email': '[email protected]'}
response = requests.post('https://httpbin.org/post', json=json_data)

print(f"Status: {response.status_code}")
print(f"Resposta: {response.json()}")

O parâmetro json define automaticamente os cabeçalhos corretos e serializa seus dados. Muito mais limpo do que definir cabeçalhos manualmente.

6 Cabeçalhos Personalizados e Autenticação

As APIs frequentemente precisam de cabeçalhos personalizados e autenticação. Requests torna isso simples com classes de autenticação embutidas:

import requests
from requests.auth import HTTPBasicAuth, HTTPDigestAuth

# Cabeçalhos personalizados
headers = {
    'User-Agent': 'MyApp/1.0',
    'Accept': 'application/json',
    'X-API-Key': 'sua-chave-de-api-aqui'
}

response = requests.get('https://httpbin.org/headers', headers=headers)
print(response.json())

# Autenticação Básica
auth = HTTPBasicAuth('username', 'password')
response = requests.get('https://httpbin.org/basic-auth/user/pass', auth=auth)

# Chave de API no cabeçalho
api_key = 'sk-1234567890abcdef'
headers = {'Authorization': f'Bearer {api_key}'}
response = requests.get('https://httpbin.org/bearer', headers=headers)

HTTPBasicAuth e HTTPDigestAuth lidam com a codificação automaticamente. Para APIs modernas, tokens Bearer no cabeçalho Authorization são o padrão.

7 Tratamento de Erros e Códigos de Status

Aplicações robustas lidam com erros de forma graciosa. Requests lança exceções para problemas de rede e fornece objetos de resposta detalhados:

import requests
from requests.exceptions import RequestException, Timeout, ConnectionError

try:
    response = requests.get('https://httpbin.org/status/404', timeout=5)
    
    # Lança uma exceção para códigos de status ruins
    response.raise_for_status()
    
except Timeout:
    print("Requisição expirou após 5 segundos")
except ConnectionError:
    print("Falha ao conectar ao servidor")
except RequestException as e:
    print(f"Falha na requisição: {e}")
    
else:
    print(f"Sucesso! Status: {response.status_code}")
    print(f"Cabeçalhos: {response.headers}")
    print(f"Corpo: {response.text[:100]}...")  # Primeiros 100 caracteres
    
# Verificação manual do código de status
if response.status_code == 200:
    data = response.json()
    print("Dados recebidos:", data)
elif response.status_code == 404:
    print("Recurso não encontrado")
else:
    print(f"Status inesperado: {response.status_code}")

raise_for_status() lança um HTTPError para respostas 4xx/5xx. Timeouts impedem que seu aplicativo trave indefinidamente.

8 Processamento JSON e Manipulação de Dados

Trabalhar com dados JSON de forma eficiente é onde requests se destaca. Ele lida com codificação, decodificação e validação automaticamente:

import requests

# Tratamento complexo de JSON
response = requests.get('https://httpbin.org/json')

# Análise segura de JSON com tratamento de erros
try:
    data = response.json()
    print(f"Tipo: {type(data)}")
    print(f"Chaves: {data.keys() if isinstance(data, dict) else 'Não é um dict'}")
except ValueError as e:
    print(f"JSON inválido: {e}")
    print(f"Conteúdo bruto: {response.text}")

# Trabalhando com dados aninhados
user_data = {
    'name': 'Alice Johnson',
    'email': '[email protected]',
    'preferences': {
        'theme': 'dark',
        'notifications': True,
        'language': 'en'
    }
}

# Enviar JSON aninhado complexo
response = requests.post('https://httpbin.org/post', json=user_data)
result = response.json()

# Acessar valores aninhados
nested = result.get('json', {}).get('preferences', {})
theme = nested.get('theme', 'light')
print(f"Tema do usuário: {theme}")

Sempre use métodos seguros como get() ao acessar JSON aninhado para evitar exceções KeyError.

9 Downloads de Arquivos e Streaming

Baixar arquivos de forma eficiente evita problemas de memória. Use streaming para arquivos grandes e verifique o tipo de conteúdo:

import requests
import os
from pathlib import Path

# Baixar um arquivo
url = 'https://httpbin.org/image/jpeg'
response = requests.get(url, stream=True)

if response.status_code == 200:
    # Criar diretório de downloads
    downloads_dir = Path('downloads')
    downloads_dir.mkdir(exist_ok=True)
    
    # Salvar arquivo
    file_path = downloads_dir / 'image.jpg'
    with open(file_path, 'wb') as f:
        for chunk in response.iter_content(chunk_size=8192):
            if chunk:  # Filtrar chunks keep-alive
                f.write(chunk)
    
    print(f"Baixado {file_path} ({file_path.stat().st_size} bytes)")
else:
    print(f"Falha no download: {response.status_code}")

# Obter informações do arquivo antes de baixar
head_response = requests.head(url)
content_length = head_response.headers.get('content-length')
content_type = head_response.headers.get('content-type')

print(f"Tamanho do arquivo: {content_length} bytes")
print(f"Tipo de conteúdo: {content_type}")

# Baixar com progresso
def download_with_progress(url, filename):
    response = requests.get(url, stream=True)
    total_size = int(response.headers.get('content-length', 0))
    
    with open(filename, 'wb') as f:
        downloaded = 0
        for chunk in response.iter_content(chunk_size=1024):
            if chunk:
                f.write(chunk)
                downloaded += len(chunk)
                
                # Mostrar progresso
                if total_size > 0:
                    progress = (downloaded / total_size) * 100
                    print(f"Progresso: {progress:.1f}%")

Downloads em streaming evitam carregar arquivos inteiros na memória. Perfeito para imagens grandes, documentos ou arquivos de mídia.

10 Gerenciamento de Sessão e Cookies

Para aplicativos que precisam manter o estado entre requisições — como sessões de login — use objetos Session do requests:

import requests

# Criar uma sessão para conexões persistentes e cookies
session = requests.Session()

# Definir cabeçalhos padrão para todas as requisições
session.headers.update({
    'User-Agent': 'MyApp/1.0',
    'Accept': 'application/json'
})

# Lida automaticamente com cookies, pool de conexões e redirecionamentos
response1 = session.get('https://httpbin.org/cookies/set/session_id/abc123')
print("Cookies definidos:", response1.cookies.get_dict())

# Requisições subsequentes incluem os cookies
response2 = session.get('https://httpbin.org/cookies')
print("Cookies recebidos:", response2.json())

# Configuração em nível de sessão
session.auth = ('username', 'password')
session.timeout = 10

# Usar gerenciador de contexto para limpeza automática
with requests.Session() as s:
    response = s.get('https://httpbin.org/json')
    data = response.json()
    print("Usando gerenciador de contexto")
    
# Tratamento manual de cookies
cookies = {'sessionid': 'abc123', 'csrftoken': 'xyz789'}
response = requests.get('https://httpbin.org/cookies', cookies=cookies)
print("Cookies manuais:", response.json())

As sessões lidam automaticamente com pooling de conexões, o que significa requisições subsequentes mais rápidas e menor carga no servidor.

11 Melhores Práticas e Padrões Comuns

Clientes HTTP profissionais seguem certos padrões. Aqui estão práticas comprovadas para código de produção:

import requests
import logging
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

# Configurar logging para depuração
logging.basicConfig(level=logging.WARNING)  # Reduzir ruído
logger = logging.getLogger(__name__)

class APIClient:
    def __init__(self, base_url, timeout=10, max_retries=3):
        self.session = requests.Session()
        
        # Estratégia de retentativa para falhas transitórias
        retry_strategy = Retry(
            total=max_retries,
            status_forcelist=[429, 500, 502, 503, 504],
            method_whitelist=["HEAD", "GET", "OPTIONS"],
            backoff_factor=1
        )
        
        adapter = HTTPAdapter(max_retries=retry_strategy)
        self.session.mount("http://", adapter)
        self.session.mount("https://", adapter)
        
        self.base_url = base_url
        self.timeout = timeout
    
    def get(self, endpoint, **kwargs):
        """Executar requisição GET com tratamento de erros"""
        url = f"{self.base_url.rstrip('/')}/{endpoint.lstrip('/')}"
        
        try:
            response = self.session.get(url, timeout=self.timeout, **kwargs)
            response.raise_for_status()
            return response
        except requests.RequestException as e:
            logger.error(f"Falha na requisição: {e}")
            raise
    
    def post(self, endpoint, **kwargs):
        """Executar requisição POST"""
        url = f"{self.base_url.rstrip('/')}/{endpoint.lstrip('/')}"
        return self.session.post(url, timeout=self.timeout, **kwargs)

# Exemplo de uso
api = APIClient('https://httpbin.org')
try:
    response = api.get('json')
    data = response.json()
    print(f"Dados obtidos: {list(data.keys())}")
except Exception as e:
    print(f"Chamada da API falhou: {e}")

# Configuração baseada em ambiente
import os

API_BASE_URL = os.getenv('API_BASE_URL', 'https://httpbin.org')
API_KEY = os.getenv('API_KEY', 'dev-key')

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'User-Agent': f'MyApp/{__version__}'
}

Esses padrões tratam de retentativas, logging de erros adequado, configuração de ambiente e criam uma camada de abstração limpa para suas interações com a API.

Principais Conclusões

• Use sessões para pooling de conexões e gerenciamento de cookies
• Implemente sempre timeout e tratamento de erros
• Utilize o parâmetro json= para serialização automática
• Transmita downloads de arquivos grandes para gerenciar a memória
• Use variáveis de ambiente para configuração