Store

Aggregated response for all processed upload fields. This is the object returned by the FastAPI dependency. A Pydantic model — return it directly from a route.

Fields

Field	Type	Description
files	dict[str, list[FileData]]	Per-field file results
status	UploadStatus	Aggregate outcome: "completed", "partial", "failed", or "empty"
message	str	Summary status message
errors	list[str]	All error messages (deduplicated)

UploadStatus

A StrEnum — members compare equal to their string values and serialize as strings:

Member	Value	Meaning
UploadStatus.COMPLETED	"completed"	Every file persisted successfully
UploadStatus.PARTIAL	"partial"	Some files succeeded, some failed
UploadStatus.FAILED	"failed"	Files submitted or errors collected, none succeeded
UploadStatus.EMPTY	"empty"	No files were submitted

Computed / Properties

Property	Type	Description
error	str \| None	First error message (included in serialized output)
flat_files	list[FileData]	All files in a single list
successful_files	list[FileData]	Only files with status=True
failed_files	list[FileData]	Only files with status=False
total_files	int	Total file count
total_size	int	Sum of sizes for successful files

bool(store) is True only when status is UploadStatus.COMPLETED. Don't truth-test store.status itself — a non-empty enum string is always truthy.

Methods

first(field_name)

store.first("avatar")  # FileData | None

add(file_data)

store.add(file_data)  # Append a FileData and collect its error

finalize()

Computes status and message from the collected results. Called automatically by FileStore — you only need it when assembling a Store manually. The verdict:

• no files, no errors → EMPTY
• no files, errors collected → FAILED
• successes and failures/errors → PARTIAL
• only failures/errors → FAILED
• only successes → COMPLETED

Serialization

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

store.model_dump(mode="json")   # plain dict when you need one

Raw bytes held by memory-engine results are never included in serialized output.