lexigram-storage

Unified blob storage abstraction for Lexigram Framework — S3, GCS, Azure Blob, and local filesystem

Overview

lexigram-storage provides a unified BlobStore interface over Amazon S3, Google Cloud Storage, Azure Blob Storage, Cloudflare R2, and local disk — with signed URLs, streaming uploads, content-type negotiation, and server-side encryption. All services are wired via StorageProvider, which registers the blob store protocol with the DI container.

Full documentation: docs.lexigram.dev

Install

uv add lexigram-storage
# Optional extras
uv add "lexigram-storage[s3]"     # Amazon S3 (aiobotocore)
uv add "lexigram-storage[gcp]"    # Google Cloud Storage
uv add "lexigram-storage[azure]"  # Azure Blob Storage

Quick Start

from lexigram import Application
from lexigram.di.module import Module, module

# Import the module from the package
from lexigram.storage import StorageModule
from lexigram.storage.config import StorageConfig, StorageLocalConfig


@module(
    imports=[
        StorageModule.configure(
            StorageConfig(drivers={"local": StorageLocalConfig(root_dir="./storage")})
        )
    ]
)
class AppModule(Module):
    pass


async with Application.boot(modules=[AppModule]) as app:
    # use app.container to resolve services
    ...

Configuration

Zero-config usage: Call StorageModule.configure() with no arguments to use defaults.

Option 1 — YAML file

# application.yaml
storage:
  default_driver: "s3"
  drivers:
    s3:
      bucket: "my-app-uploads"
      region: "us-east-1"
      access_key: "${AWS_ACCESS_KEY_ID}"
      secret_key: "${AWS_SECRET_ACCESS_KEY}"

Option 2 — Profiles + Environment Variables (recommended)

export LEX_STORAGE__ENABLED=true
# Environment variables for each field

Option 3 — Python

from lexigram.storage.config import StorageConfig
from lexigram.storage import StorageModule

config = StorageConfig(default_driver="s3", ...)
StorageModule.configure(config)

Config reference

Module Factory Methods

Key Features

• S3 — Multi-part upload, server-side encryption, lifecycle rules
• GCS — Resumable uploads, CMEK, uniform bucket-level access
• Azure — Block blobs, shared access signatures (SAS), CDN integration
• R2 — Cloudflare R2 (S3-compatible) support
• Local driver — On-disk storage for development and CI
• Memory driver — In-process storage for unit tests
• Signed URLs — Time-limited GET / PUT pre-signed URLs for direct browser upload
• Content negotiation — Automatic MIME type detection from extension and magic bytes
• Key-value store — InMemoryKVStorage (memory) / LocalStorage (file) for small blobs (config, flags)
• Streaming — stream() yields chunks for arbitrarily large files

Testing

async with Application.boot(modules=[StorageModule.stub()]) as app:
    # your test code
    ...

Key Source Files