obstore

скрывать

Простая и быстрая интеграция со службами хранения объектов, такими как Amazon S3, Google Cloud Storage, Azure Blob Storage и API-интерфейсами, совместимыми с S3, такими как Cloudflare R2.

• Синхронный и асинхронный API.
• Потоковая загрузка с настраиваемым фрагментированием.
• list потоковой передачи без необходимости разбивки на страницы.
• Поддержка условного размещения («помещать, если не существует»), а также пользовательских тегов и атрибутов.
• Автоматически поддерживает многочастную загрузку больших файловых объектов.
• При необходимости возвращайте результаты списка в виде стрелки, что быстрее, чем материализация объектов dict / list Python.
• Легко установить без каких-либо необходимых зависимостей Python.
• Базовая библиотека Rust является производственной и используется в крупномасштабных производственных системах, таких как реестр пакетов Rust crates.io.
• Поддержка обмена данными без копирования из Rust в Python в get_range и get_ranges .
• Простой API со статической проверкой типов.
• Помощники для построения из переменных среды и объектов boto3.Session

Установка

Чтобы установить obstore с помощью pip:

pip install obstore

Obstore находится на conda-forge и может быть установлен с помощью conda, mamba или pixi. Чтобы установить obstore с помощью conda:

 conda install -c conda-forge obstore

Документация

Полная документация доступна на сайте.

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

Строительство магазина

Классы для создания хранилища экспортируются из подмодуля obstore.store :

• S3Store : настройка подключения к Amazon S3.
• GCSStore : настройка подключения к облачному хранилищу Google.
• AzureStore : настройка подключения к хранилищу BLOB-объектов Microsoft Azure.
• HTTPStore : настройка подключения к общему HTTP-серверу.
• LocalStore : локальное хранилище файловой системы, предоставляющее тот же интерфейс хранилища объектов.
• MemoryStore : реализация ObjectStore, полностью размещаемая в памяти.

Пример

 import boto3
from obstore . store import S3Store

session = boto3 . Session ()
store = S3Store . from_session ( session , "bucket-name" , config = { "AWS_REGION" : "us-east-1" })

Конфигурация

Каждый класс магазина, указанный выше, имеет свою собственную конфигурацию, доступную через параметр с именем config . Это описано в документации, а строковые литералы находятся в подсказках по типам.

Дополнительная конфигурация HTTP-клиента доступна через именованный параметр client_options .

Взаимодействие с магазином

Все методы взаимодействия с магазином экспортируются как функции верхнего уровня (а не методы объекта store ):

• copy : копировать объект с одного пути на другой в том же хранилище объектов.
• delete : удалить объект в указанном месте.
• get : Возвращает байты, хранящиеся в указанном месте.
• head : вернуть метаданные для указанного местоположения.
• list : перечислить все объекты с заданным префиксом.
• put : сохранить предоставленные байты в указанное место.
• rename : переместить объект с одного пути на другой в том же хранилище объектов.

Есть несколько дополнительных API, полезных для конкретных случаев использования:

• get_range : получить определенный диапазон байтов из файла.
• get_ranges : получить несколько диапазонов байтов из одного файла.
• list_with_delimiter : список объектов в определенном каталоге.
• sign : Создайте подписанный URL-адрес.

Все методы имеют аналогичный асинхронный метод с тем же именем и суффиксом _async .

Пример

 import obstore as obs

store = obs . store . MemoryStore ()

obs . put ( store , "file.txt" , b"hello world!" )
response = obs . get ( store , "file.txt" )
response . meta
# {'path': 'file.txt',
#  'last_modified': datetime.datetime(2024, 10, 21, 16, 19, 45, 102620, tzinfo=datetime.timezone.utc),
#  'size': 12,
#  'e_tag': '0',
#  'version': None}
assert response . bytes () == b"hello world!"

byte_range = obs . get_range ( store , "file.txt" , offset = 0 , length = 5 )
assert byte_range == b"hello"

obs . copy ( store , "file.txt" , "other.txt" )
assert obs . get ( store , "other.txt" ). bytes () == b"hello world!"

Все эти методы также имеют async аналоги с суффиксом _async .

 import obstore as obs

store = obs . store . MemoryStore ()

await obs . put_async ( store , "file.txt" , b"hello world!" )
response = await obs . get_async ( store , "file.txt" )
response . meta
# {'path': 'file.txt',
#  'last_modified': datetime.datetime(2024, 10, 21, 16, 20, 36, 477418, tzinfo=datetime.timezone.utc),
#  'size': 12,
#  'e_tag': '0',
#  'version': None}
assert await response . bytes_async () == b"hello world!"

byte_range = await obs . get_range_async ( store , "file.txt" , offset = 0 , length = 5 )
assert byte_range == b"hello"

await obs . copy_async ( store , "file.txt" , "other.txt" )
resp = await obs . get_async ( store , "other.txt" )
assert await resp . bytes_async () == b"hello world!" 

Сравнение с объектным хранилищем Python

Прочтите подробное сравнение с object-store-python , предыдущей библиотекой Python, которая также является оболочкой того же крейта object_store в Rust.