Bucket Helper

🇫🇷 · 🇬🇧

Bucket Helper pertenece a una colección de bibliotecas llamada AI Helpers desarrollada para construir Inteligencia Artificial, cada una publicada en PyPI detrás de su propia puerta de CI verde (pytest y ruff, ambos bloqueantes) y lanzamientos con versiones semánticas.

Funciones de utilidad para AWS S3 y cualquier almacenamiento de objetos compatible con S3: MinIO, Backblaze B2 S3 API, DigitalOcean Spaces, Cloudflare R2, Wasabi y otros. Construido sobre boto3. Misma forma que sftp-helper: un cargador de credentials(), el CRUD habitual (upload / download / delete / exists / list_prefix), y un administrador de contexto remote_tempfile para flujos de preparación y compartición.

El almacenamiento de objetos mantiene los archivos como blobs planos y direccionables, un bucket más una clave como my-bucket/folder/file.txt, en lugar de un árbol de carpetas anidado en un disco duro: nada que crear de antemano, sin límite en cuántos archivos se acumulan en un lugar, y cada objeto es accesible directamente desde una URL. Amazon Web Services construyó la primera versión popular de esto, S3 (Simple Storage Service), y su protocolo de red se convirtió en el estándar de facto: MinIO, Backblaze B2, DigitalOcean Spaces, Cloudflare R2 y Wasabi todos hablan la misma API de S3, por lo que bucket-helper funciona sin cambios contra cualquiera de ellos; solo cambia la URL del endpoint.

🌍 AI Helpers

La Promesa

Remoto por diseño. bucket-helper existe para mover datos hacia y desde el almacenamiento de objetos que elijas: AWS, o cualquier endpoint compatible con S3 al que lo apuntes (incluyendo una instancia de MinIO en tu propia red). Está deliberadamente no local-first y no incluye GUI. Para un remoto alcanzado vía SFTP en lugar de S3, usa sftp-helper; para descargar medios desde una URL, usa youtube-helper.

Ese alcance remoto es también donde "probado en batalla" tiene que significar algo comprobable, no un eslogan. Cada push ejecuta una puerta de CI bloqueante: la suite de pruebas ejercita el cliente S3 contra un backend simulado con moto, luego ruff verifica el estilo; nada se fusiona a main en una ejecución en rojo. El paquete ha pasado por nueve lanzamientos con versiones semánticas en PyPI, desde v0.2.2 hasta el actual v1.1.2 (el historial de etiquetas es visible con git tag). Depende de os-helper, el pequeño paquete base que toda la suite AI Helpers comparte para registro y manejo de archivos; nada aquí reinventa esa capa.

Related MCP server: MinIO MCP Server

Documentación

💻 Documentación

🗺️ Paisaje

📋 Ejemplos

🎯 Disparadores

Características

• CRUD contra AWS S3 o cualquier endpoint compatible con S3: upload, download, delete, exists, list_prefix.

• Funciona contra cualquier proveedor compatible con S3, MinIO, Backblaze B2 S3 API, DigitalOcean Spaces, Cloudflare R2, Wasabi, apuntando la credencial endpoint_url a él; sin cambios de código por proveedor.

• Cargador de credenciales (credentials) que resuelve JSON / YAML / variables de entorno / .env, en ese orden de respaldo.

• remote_tempfile administrador de contexto para flujos de preparación y compartición: sube, devuelve el objeto, auto-elimina al salir del bloque, sin limpieza manual.

• Tres superficies, un comportamiento: biblioteca de Python, CLI argparse, gemelo CLI click (extra [cli]), y superficie HTTP FastAPI (extra [api]). Ver la sección de múltiples superficies.

• Imagen Docker incluye el servidor HTTP listo para ejecutar.

Instalación

Requisitos previos: Python 3.10–3.13 y git, multiplataforma:

• 🍎 macOS (Homebrew): brew install python git

• 🐧 Ubuntu/Debian: sudo apt update && sudo apt install -y python3 python3-pip git

• 🪟 Windows (PowerShell): winget install Python.Python.3.12 Git.Git

Recomendamos usar entornos de Python. Consulta este enlace si no estás familiarizado con su configuración: 🥸 Consejos técnicos.

Desde PyPI (recomendado)

# Core library (credentials loader + CRUD + remote_tempfile)
pip install bucket-helper

# Optional surfaces
pip install "bucket-helper[cli]"       # click-based CLI twin
pip install "bucket-helper[api]"       # FastAPI HTTP surface

Desde el código fuente (sin PyPI)

git clone https://github.com/warith-harchaoui/bucket-helper.git
cd bucket-helper
pip install -e .

# Optional surfaces
pip install -e ".[cli]"
pip install -e ".[api]"

La CLI argparse siempre está disponible. El extra [cli] añade el gemelo click.

Configuración

Hay una plantilla lista para completar en settings.yaml.example. Cópiala a settings.yaml y edítala en su lugar: settings.yaml está en gitignore, por lo que no puedes confirmar secretos accidentalmente.

cp settings.yaml.example settings.yaml
# then edit settings.yaml with your AWS / MinIO / R2 / B2 credentials

También puedes escribir JSON en lugar de YAML, usar un .env, o establecer variables de entorno; bucket-helper recurre en ese orden a través de os_helper.get_config. Claves requeridas:

{
  "s3_access_key": "AKIA...",
  "s3_secret_key": "...",
  "s3_bucket":     "my-bucket",
  "s3_https":      "https://my-bucket.s3.eu-west-3.amazonaws.com"
}

Claves opcionales:

URLs de endpoint para almacenamiento compatible con S3 común

Establece s3_endpoint_url a:

Uso

Para el catálogo completo de recetas (subidas / descargas / listados, endpoints compatibles con S3 como MinIO / R2 / B2 / Spaces / Wasabi, claves remotas temporales con auto-limpieza, espejado con sftp-helper), ver 📋 EXAMPLES.md.

import bucket_helper as bh

# Load creds: JSON / YAML / env / .env (auto-fallback in that order)
cred = bh.credentials("path/to/settings.yaml")

# Upload a local file
uri = bh.upload("local.txt", cred, "folder/uploaded.txt")
# uri == "s3://my-bucket/folder/uploaded.txt"

assert bh.exists(uri, cred)

# Download
bh.download(uri, "downloaded.txt", cred)

# List
for key in bh.list_prefix("folder/", cred):
    print(key)

# Delete
bh.delete(uri, cred)

Ejemplo de MinIO

cred = {
    "s3_access_key":      "minioadmin",
    "s3_secret_key":      "minioadmin",
    "s3_bucket":          "uploads",
    "s3_https":           "http://minio.example.com:9000/uploads",
    "s3_endpoint_url":    "http://minio.example.com:9000",
    "s3_use_path_style":  "true",
    "s3_region":          "us-east-1",  # MinIO accepts any region string
}

bh.make_bucket("uploads", cred)
bh.upload("file.bin", cred, "file.bin")

Preparación y compartición con remote_tempfile

Coloca un archivo generado en una clave aleatoria única, entrega la URL pública a un trabajador / webhook posterior, y el objeto se elimina al salir del bloque (incluso si el cuerpo lanza una excepción):

import bucket_helper as bh
import requests

cred = bh.credentials("path/to/settings.yaml")

with bh.remote_tempfile(cred, ext="json", prefix="runs") as (s3_addr, public_url):
    bh.upload("payload.json", cred, s3_addr, content_type="application/json")
    # Hand the URL to something that fetches it once.
    requests.post("https://hook.example.com/process", json={"input_url": public_url}).raise_for_status()
# Object is gone here, no manual cleanup.

Exposición de múltiples superficies

Cada función pública de la biblioteca también se expone como:

• CLI argparse: bucket-helper <subcommand> (instalado por defecto).

• CLI click: bucket-helper-click <subcommand> (instala el extra [cli]).

• HTTP FastAPI: uvicorn bucket_helper.api:app --host 0.0.0.0 --port 8000 (instala el extra [api]).

• MCP: bucket-helper-mcp expone la misma superficie HTTP como herramientas MCP para cualquier host agente compatible con MCP (instala el extra [mcp]).

Ambas CLI comparten los mismos nombres de subcomandos y banderas; elige tu favorita.

El catálogo exhaustivo de lo que activa el kit de herramientas (frases en lenguaje natural, comandos, funciones, señales de dirección y reglas SKIP explícitas) se encuentra en TRIGGERS.md.

Ejemplos de CLI

# argparse CLI (always available)
bucket-helper upload      --config settings.yaml --input local.txt --key folder/uploaded.txt
bucket-helper exists      --config settings.yaml --key folder/uploaded.txt
bucket-helper download    --config settings.yaml --key folder/uploaded.txt --output back.txt
bucket-helper list        --config settings.yaml --prefix folder/
bucket-helper delete      --config settings.yaml --key folder/uploaded.txt
bucket-helper make-bucket --config settings.yaml --bucket new-bucket
bucket-helper tempfile    --config settings.yaml --ext json --prefix runs
bucket-helper strip-path  --config settings.yaml --address s3://my-bucket/path/to/obj

# click CLI: same verbs, same flags
bucket-helper-click upload --config settings.yaml --input local.txt --key folder/uploaded.txt

Servidor HTTP

# Serve HTTP (default credentials picked up from BUCKET_HELPER_CONFIG)
BUCKET_HELPER_CONFIG=$PWD/settings.yaml uvicorn bucket_helper.api:app --host 0.0.0.0 --port 8000
# → Swagger UI at http://localhost:8000/docs

Las credenciales por solicitud también se pueden enviar como campos de formulario multipart (s3_access_key / s3_secret_key / s3_bucket / s3_https / …).

Docker

docker build -t bucket-helper .
docker run --rm -p 8000:8000 \
  -e BUCKET_HELPER_CONFIG=/config/settings.yaml \
  -v $PWD/settings.yaml:/config/settings.yaml:ro \
  bucket-helper

Ver también: TRIGGERS.md (qué invoca el kit de herramientas) y GUI.md (plan de diseño visual del producto; no se incluye GUI, bucket-helper es plomería de almacenamiento de objetos remoto).

Autor

• Warith HARCHAOUI

Agradecimientos

Agradecimientos especiales a Mohamed Chelali y Bachir Zerroug por las fructíferas discusiones.

Licencia

Este proyecto está licenciado bajo la Licencia BSD-3-Clause; ver el archivo LICENSE para más detalles.