Conceptos básicos de boto3

10 ejemplos para empezar con los SDK en la nube: 7 básicos y 3 intermedios.

Prerrequisitos

uv venv && source .venv/bin/activate
uv pip install "boto3>=1.35"
aws configure --profile dev  # o export AWS_PROFILE=dev

• Python 3.14.0 con boto3 instalado en un entorno virtual.
• Credenciales de AWS a través de ~/.aws/credentials, variables de entorno o rol de IAM de instancia/tarea.

Ejemplos básicos

1. Crear una sesión

boto3.Session es el punto de entrada para la resolución de región, perfil y credenciales.

import boto3
 
session = boto3.Session(profile_name="dev", region_name="us-east-1")
print(session.region_name)

• Una sesión por contexto lógico de cuenta/región de AWS en scripts.
• profile_name se mapea a las secciones de ~/.aws/credentials.
• Prefiere region_name explícito: los clientes globales aún necesitan una región de firma.

Relacionado: Patrones de credenciales y sesiones - configuraciones de mínimo privilegio

2. Cliente de bajo nivel

Los clientes exponen la API bruta de AWS: un método por acción de API.

import boto3
 
s3 = boto3.client("s3")
resp = s3.list_buckets()
print([b["Name"] for b in resp.get("Buckets", [])])

• Los clientes devuelven diccionarios planos que coinciden con las formas de la API de AWS.
• La paginación es manual a menos que uses paginadores (ver ejemplos intermedios).
• Lo mejor para una cobertura completa de la API y las operaciones más nuevas.

Relacionado: S3 - cargas, descargas, URLs pre-firmadas

3. Interfaz de recursos

Los recursos proporcionan una capa orientada a objetos sobre los clientes.

import boto3
 
s3 = boto3.resource("s3")
for bucket in s3.buckets.all():
    print(bucket.name)

• Las clases Bucket, Object, Table envuelven flujos de trabajo comunes.
• No todas las operaciones de la API tienen un equivalente de recurso; recurre a los clientes cuando sea necesario.
• Los recursos todavía usan la misma cadena de credenciales que los clientes.

Relacionado: S3 - operaciones de transmisión y objetos

4. Configuración de región y punto de conexión

Fija la región para evitar latencias interregionales sorprendentes o un comportamiento incorrecto de la partición.

import boto3
 
session = boto3.Session(region_name="eu-west-1")
dynamodb = session.client("dynamodb")
print(dynamodb.meta.region_name)

• meta.region_name confirma dónde se firman las solicitudes.
• Usa endpoint_url solo para LocalStack, puntos de conexión de VPC o pasarelas personalizadas.
• Las aplicaciones multirregión crean una sesión por región, no un cliente global.

Relacionado: Reintentos, paginación y limitación - llamadas robustas a escala

5. Orden de la cadena de credenciales

boto3 resuelve las credenciales automáticamente cuando no pasas claves en el código.

import boto3
 
session = boto3.Session()
creds = session.get_credentials()
print(creds.method if creds else "no credentials")

• Orden: variables de entorno → config/credenciales compartidas → rol de IAM (EC2/ECS/Lambda).
• AWS_PROFILE selecciona un perfil con nombre sin codificarlo en el código fuente.
• Nunca confirmes claves de acceso; rota inmediatamente si se filtran.

Relacionado: Secrets Manager y SSM - obtención de secretos en tiempo de ejecución

6. Manejo de errores con ClientError

Los errores de AWS llegan como botocore.exceptions.ClientError con códigos estructurados.

import boto3
from botocore.exceptions import ClientError
 
s3 = boto3.client("s3")
try:
    s3.head_bucket(Bucket="definitely-missing-bucket-xyz")
except ClientError as exc:
    code = exc.response["Error"]["Code"]
    print(code)

• Ramifica según Error.Code (404, NoSuchBucket, AccessDenied), no según cadenas de mensajes.
• El diccionario response refleja las cargas útiles de error XML/JSON de AWS.
• Registra el ID de la solicitud de ResponseMetadata para tickets de soporte de AWS.

Relacionado: Mejores prácticas de SDK en la nube - reglas seguras de manejo de errores

7. Reutilizar clientes en trabajadores

Crea clientes una vez por proceso, no por solicitud en bucles intensivos.

import boto3
 
_SESSION = boto3.Session()
_SQS = _SESSION.client("sqs")
 
def send_message(queue_url: str, body: str) -> None:
    _SQS.send_message(QueueUrl=queue_url, MessageBody=body)

• La creación de clientes es relativamente costosa; la reutilización a nivel de módulo está bien para scripts y trabajadores.
• Seguridad de hilos: los clientes son generalmente seguros para hilos; los recursos no siempre lo son.
• En Lambda, crea clientes fuera del manejador para reutilizar conexiones entre invocaciones.

Relacionado: SQS y SNS - patrones de colas y temas

Ejemplos intermedios

8. Paginadores para grandes conjuntos de resultados

Deja de crear bucles NextToken manualmente: usa los paginadores integrados.

import boto3
 
s3 = boto3.client("s3")
paginator = s3.get_paginator("list_objects_v2")
for page in paginator.paginate(Bucket="my-bucket", Prefix="logs/"):
    for obj in page.get("Contents", []):
        print(obj["Key"], obj["Size"])

• Los paginadores manejan tokens y tamaños de página de manera consistente.
• Establece PaginationConfig={"MaxItems": 100} para limitar los scripts de desarrollo.
• Empareja con Reintentos, paginación y limitación para APIs limitadas.

Relacionado: DynamoDB - paginación de consultas

9. Waiters para la convergencia de recursos

Espera hasta que AWS finalice la creación asíncrona antes de los pasos dependientes.

import boto3
 
ec2 = boto3.client("ec2")
waiter = ec2.get_waiter("instance_running")
instance_id = "i-0123456789abcdef0"
waiter.wait(InstanceIds=[instance_id])

• Los waiters sondean con retroceso hasta el éxito o el número máximo de intentos.
• Prefiere waiters sobre estimaciones de time.sleep en scripts de aprovisionamiento.
• Configura WaiterConfig={"Delay": 5, "MaxAttempts": 40} para recursos de larga duración.

Relacionado: Aprovisionamiento de recursos en la nube - flujos de trabajo de arranque

10. Configuración de botocore para reintentos y tiempos de espera

Ajusta los reintentos y los tiempos de espera para los patrones de tráfico de producción.

import boto3
from botocore.config import Config
 
config = Config(
    retries={"max_attempts": 10, "mode": "standard"},
    connect_timeout=5,
    read_timeout=60,
)
s3 = boto3.client("s3", config=config)

• mode: adaptive ayuda bajo limitación sostenida; standard es un valor predeterminado predecible.
• Separa los tiempos de espera de conexión y lectura: las descargas grandes de S3 necesitan un tiempo de espera de lectura más alto.
• Aplica el mismo objeto Config a cada cliente de una clase de servicio.

Relacionado: Reintentos, paginación y limitación - estrategias de limitación

Versiones de la pila: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.