Skip to content

filestore

File upload dependency and storage toolkit for FastAPI

PyPI version Python versions Package status CI Docs License Ruff Typed

filestore is a FastAPI upload library with a simple dependency-based API and production-grade defaults. It keeps the happy path short, but adds the things real services usually need.

Features

  • Pluggable Storage Engines

    Local filesystem, in-memory, Amazon S3, Google Cloud Storage, and Azure Blob Storage — all behind one interface.

  • Presigned URLs

    Mint presigned upload and download URLs for S3, GCS, and Azure so clients transfer files directly to cloud storage.

  • Built-in Validation

    Validate file size, extension, and content type out of the box. Add custom filter callbacks for application-specific rules.

  • Sync & Async Callbacks

    Dynamically resolve filenames, destinations, filters, and metadata with sync or async callables.

  • Multi-Field Support

    Handle multiple upload fields in a single request, each with its own configuration — and even its own storage engine.

  • Pydantic Results

    Store and FileData are Pydantic models. Return them straight from a route and FastAPI serializes them for you.

Quick Example

from fastapi import Depends, FastAPI
from filestore import FileStore, LocalEngine, Store

app = FastAPI()

storage = FileStore(
    "file",
    required=True,
    engine=LocalEngine(base_dir="uploads", base_url="/media"),
)


@app.post("/upload")
async def upload(store: Store = Depends(storage)) -> Store:
    return store

That's it. Uploads are validated, written atomically to disk, collision-free by default, and the result is a ready-to-serialize Pydantic model.

Next Steps