obstore

obstruir

Integração simples e rápida com serviços de armazenamento de objetos, como Amazon S3, Google Cloud Storage, Azure Blob Storage e APIs compatíveis com S3, como Cloudflare R2.

• API de sincronização e assíncrona.
• Streaming de downloads com chunking configurável.
• list de streaming, sem necessidade de paginação.
• Suporte para colocação condicional ("colocar se não existir"), bem como tags e atributos personalizados.
• Suporta automaticamente multipart uploads nos bastidores para objetos de arquivo grandes.
• Opcionalmente, retorne os resultados da lista como Arrow, o que é mais rápido do que materializar objetos dict / list do Python.
• Fácil de instalar, sem dependências Python necessárias.
• A biblioteca Rust subjacente é de qualidade de produção e usada em sistemas de produção em larga escala, como o registro de pacotes Rust crates.io.
• Suporte para troca de dados de cópia zero de Rust para Python em get_range e get_ranges .
• API simples com verificação de tipo estático.
• Auxiliares para construção a partir de variáveis ​​de ambiente e objetos boto3.Session

Instalação

Para instalar o obsstore usando pip:

pip install obstore

Obstore está no conda-forge e pode ser instalado usando conda, mamba ou pixi. Para instalar o obsstore usando conda:

 conda install -c conda-forge obstore

Documentação

A documentação completa está disponível no site.

Uso

Construindo uma loja

As classes para construir uma loja são exportadas do submódulo obstore.store :

• S3Store : configure uma conexão com o Amazon S3.
• GCSStore : configure uma conexão com o Google Cloud Storage.
• AzureStore : Configure uma conexão com o Armazenamento de Blobs do Microsoft Azure.
• HTTPStore : Configure uma conexão com um servidor HTTP genérico
• LocalStore : armazenamento de sistema de arquivos local que fornece a mesma interface de armazenamento de objetos.
• MemoryStore : uma implementação totalmente na memória do ObjectStore.

Exemplo

 import boto3
from obstore . store import S3Store

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

Configuração

Cada classe de loja acima possui sua própria configuração, acessível através do parâmetro denominado config . Isso é abordado na documentação e os literais de string estão nas dicas de tipo.

A configuração adicional do cliente HTTP está disponível por meio do parâmetro nomeado client_options .

Interagindo com uma loja

Todos os métodos para interagir com uma loja são exportados como funções de nível superior (não métodos no objeto store ):

• copy : Copia um objeto de um caminho para outro no mesmo armazenamento de objetos.
• delete : exclui o objeto no local especificado.
• get : retorna os bytes armazenados no local especificado.
• head : Retorna os metadados para o local especificado
• list : lista todos os objetos com o prefixo fornecido.
• put : salva os bytes fornecidos no local especificado
• rename : mova um objeto de um caminho para outro no mesmo armazenamento de objetos.

Existem algumas APIs adicionais úteis para casos de uso específicos:

• get_range : obtém um intervalo de bytes específico de um arquivo.
• get_ranges : Obtenha vários intervalos de bytes de um único arquivo.
• list_with_delimiter : lista objetos em um diretório específico.
• sign : crie um URL assinado.

Todos os métodos possuem um método assíncrono comparável com o mesmo nome mais um sufixo _async .

Exemplo

 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 esses métodos também possuem contrapartes async , sufixadas com _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!" 

Comparação com object-store-python

Leia uma comparação detalhada com object-store-python , uma biblioteca Python anterior que também envolve a mesma caixa Rust object_store .