Fragmentos de la Biblioteca de Peticiones de Python

1 Introducción a Python Requests

La librería requests es el cliente HTTP elegante de Python que hace que las llamadas a API se sientan como algo natural. Abstrae los detalles complejos de HTTP mientras mantiene el poder bajo la superficie. Piensa en ello como tu mensajero confiable para Internet: maneja todo, desde simples capturas de páginas hasta flujos de autenticación complejos.

Por qué los desarrolladores la aman:

Amigable con el humano: La API se lee como inglés claro en lugar de jerga críptica de HTTP.
JSON incorporado: El análisis automático elimina dolores de cabeza de análisis de código repetitivo.
Soporte de sesión: Mantiene cookies y agrupación de conexiones por ti automáticamente.
Manejo robusto de errores: Excepciones claras en lugar de códigos de estado crípticos.
Verificación SSL: Seguro por defecto, flexible cuando es necesario.

¿Listo para obtener algunos datos? Empecemos con lo básico.

2 Prerrequisitos: Python y Pip

Necesitarás Python 3.6+ y pip para instalar la librería requests. Verifiquemos tu configuración:

python --version && pip --version

Si esos comandos funcionan, estás listo. Si no, descarga Python desde python.org y pip vendrá contigo.

3 Instalar la Librería Requests

Primero, creemos un nuevo entorno virtual; esto mantiene limpias las dependencias de tu proyecto y evita conflictos de versiones:

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

Ahora instala requests usando pip:

pip install requests

4 Tu Primera Solicitud GET

Empecemos con la operación más común: obtener datos. Este simple fragmento obtiene una respuesta JSON de una API pública:

import requests

response = requests.get('https://httpbin.org/json')
print(f"Estado: {response.status_code}")
print(f"Tipo de contenido: {response.headers['content-type']}")

# Análisis automático de JSON
data = response.json()
print(f"Claves: {list(data.keys())}")

Observa el análisis automático de JSON: requests detecta el tipo de contenido y lo analiza por ti. No se requiere un baile manual de json.loads().

5 Solicitudes POST con Datos

¿Envías datos a un servidor? Las solicitudes POST manejan datos de formularios, JSON y archivos sin problemas. Estos son los patrones comunes:

import requests

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

# Enviar datos JSON (establece automáticamente la cabecera Content-Type)
json_data = {'name': 'Alice', 'email': '[email protected]'}
response = requests.post('https://httpbin.org/post', json=json_data)

print(f"Estado: {response.status_code}")
print(f"Respuesta: {response.json()}")

El parámetro json establece automáticamente las cabeceras correctas y serializa tus datos. Mucho más limpio que establecer cabeceras manualmente.

6 Cabeceras Personalizadas y Autenticación

Las API a menudo necesitan cabeceras personalizadas y autenticación. Requests lo hace sencillo con clases de autenticación incorporadas:

import requests
from requests.auth import HTTPBasicAuth, HTTPDigestAuth

# Cabeceras personalizadas
headers = {
    'User-Agent': 'MyApp/1.0',
    'Accept': 'application/json',
    'X-API-Key': 'tu-clave-api-aqui'
}

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

# Autenticación Básica
auth = HTTPBasicAuth('username', 'password')
response = requests.get('https://httpbin.org/basic-auth/user/pass', auth=auth)

# Clave API en cabecera
api_key = 'sk-1234567890abcdef'
headers = {'Authorization': f'Bearer {api_key}'}
response = requests.get('https://httpbin.org/bearer', headers=headers)

HTTPBasicAuth y HTTPDigestAuth manejan la codificación automáticamente. Para las API modernas, los tokens Bearer en la cabecera Authorization son el estándar.

7 Manejo de Errores y Códigos de Estado

Las aplicaciones robustas manejan los errores con gracia. Requests lanza excepciones para problemas de red y proporciona objetos de respuesta detallados:

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

try:
    response = requests.get('https://httpbin.org/status/404', timeout=5)
    
    # Lanza una excepción para códigos de estado incorrectos
    response.raise_for_status()
    
except Timeout:
    print("La solicitud superó el tiempo de espera después de 5 segundos")
except ConnectionError:
    print("Error al conectar al servidor")
except RequestException as e:
    print(f"La solicitud falló: {e}")
    
else:
    print(f"¡Éxito! Estado: {response.status_code}")
    print(f"Cabeceras: {response.headers}")
    print(f"Cuerpo: {response.text[:100]}...")  # Primeros 100 caracteres
    
# Verificación manual del código de estado
if response.status_code == 200:
    data = response.json()
    print("Datos recibidos:", data)
elif response.status_code == 404:
    print("Recurso no encontrado")
else:
    print(f"Estado inesperado: {response.status_code}")

raise_for_status() lanza un HTTPError para respuestas 4xx/5xx. Los tiempos de espera evitan que tu aplicación se cuelgue indefinidamente.

8 Procesamiento JSON y Manejo de Datos

Trabajar con datos JSON de manera eficiente es donde requests brilla. Maneja la codificación, decodificación y validación automáticamente:

import requests

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

# Análisis seguro de JSON con manejo de errores
try:
    data = response.json()
    print(f"Tipo: {type(data)}")
    print(f"Claves: {data.keys() if isinstance(data, dict) else 'No es un dict'}")
except ValueError as e:
    print(f"JSON inválido: {e}")
    print(f"Contenido bruto: {response.text}")

# Trabajar con datos anidados
user_data = {
    'name': 'Alice Johnson',
    'email': '[email protected]',
    'preferences': {
        'theme': 'dark',
        'notifications': True,
        'language': 'en'
    }
}

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

# Acceder a valores anidados
nested = result.get('json', {}).get('preferences', {})
theme = nested.get('theme', 'light')
print(f"Tema del usuario: {theme}")

Utiliza siempre métodos seguros como get() al acceder a JSON anidado para evitar excepciones KeyError.

9 Descarga de Archivos y Streaming

Descargar archivos eficientemente evita problemas de memoria. Usa streaming para archivos grandes y verifica el tipo de contenido:

import requests
import os
from pathlib import Path

# Descargar un archivo
url = 'https://httpbin.org/image/jpeg'
response = requests.get(url, stream=True)

if response.status_code == 200:
    # Crear directorio de descargas
    downloads_dir = Path('downloads')
    downloads_dir.mkdir(exist_ok=True)
    
    # Guardar archivo
    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 de keep-alive
                f.write(chunk)
    
    print(f"Descargado {file_path} ({file_path.stat().st_size} bytes)")
else:
    print(f"Fallo al descargar: {response.status_code}")

# Obtener información del archivo antes de descargar
head_response = requests.head(url)
content_length = head_response.headers.get('content-length')
content_type = head_response.headers.get('content-type')

print(f"Tamaño del archivo: {content_length} bytes")
print(f"Tipo de contenido: {content_type}")

# Descargar con progreso
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)
                
                # Imprimir progreso
                if total_size > 0:
                    progress = (downloaded / total_size) * 100
                    print(f"Progreso: {progress:.1f}%")

Las descargas en streaming evitan cargar archivos completos en memoria. Perfecto para imágenes grandes, documentos o archivos multimedia.

10 Gestión de Sesiones y Cookies

Para aplicaciones que necesitan mantener el estado entre solicitudes, como sesiones de inicio de sesión, usa objetos de sesión de requests:

import requests

# Crear una sesión para conexiones persistentes y cookies
session = requests.Session()

# Establecer cabeceras predeterminadas para todas las solicitudes
session.headers.update({
    'User-Agent': 'MyApp/1.0',
    'Accept': 'application/json'
})

# Maneja automáticamente cookies, agrupación de conexiones y redirecciones
response1 = session.get('https://httpbin.org/cookies/set/session_id/abc123')
print("Cookies establecidas:", response1.cookies.get_dict())

# Las solicitudes posteriores incluyen las cookies
response2 = session.get('https://httpbin.org/cookies')
print("Cookies recibidas:", response2.json())

# Configuración a nivel de sesión
session.auth = ('username', 'password')
session.timeout = 10

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

Las sesiones manejan automáticamente la agrupación de conexiones, lo que significa solicitudes posteriores más rápidas y menor carga del servidor.

11 Mejores Prácticas y Patrones Comunes

Los clientes HTTP profesionales siguen ciertos patrones. Aquí hay prácticas probadas en batalla para código de producción:

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

# Configurar registro para depuración
logging.basicConfig(level=logging.WARNING)  # Reduce el ruido
logger = logging.getLogger(__name__)

class APIClient:
    def __init__(self, base_url, timeout=10, max_retries=3):
        self.session = requests.Session()
        
        # Estrategia de reintentos para fallos transitorios
        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):
        """Realiza una solicitud GET con manejo de errores"""
        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"La solicitud falló: {e}")
            raise
    
    def post(self, endpoint, **kwargs):
        """Realiza una solicitud POST"""
        url = f"{self.base_url.rstrip('/')}/{endpoint.lstrip('/')}"
        return self.session.post(url, timeout=self.timeout, **kwargs)

# Ejemplo de uso
api = APIClient('https://httpbin.org')
try:
    response = api.get('json')
    data = response.json()
    print(f"Obtenidos datos: {list(data.keys())}")
except Exception as e:
    print(f"La llamada a la API falló: {e}")

# Configuración basada en el entorno
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__}'
}

Estos patrones manejan reintentos, registro adecuado de errores, configuración del entorno y crean una capa de abstracción limpia para tus interacciones con la API.

Puntos Clave

• Usa sesiones para agrupación de conexiones y gestión de cookies
• Implementa siempre tiempos de espera y manejo de errores
• Aprovecha el parámetro json= para serialización automática
• Transmite descargas de archivos grandes para gestionar la memoria
• Usa variables de entorno para la configuración