Bucket Helper

🇫🇷 · 🇬🇧

Bucket Helper gehört zu einer Sammlung von Bibliotheken namens AI Helpers, die für die Entwicklung Künstlicher Intelligenz entwickelt wurden. Jede wird auf PyPI hinter einem eigenen grünen CI-Gate (pytest plus ruff, beide blockierend) und semantisch versionierten Releases veröffentlicht.

Hilfsfunktionen für AWS S3 und jeden S3-kompatiblen Objektspeicher: MinIO, Backblaze B2 S3 API, DigitalOcean Spaces, Cloudflare R2, Wasabi und weitere. Basierend auf boto3. Gleiche Form wie sftp-helper: ein credentials()-Lader, die üblichen CRUD-Operationen (upload / download / delete / exists / list_prefix) und ein remote_tempfile-Kontextmanager für Stage-and-Share-Abläufe.

Objektspeicher hält Dateien als flache, adressierbare Blobs, einen Bucket plus einen Schlüssel wie my-bucket/folder/file.txt, anstelle eines verschachtelten Ordnerbaums auf einer Festplatte: Es muss nichts im Voraus erstellt werden, es gibt keine Begrenzung, wie viele Dateien an einem Ort liegen, und jedes Objekt ist direkt über eine URL erreichbar. Amazon Web Services baute die erste populäre Version davon, S3 (Simple Storage Service), und sein Drahtprotokoll wurde zum De-facto-Standard: MinIO, Backblaze B2, DigitalOcean Spaces, Cloudflare R2 und Wasabi sprechen alle dieselbe S3-API, sodass bucket-helper unverändert gegen jede von ihnen läuft; nur die Endpunkt-URL ändert sich.

🌍 AI Helpers

Das Versprechen

Bewusst remote. bucket-helper existiert, um Daten zu und von Objektspeicher Ihrer Wahl zu bewegen: AWS oder einen beliebigen S3-kompatiblen Endpunkt, auf den Sie es richten (einschließlich einer MinIO-Instanz in Ihrem eigenen Netzwerk). Es ist bewusst nicht lokal-first und wird ohne GUI geliefert. Für einen Remote, der über SFTP statt S3 erreicht wird, verwenden Sie sftp-helper; zum Herunterladen von Medien von einer URL verwenden Sie youtube-helper.

Diese Remote-Erreichbarkeit ist auch der Ort, an dem „kampferprobt“ etwas Überprüfbares bedeuten muss, nicht nur ein Slogan. Jeder Push durchläuft ein blockierendes CI-Gate: Die Testsuite testet den S3-Client gegen ein moto-gemocktes Backend, dann prüft ruff den Stil; nichts wird bei einem roten Lauf in main gemergt. Das Paket wurde über neun semantisch versionierte Releases auf PyPI veröffentlicht, von v0.2.2 bis zum aktuellen v1.1.2 (die Tag-Historie ist mit git tag sichtbar). Es hängt von os-helper ab, dem kleinen Fundamentpaket, das die gesamte AI-Helpers-Suite für Logging und Dateiverwaltung gemeinsam nutzt; nichts hier erfindet diese Schicht neu.

Related MCP server: MinIO MCP Server

Dokumentation

💻 Dokumentation

🗺️ Landschaft

📋 Beispiele

🎯 Auslöser

Funktionen

• CRUD gegen AWS S3 oder einen beliebigen S3-kompatiblen Endpunkt: upload, download, delete, exists, list_prefix.

• Funktioniert mit jedem S3-kompatiblen Anbieter, MinIO, Backblaze B2 S3 API, DigitalOcean Spaces, Cloudflare R2, Wasabi, indem die endpoint_url-Anmeldedaten darauf zeigen; keine Codeänderungen pro Anbieter.

• Anmeldedaten-Lader (credentials), der JSON / YAML / Umgebungsvariablen / .env in dieser Reihenfolge auflöst.

• remote_tempfile-Kontextmanager für Stage-and-Share-Abläufe: Hochladen, Objekt zurückgeben, automatisches Löschen beim Verlassen des Blocks, keine manuelle Bereinigung.

• Drei Oberflächen, ein Verhalten: Python-Bibliothek, argparse-CLI, click-CLI-Zwilling ([cli]-Extra) und FastAPI-HTTP-Oberfläche ([api]-Extra). Siehe den Multi-Oberflächen-Abschnitt.

• Docker-Image enthält den HTTP-Server einsatzbereit.

Installation

Voraussetzungen: Python 3.10–3.13 und git, plattformübergreifend:

• 🍎 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

Wir empfehlen die Verwendung von Python-Umgebungen. Schauen Sie sich diesen Link an, wenn Sie nicht wissen, wie man eine einrichtet: 🥸 Tech-Tipps.

Von PyPI (empfohlen)

# 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

Aus dem Quellcode (ohne 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]"

Die argparse-CLI ist immer verfügbar. Das [cli]-Extra fügt den click-Zwilling hinzu.

Konfiguration

Eine ausfüllbare Vorlage ist unter settings.yaml.example eingecheckt. Kopieren Sie sie nach settings.yaml und bearbeiten Sie sie direkt: settings.yaml ist gitignored, sodass Sie nicht versehentlich Geheimnisse committen können.

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

Sie können auch JSON statt YAML schreiben, eine .env-Datei verwenden oder Umgebungsvariablen setzen; bucket-helper greift in dieser Reihenfolge über os_helper.get_config darauf zurück. Erforderliche Schlüssel:

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

Optionale Schlüssel:

Endpunkt-URLs für gängige S3-kompatible Speicher

Setzen Sie s3_endpoint_url auf:

Verwendung

Für den vollständigen Katalog an Rezepten (Uploads / Downloads / Auflistungen, S3-kompatible Endpunkte wie MinIO / R2 / B2 / Spaces / Wasabi, temporäre Remote-Schlüssel mit automatischer Bereinigung, Spiegelung mit sftp-helper) siehe 📋 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)

MinIO-Beispiel

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")

Stage-and-Share mit remote_tempfile

Legen Sie eine generierte Datei unter einem eindeutigen zufälligen Schlüssel ab, übergeben Sie die öffentliche URL an einen nachgelagerten Worker / Webhook, und das Objekt wird beim Verlassen des Blocks gelöscht (auch wenn der Body eine Ausnahme auslöst):

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.

Multi-Oberflächen

Jede öffentliche Funktion der Bibliothek ist auch verfügbar als:

• argparse-CLI: bucket-helper <subcommand> (standardmäßig installiert).

• click-CLI: bucket-helper-click <subcommand> (installieren Sie das [cli]-Extra).

• FastAPI-HTTP: uvicorn bucket_helper.api:app --host 0.0.0.0 --port 8000 (installieren Sie das [api]-Extra).

• MCP: bucket-helper-mcp stellt dieselbe HTTP-Oberfläche als MCP-Tools für jeden MCP-fähigen Agent-Host bereit (installieren Sie das [mcp]-Extra).

Beide CLIs teilen sich dieselben Unterbefehlsnamen und Flags; wählen Sie Ihre Favoriten.

Der vollständige Katalog dessen, was das Toolkit auslöst (natürlichsprachliche Formulierungen, Befehle, Funktionen, Adresshinweise und explizite SKIP-Regeln) befindet sich in TRIGGERS.md.

CLI-Beispiele

# 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

HTTP-Server

# 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

Anmeldedaten pro Anfrage können auch als Multipart-Formularfelder gesendet werden (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

Siehe auch: TRIGGERS.md (was das Toolkit aufruft) und GUI.md (visueller Produktdesignplan; keine GUI wird mitgeliefert, bucket-helper ist Remote-Objektspeicher-Infrastruktur).

Autor

• Warith HARCHAOUI

Danksagungen

Besonderer Dank an Mohamed Chelali und Bachir Zerroug für fruchtbare Diskussionen.

Lizenz

Dieses Projekt ist unter der BSD-3-Clause-Lizenz lizenziert; siehe die Datei LICENSE für Details.