obstore

obscurcir

Intégration simple et rapide avec des services de stockage d'objets comme Amazon S3, Google Cloud Storage, Azure Blob Storage et des API compatibles S3 comme Cloudflare R2.

• API de synchronisation et asynchrone.
• Téléchargements en streaming avec segmentation configurable.
• list en streaming, sans avoir besoin de paginer.
• Prise en charge du put conditionnel (« mettre s'il n'existe pas »), ainsi que des balises et attributs personnalisés.
• Prend automatiquement en charge les téléchargements en plusieurs parties sous le capot pour les objets fichiers volumineux.
• Renvoie éventuellement les résultats de la liste sous forme de flèche, ce qui est plus rapide que la matérialisation d'objets Python dict / list .
• Facile à installer sans dépendances Python requises.
• La bibliothèque Rust sous-jacente est de qualité production et utilisée dans les systèmes de production à grande échelle, tels que le registre du package Rust crates.io.
• Prise en charge de l'échange de données sans copie de Rust vers Python dans get_range et get_ranges .
• API simple avec vérification de type statique.
• Aides pour la construction à partir de variables d'environnement et d'objets boto3.Session

Installation

Pour installer obstore à l'aide de pip :

pip install obstore

Obstore est sur conda-forge et peut être installé en utilisant conda, mamba ou pixi. Pour installer obstore à l'aide de conda :

 conda install -c conda-forge obstore

Documentation

La documentation complète est disponible sur le site Internet.

Usage

Construire un magasin

Les classes pour construire un magasin sont exportées depuis le sous-module obstore.store :

• S3Store : Configurez une connexion à Amazon S3.
• GCSStore : Configurez une connexion à Google Cloud Storage.
• AzureStore : configurez une connexion à Microsoft Azure Blob Storage.
• HTTPStore : Configurer une connexion à un serveur HTTP générique
• LocalStore : stockage du système de fichiers local fournissant la même interface de magasin d'objets.
• MemoryStore : une implémentation entièrement en mémoire d'ObjectStore.

Exemple

 import boto3
from obstore . store import S3Store

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

Configuration

Chaque classe de magasin ci-dessus a sa propre configuration, accessible via le paramètre config nommé. Ceci est couvert dans la documentation et les littéraux de chaîne se trouvent dans les astuces de type.

Une configuration supplémentaire du client HTTP est disponible via le paramètre nommé client_options .

Interagir avec un magasin

Toutes les méthodes permettant d'interagir avec un magasin sont exportées en tant que fonctions de niveau supérieur (et non en tant que méthodes sur l'objet store ) :

• copy : Copie un objet d'un chemin à un autre dans le même magasin d'objets.
• delete : supprime l’objet à l’emplacement spécifié.
• get : Renvoie les octets stockés à l’emplacement spécifié.
• head : renvoie les métadonnées pour l'emplacement spécifié
• list : Répertorie tous les objets avec le préfixe donné.
• put : enregistre les octets fournis à l'emplacement spécifié
• rename : Déplacer un objet d'un chemin à un autre dans le même magasin d'objets.

Il existe quelques API supplémentaires utiles pour des cas d'utilisation spécifiques :

• get_range : Obtenez une plage d'octets spécifique à partir d'un fichier.
• get_ranges : obtenez plusieurs plages d'octets à partir d'un seul fichier.
• list_with_delimiter : Liste les objets dans un répertoire spécifique.
• sign : Créez une URL signée.

Toutes les méthodes ont une méthode asynchrone comparable avec le même nom plus un suffixe _async .

Exemple

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

Toutes ces méthodes ont également des équivalents async , suffixés par _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!" 

Comparaison avec le magasin d'objets-python

Lisez une comparaison détaillée avec object-store-python , une bibliothèque Python précédente qui enveloppe également la même caisse Rust object_store .