FileStore¶

The core orchestration class. Used as a FastAPI dependency.

Constructor¶

FileStore(
    name: str | None = None,
    *,
    count: int = 1,
    required: bool = False,
    fields: list[FileField] | None = None,
    engine: StorageEngine | None = None,
    config: StoreConfig | dict | None = None,
)

Parameter	Type	Default	Description
`name`	`str \\| None`	`None`	Shorthand for defining a single field
`count`	`int`	`1`	Maximum file count (single-field shorthand)
`required`	`bool`	`False`	Whether the field is required
`fields`	`list[FileField] \\| None`	`None`	Explicit list of field definitions
`engine`	`StorageEngine \\| None`	`LocalEngine()`	Default storage engine instance
`config`	`StoreConfig \\| dict \\| None`	`None`	Store-level configuration

Raises ConfigurationError at construction when no fields are defined, field names are duplicated, or engine is not a StorageEngine instance. Store/field configs are validated and merged once, up front.

Usage¶

Single Field¶

from filestore import FileStore, MemoryEngine

storage = FileStore("avatar", count=1, required=True, engine=MemoryEngine())

Multiple Fields¶

from filestore import FileField, FileStore, S3Engine

storage = FileStore(
    fields=[
        FileField(name="avatar", required=True),
        FileField(name="resume", engine=S3Engine(bucket="cvs")),
    ],
)

As a FastAPI Dependency¶

from fastapi import Depends
from filestore import Store

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

Attributes¶

Attribute	Type	Description
`fields`	`list[FileField]`	Configured upload fields
`config`	`StoreConfig`	Store-level configuration
`engine`	`StorageEngine`	Default engine instance

UploadContext¶

Every callback (filename, destination, metadata, filters) receives a single UploadContext:

Attribute	Type	Description
`request`	`Request`	The incoming request
`form`	`FormData`	The parsed multipart form
`field_name`	`str`	Name of the field being processed
`file`	`UploadFile`	The upload being processed

from filestore import UploadContext

async def namer(ctx: UploadContext) -> str:
    return f"{ctx.field_name}/{ctx.file.filename}"

FileModel Helper¶

Generate a Pydantic model that mirrors the configured fields — useful for documenting the multipart body in OpenAPI:

from filestore import FileModel

UploadForm = FileModel(storage)