obstore

obstruir

Integración sencilla y rápida con servicios de almacenamiento de objetos como Amazon S3, Google Cloud Storage, Azure Blob Storage y API compatibles con S3 como Cloudflare R2.

• API de sincronización y asíncrona.
• Descargas en streaming con fragmentación configurable.
• list en streaming, sin necesidad de paginar.
• Soporte para colocación condicional ("poner si no existe"), así como etiquetas y atributos personalizados.
• Admite automáticamente cargas de varias partes bajo el capó para objetos de archivos grandes.
• Opcionalmente, devuelve los resultados de la lista como Flecha, que es más rápido que materializar objetos dict / list de Python.
• Fácil de instalar sin dependencias requeridas de Python.
• La biblioteca Rust subyacente es de calidad de producción y se utiliza en sistemas de producción a gran escala, como el registro de paquetes Rust crates.io.
• Soporte para el intercambio de datos sin copia de Rust a Python en get_range y get_ranges .
• API simple con verificación de tipo estático.
• Ayudantes para construir a partir de variables de entorno y objetos boto3.Session

Instalación

Para instalar obstore usando pip:

pip install obstore

Obstore está en conda-forge y se puede instalar usando conda, mamba o pixi. Para instalar obstore usando conda:

 conda install -c conda-forge obstore

Documentación

La documentación completa está disponible en el sitio web.

Uso

Construyendo una tienda

Las clases para construir una tienda se exportan desde el submódulo obstore.store :

• S3Store : configura una conexión a Amazon S3.
• GCSStore : configura una conexión a Google Cloud Storage.
• AzureStore : configure una conexión a Microsoft Azure Blob Storage.
• HTTPStore : configurar una conexión a un servidor HTTP genérico
• LocalStore : almacenamiento del sistema de archivos local que proporciona la misma interfaz de almacén de objetos.
• MemoryStore : una implementación totalmente en memoria de ObjectStore.

Ejemplo

 import boto3
from obstore . store import S3Store

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

Configuración

Cada clase de tienda anterior tiene su propia configuración, a la que se puede acceder a través del parámetro denominado config . Esto se trata en los documentos y los literales de cadena se encuentran en las sugerencias de tipo.

La configuración adicional del cliente HTTP está disponible a través del parámetro con nombre client_options .

Interactuando con una tienda

Todos los métodos para interactuar con una tienda se exportan como funciones de nivel superior (no métodos en el objeto store ):

• copy : copia un objeto de una ruta a otra en el mismo almacén de objetos.
• delete : elimina el objeto en la ubicación especificada.
• get : Devuelve los bytes que están almacenados en la ubicación especificada.
• head : Devuelve los metadatos para la ubicación especificada
• list : enumera todos los objetos con el prefijo dado.
• put : guarda los bytes proporcionados en la ubicación especificada
• rename : mueve un objeto de una ruta a otra en el mismo almacén de objetos.

Hay algunas API adicionales útiles para casos de uso específicos:

• get_range : obtiene un rango de bytes específico de un archivo.
• get_ranges : obtiene varios rangos de bytes de un solo archivo.
• list_with_delimiter : enumera objetos dentro de un directorio específico.
• sign : crea una URL firmada.

Todos los métodos tienen un método asíncrono comparable con el mismo nombre más un sufijo _async .

Ejemplo

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

Todos estos métodos también tienen contrapartes async , con el sufijo _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!" 

Comparación con object-store-python

Lea una comparación detallada con object-store-python , una biblioteca de Python anterior que también incluye la misma caja Rust object_store .