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, вместо вложенного дерева папок на жёстком диске: ничего не нужно создавать заранее, нет ограничений на количество файлов в одном месте, и каждый объект доступен напрямую по 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 вместо S3 используйте sftp-helper; для загрузки медиа по URL — youtube-helper.

Эта удалённая доступность также означает, что «проверено в бою» должно быть чем-то проверяемым, а не лозунгом. Каждый push проходит блокирующий CI-шлюз: тестовый набор проверяет S3-клиент против мок-бэкенда moto, затем ruff проверяет стиль; ничего не попадает в main при красном прогоне. Пакет выпущен через девять семантически версионированных релизов на PyPI, от v0.2.2 до текущего v1.1.2 (историю тегов можно посмотреть с помощью git tag). Он зависит от os-helper — небольшого базового пакета, который весь набор AI Helpers использует для логирования и работы с файлами; здесь ничего не изобретается заново.

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 для сценариев «загрузи и поделись»: загрузка, возврат объекта, автоматическое удаление при выходе из блока, без ручной очистки.

• Три поверхности, одно поведение: библиотека Python, argparse CLI, click CLI (дополнение [cli]) и HTTP-поверхность FastAPI (дополнение [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]"

Аргументный 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

Вы также можете написать JSON вместо YAML, использовать .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"
}

Необязательные ключи:

URL конечных точек для распространённых S3-совместимых хранилищ

Установите s3_endpoint_url:

Использование

Полный каталог рецептов (загрузки / скачивания / списки, S3-совместимые конечные точки, такие как MinIO / R2 / B2 / Spaces / Wasabi, временные удалённые ключи с автоматической очисткой, зеркалирование с 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

Учётные данные для каждого запроса также можно отправлять как поля 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

См. также: TRIGGERS.md (что вызывает инструментарий) и GUI.md (план визуального дизайна продукта; GUI не поставляется, bucket-helper — это удалённая объектная инфраструктура).

Автор

• Warith HARCHAOUI

Благодарности

Особая благодарность Mohamed Chelali и Bachir Zerroug за плодотворные обсуждения.

Лицензия

Этот проект лицензирован по лицензии BSD-3-Clause; см. файл LICENSE.