Flask-Files

Uploaded files management based on fsspec.

Installation

pip install flask-files

Store uploaded files

Use save_file() to store a Flask file object from request.files. This function returns a File object. Store the value of the File.uri property to later access the file.

from flask import Flask
from flask_files import Files, save_file

app = Flask(__name__)
Files(app)

@app.post("/")
def index():
    file = save_file(request.files["file"])
    print(file.uri)

By default, files are saved to disk prefixed with a UUID.

Validate files from forms

You should validate uploaded files using validate_file(). It will raised a BadRequest error on validation failure.

from flask_files import validate_file

@app.post("/")
def index():
    validate_file(request.files["file"], allowed_exts=[".pdf"], max_size=1024**10)

Use the flask_files.images.IMAGE_EXTS constant for a list of common image extensions.

Serve uploaded files

Use url_for_upload() in combination with the URI stored after saving the file to obtain a public URL for your file.

<img src="{{ url_for_upload(file_or_uri) }}">

You can also re-build a File object from a URI using File.from_uri(uri).

Storage file systems

Flask-Files is built on top of fsspec, allowing it to use any fssspec file system. Compatible file systems must allow write operations.

File systems can allow custom url generation if they provide a url() method (like s3fs).

The default backend can be modified using the FILES_DEFAULT_FILESYSTEM option.

Multiple backends can be used at once by providing the protocol parameter to save_file().

Per filesystem options can be provided in the configuration

FILES_FILESYSTEMS={
    "local": {
        "subfolders": True
    },
    "s3": {
        "endpoint_url": "https://alternative-service.com"
    }
}

You can also use the same filesystem multiple times with different configurations:

FILES_FILESYSTEMS={
    "bucket1": {
        "protocol": "s3",
        "base_path": "bucket1"
    },
    "bucket2": {
        "protocol": "s3",
        "base_path": "bucket2"
    }
}

save_file(file, protocol="bucket1")
save_file(file, protocol="bucket2")

Using S3

To store files on S3 (or compatible services), setup your AWS credentials as env variables and configure your app as follow:

FILES_DEFAULT_FILESYSTEM="s3"
FILES_BASE_PATH="bucket_name"

Manipulate images

Flask-Files provides functions to manipulate images. They can be chained. The returned image must be stored using save_file().

from flask_files.images import IMAGE_EXTS, create_thumbnail

@app.post("/")
def index():
    validate_file(request.files["file"], IMAGE_EXTS)
    file = save_file(request.files["file"])
    thumb = save_file(create_thumbail(file, 100))

File object

The file object is a serializable object that holds information about a file.

It is serializable as string (uri) or JSON.

The stringified representation of a file object is its URL.

Configuration

Configuration for file systems: