Bucket Helper

🇫🇷 · 🇬🇧

Bucket Helper は、人工知能構築のために開発された AI Helpers と呼ばれるライブラリ群に属しており、各ライブラリは PyPI に公開され、それぞれ独自のグリーン CI ゲート（pytest と ruff、両方ともブロッキング）とセマンティックバージョニングによるリリースを備えています。

AWS S3 およびあらゆる S3 互換オブジェクトストレージ（MinIO、Backblaze B2 S3 API、DigitalOcean Spaces、Cloudflare R2、Wasabi など）のためのユーティリティ関数です。boto3 上に構築されています。sftp-helper と同じ形状です：credentials() ローダー、通常の CRUD（upload / download / delete / exists / list_prefix）、およびステージ・アンド・シェアフロー用の remote_tempfile コンテキストマネージャー。

オブジェクトストレージは、ファイルをハードドライブ上のネストされたフォルダツリーではなく、フラットでアドレス可能なブロブとして保持します。バケットとキー（例：my-bucket/folder/file.txt）で構成されます。事前に作成するものはなく、1 か所に蓄積できるファイル数に制限はなく、すべてのオブジェクトは URL から直接到達できます。Amazon Web Services がこの最初の普及版である S3（Simple Storage Service）を構築し、そのワイヤプロトコルは事実上の標準となりました。MinIO、Backblaze B2、DigitalOcean Spaces、Cloudflare R2、Wasabi はすべて同じ S3 API を話すため、bucket-helper はエンドポイント URL を変更するだけで、これらのいずれに対しても変更なしで動作します。

🌍 AI Helpers

約束

リモート設計。 bucket-helper は、選択したオブジェクトストレージ（AWS、または指定した任意の S3 互換エンドポイント（自社ネットワーク上の MinIO インスタンスを含む））との間でデータを移動するために存在します。意図的にローカルファーストではなく、GUI は付属しません。SFTP 経由でリモートにアクセスする場合は sftp-helper を、URL からメディアをダウンロードする場合は youtube-helper を使用してください。

そのリモート到達性こそ、「実戦で試された」という言葉が単なるスローガンではなく、検証可能な意味を持つ場所です。すべてのプッシュはブロッキング CI ゲートを通過します。テストスイートは moto モックバックエンドに対して S3 クライアントを実行し、その後 ruff がスタイルをチェックします。赤い実行で main にマージされることはありません。このパッケージは PyPI で 9 つのセマンティックバージョン付きリリースを公開しており、v0.2.2 から現在の v1.1.2 まで（タグ履歴は git tag で確認できます）。これは、AI Helpers スイート全体がロギングとファイル処理のために共有する小さな基盤パッケージである os-helper に依存しています。ここでそのレイヤーを再発明することはありません。

Related MCP server: MinIO MCP Server

ドキュメント

💻 ドキュメント

🗺️ ランドスケープ

📋 例

🎯 トリガー

機能

• CRUD：AWS S3 または任意の S3 互換エンドポイントに対する upload、download、delete、exists、list_prefix。

• 任意の S3 互換プロバイダーで動作：MinIO、Backblaze B2 S3 API、DigitalOcean Spaces、Cloudflare R2、Wasabi など。endpoint_url 資格情報を指定するだけで、プロバイダーごとのコード変更は不要です。

• 資格情報ローダー（credentials）：JSON / YAML / 環境変数 / .env をこのフォールバック順で解決します。

• remote_tempfile コンテキストマネージャー：ステージ・アンド・シェアフロー用。アップロードしてオブジェクトを返し、ブロック終了時に自動削除。手動クリーンアップは不要です。

• 3 つのサーフェス、1 つの動作：Python ライブラリ、argparse CLI、click CLI ツイン（[cli] エクストラ）、FastAPI HTTP サーフェス（[api] エクストラ）。マルチサーフェスセクション を参照してください。

• Docker イメージ：HTTP サーバーをすぐに実行できる状態で同梱。

インストール

前提条件：Python 3.10–3.13 と git、クロスプラットフォーム：

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

Python 環境の使用をお勧めします。環境の設定に不慣れな場合は、このリンクを確認してください：🥸 テックヒント。

PyPI から（推奨）

# 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

ソースから（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]"

argparse CLI は常に利用可能です。[cli] エクストラで click ツインが追加されます。

設定

すぐに記入できるテンプレートが settings.yaml.example にコミットされています。それを settings.yaml にコピーしてその場で編集してください。settings.yaml は gitignore されているため、誤ってシークレットをコミットすることはありません。

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

YAML の代わりに JSON を書いたり、.env を使用したり、環境変数を設定したりすることもできます。bucket-helper は os_helper.get_config を介してこの順序でフォールバックします。必須キー：

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

オプションキー：

一般的な S3 互換ストレージのエンドポイント URL

s3_endpoint_url を次のように設定します：

使用法

レシピの完全なカタログ（アップロード / ダウンロード / リスト、MinIO / R2 / B2 / Spaces / Wasabi などの S3 互換エンドポイント、自動クリーンアップ付きの一時リモートキー、sftp-helper とのミラーリング）については、📋 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 の例

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

remote_tempfile によるステージ・アンド・シェア

生成されたファイルを一意のランダムキーに配置し、公開 URL をダウンストリームのワーカー / ウェブフックに渡します。オブジェクトはブロック終了時に削除されます（本体が例外を発生させた場合でも）：

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.

マルチサーフェス公開

ライブラリのすべての公開関数は、次のものとしても公開されています：

• argparse CLI：bucket-helper <サブコマンド>（デフォルトでインストール）。

• click CLI：bucket-helper-click <サブコマンド>（[cli] エクストラをインストール）。

• FastAPI HTTP：uvicorn bucket_helper.api:app --host 0.0.0.0 --port 8000（[api] エクストラをインストール）。

• MCP：bucket-helper-mcp は、同じ HTTP サーフェスを MCP ツールとして、MCP 対応の任意のエージェントホストに公開します（[mcp] エクストラをインストール）。

両方の CLI は同じサブコマンド名とフラグを共有しています。お好みのものを選んでください。

ツールキットをトリガーするものの網羅的なカタログ（自然言語の言い回し、コマンド、関数、アドレスキュー、明示的な SKIP ルール）は TRIGGERS.md にあります。

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

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

リクエストごとの資格情報は、マルチパートフォームフィールド（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

関連項目：TRIGGERS.md（ツールキットを呼び出すもの）と GUI.md（ビジュアル製品設計計画。GUI は同梱されません。bucket-helper はリモートオブジェクトストレージの配管です）。

著者

• Warith HARCHAOUI

謝辞

実りある議論をしてくれた Mohamed Chelali と Bachir Zerroug に特別な感謝を捧げます。

ライセンス

このプロジェクトは BSD-3-Clause ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。