litestar-storages

Welcome to litestar-storages, an async-first file storage abstraction library for Python with optional Litestar integration.

What is litestar-storages?

litestar-storages provides a unified, async-native interface for storing and retrieving files across multiple storage backends. Whether you need to store user uploads on the local filesystem, serve media from AWS S3, or use Cloudflare R2 for edge distribution, litestar-storages gives you a consistent API that works the same way everywhere.

The core library is framework-agnostic - use it with any async Python application, including FastAPI, Starlette, Quart, or plain asyncio. Litestar integration is provided as an optional plugin.

from litestar_storages import S3Storage, S3Config

storage = S3Storage(S3Config(bucket="my-uploads"))

# Store a file
await storage.put("photos/vacation.jpg", image_data)

# Get a presigned URL
url = await storage.url("photos/vacation.jpg", expires_in=timedelta(hours=1))

Key Features

Framework-Agnostic Core

The storage backends work with any async Python application. No framework dependencies required for the core functionality - just install and use with plain asyncio:

Note

Yes, we know. A library called “litestar-storages” that doesn’t require Litestar. We considered renaming it to “asyncio-storages-that-also-works-great-with-litestar-but-you-do-you” but that didn’t fit on the PyPI page. The name is a tribute to our roots, not a requirement for your imports.

import asyncio
from litestar_storages import FileSystemStorage, FileSystemConfig
from pathlib import Path

async def main():
    storage = FileSystemStorage(FileSystemConfig(path=Path("./uploads")))
    await storage.put("hello.txt", b"Hello, World!")
    content = await storage.get_bytes("hello.txt")
    print(content.decode())

asyncio.run(main())

Async-Native Design

Built from the ground up for Python’s async/await paradigm. Unlike django-storages (sync) or fastapi-storages (sync despite the name), every operation in litestar-storages is truly asynchronous.

Multiple Storage Backends

  • FileSystemStorage: Local filesystem storage with optional URL generation

  • S3Storage: Amazon S3 and S3-compatible services (Cloudflare R2, DigitalOcean Spaces, MinIO, Backblaze B2)

  • GCSStorage: Google Cloud Storage with signed URLs and ADC support

  • AzureStorage: Azure Blob Storage with SAS URLs and managed identity

  • MemoryStorage: In-memory storage for testing and development

Optional Litestar Integration

The StoragePlugin provides seamless integration with Litestar applications (requires the litestar extra):

  • Dependency injection: Storage instances injected directly into route handlers

  • Lifespan management: Automatic connection cleanup on application shutdown

  • Multiple storages: Named storages for different use cases (uploads, images, documents)

Type-Safe Protocol Design

A well-defined Storage protocol ensures all backends behave consistently:

@runtime_checkable
class Storage(Protocol):
    async def put(self, key: str, data: bytes, ...) -> StoredFile: ...
    async def get(self, key: str) -> AsyncIterator[bytes]: ...
    async def delete(self, key: str) -> None: ...
    async def exists(self, key: str) -> bool: ...
    async def list(self, prefix: str = "") -> AsyncIterator[StoredFile]: ...
    async def url(self, key: str, *, expires_in: timedelta | None = None) -> str: ...

Streaming Support

Handle large files efficiently without loading them entirely into memory:

# Stream download
async for chunk in storage.get("large-file.zip"):
    await response.write(chunk)

# Stream upload from async iterator
await storage.put("large-file.zip", async_chunk_generator())

Comparison with Litestar Stores

Litestar includes built-in stores for key-value data. These serve a different purpose than litestar-storages:

Aspect

litestar-storages

Litestar Stores

Purpose

File storage (uploads, media assets)

Key-value data (caching, sessions)

Data type

Binary files with metadata

Serialized values with TTL

Typical use

User uploads, CDN assets, documents

Sessions, rate limiting, caching

Backends

FileSystem, S3, GCS, Azure, Memory

Memory, File, Redis, Valkey

TTL support

No (files are persistent)

Yes (automatic expiration)

Metadata

Yes (content-type, size, custom)

No

Presigned URLs

Yes (for cloud backends)

No

Use litestar-storages when you need to:

  • Accept file uploads from users

  • Store and serve media assets (images, videos, documents)

  • Generate secure download URLs

  • Manage files across cloud providers

Use Litestar Stores when you need to:

  • Cache computed values

  • Store session data

  • Implement rate limiting

  • Store ephemeral data with automatic expiration

Documentation Contents

Getting Started

Storage Backends

Advanced Topics

Cookbook

Reference