StoreConfig¶

A validated Pydantic model accepted by FileStore and FileField. Plain dicts are coerced automatically; Config is kept as an alias.

from filestore import StoreConfig

config = StoreConfig(
    destination="uploads",
    max_file_size=5 * 1024 * 1024,
    allowed_extensions=[".jpg", ".png"],
)

General Keys¶

Key	Type	Default	Description
`destination`	`str \\| Path \\| callback`	Engine default	Upload directory or cloud key prefix
`filename`	`str \\| Path \\| callback`	Original name	Override stored filename
`filters`	`list[callback] \\| callback`	`[]`	Filter callbacks
`metadata`	`dict \\| callback`	`{}`	Extra per-file metadata
`extra_args`	`dict`	`{}`	Extra kwargs for the backend upload call

Callbacks receive an UploadContext and may be sync or async.

Validation Keys¶

Key	Type	Default	Description
`max_file_size`	`int \\| None`	`None`	Maximum file size in bytes (≥ 0)
`min_file_size`	`int \\| None`	`None`	Minimum file size in bytes (≥ 0)
`allowed_extensions`	`list[str] \\| str`	All	Allowed extensions, normalized to `.ext` lowercase
`allowed_content_types`	`list[str] \\| str`	All	Allowed MIME types, lowercased

Multipart Parsing Keys (store level)¶

Key	Type	Default	Description
`max_files`	`int`	`1000`	Max files in multipart body
`max_fields`	`int`	`1000`	Max fields in multipart body
`max_part_size`	`int`	`1048576`	Max part size in bytes

Behaviour Keys¶

Key	Type	Default	Description
`chunk_size`	`int`	`1048576`	Local read/write chunk size (≥ 1)
`overwrite`	`bool`	`False`	Allow overwriting existing objects
`sanitize_filename`	`bool`	`True`	Replace unsafe filename characters
`base_url`	`str \\| None`	`None`	Public URL prefix (local engine)

Validation Behaviour¶

StoreConfig validates on construction:

Extensions are normalized — "PNG", ".png", and " .Png " all become ".png".
Content types are lowercased and stripped.
A single callable passed to filters is wrapped into a list.
min_file_size > max_file_size raises a ValidationError.
Negative sizes and zero chunk sizes are rejected.

Merging¶

merged_with(override) returns a new config with the override's explicitly set keys applied on top; filters are concatenated instead of replaced:

base = StoreConfig(max_file_size=100, overwrite=True)
merged = base.merged_with({"max_file_size": 50})
merged.max_file_size  # 50
merged.overwrite      # True  (not reset to the default)

FileStore performs this merge for every field once, at construction time.

Engine settings moved

Backend settings (AWS_*, GCP_*, AZURE_*, endpoint_url) are no longer config keys — they are engine constructor arguments.