Configuration Reference¶

Complete reference for StoreConfig and engine constructor options.

How Configuration Works¶

Upload behaviour is configured with StoreConfig, a validated Pydantic model. Backend settings (buckets, containers, credentials, endpoints) live on the engine constructors instead.

StoreConfig can be set at two levels:

Store level — applies to all fields as a baseline
Field level — overrides the store level for that specific field

from filestore import FileField, FileStore, StoreConfig

storage = FileStore(
    fields=[
        FileField(
            name="avatar",
            config=StoreConfig(max_file_size=2 * 1024 * 1024),  # Field override
        ),
    ],
    config=StoreConfig(max_file_size=10 * 1024 * 1024),  # Store baseline
)

A plain dict is accepted anywhere a StoreConfig is — it is validated on construction. Config is kept as an alias of StoreConfig.

Filter merging

Filters are the one exception to key-by-key overriding — store-level and field-level filters are concatenated, not overridden. Store filters run first.

Validated up front

StoreConfig is validated when the FileStore is constructed: extensions are normalized (leading dot optional, case-insensitive), size bounds are checked (min_file_size cannot exceed max_file_size), and store/field configs are merged once at startup, not per request.

StoreConfig Keys¶

General¶

Key	Type	Default	Description
`destination`	`str \\| Path \\| callback`	Engine default	Upload directory (local) or key prefix (cloud). Callback receives an `UploadContext`.
`filename`	`str \\| Path \\| callback`	Original	Override stored filename. Callback receives an `UploadContext`.
`filters`	`list[callback] \\| callback`	`[]`	One or more filter callbacks. Return `True` to accept, `False` or a string to reject.
`metadata`	`dict \\| callback`	`{}`	Static metadata dict or callback. Merged into `FileData.metadata`.
`extra_args`	`dict`	`{}`	Extra kwargs passed to the backend upload call (e.g. S3 `put_object()` kwargs).

Validation¶

Key	Type	Default	Description
`max_file_size`	`int`	Unlimited	Maximum file size in bytes.
`min_file_size`	`int`	`None`	Minimum file size in bytes.
`allowed_extensions`	`list[str] \\| str`	All	Allowed file extensions. Case-insensitive, leading dot optional.
`allowed_content_types`	`list[str] \\| str`	All	Allowed MIME types. Case-insensitive.

Multipart Parsing (store level)¶

Key	Type	Default	Description
`max_files`	`int`	`1000`	Maximum number of files in the multipart body.
`max_fields`	`int`	`1000`	Maximum number of form fields.
`max_part_size`	`int`	`1048576`	Maximum size of a single multipart part (bytes).

Behaviour¶

Key	Type	Default	Description
`chunk_size`	`int`	`1048576`	Local read/write chunk size in bytes.
`overwrite`	`bool`	`False`	Allow overwriting existing objects. Local storage adds a numeric suffix when `False`; GCS uses `if_generation_match=0`.
`sanitize_filename`	`bool`	`True`	Replace unsafe characters (`[^A-Za-z0-9._-]`) with underscores and strip traversal segments.
`base_url`	`str`	`None`	Public URL prefix for local files. When set, `FileData.url` is populated.

Engine Options¶

Engine-specific settings are constructor arguments, configured once when you create the engine:

LocalEngine¶

Argument	Default	Description
`base_dir`	Current directory	Directory used when config has no `destination`; also the root for `delete()`.
`base_url`	`None`	Default public URL prefix (config `base_url` wins).

S3Engine¶

Argument	Env fallback	Description
`bucket`	`AWS_BUCKET_NAME`	Required. Target bucket.
`region`	`AWS_DEFAULT_REGION`	AWS region.
`endpoint_url`	—	Custom endpoint for S3-compatible services (MinIO, LocalStack, R2).
`client`	—	Pre-built boto3 S3 client; overrides all other options.

Credentials resolve through the standard boto3 chain (env vars, ~/.aws/credentials, IAM roles).

GCSEngine¶

Argument	Env fallback	Description
`bucket`	`GCP_BUCKET_NAME`	Required. Target bucket.
`project`	`GCP_PROJECT` / `GOOGLE_CLOUD_PROJECT`	Google Cloud project ID.
`credentials`	ADC	Explicit credentials object. Signed URLs require a private key (service account).
`endpoint_url`	—	Custom API endpoint for emulators.
`client`	—	Pre-built `storage.Client`; overrides all other options.

AzureBlobEngine¶

Argument	Env fallback	Description
`container`	`AZURE_STORAGE_CONTAINER`	Required. Blob container name.
`connection_string`	`AZURE_STORAGE_CONNECTION_STRING`	Connection-string authentication.
`account_url`	`AZURE_STORAGE_ACCOUNT_URL`	Account URL; uses `DefaultAzureCredential` when no credential is given.
`credential`	—	Explicit credential for `account_url` authentication.
`client`	—	Pre-built `BlobServiceClient`; overrides other options.