Flask-Reuploaded

Flask-Reuploaded allows your application to flexibly and efficiently handle file uploading and serving the uploaded files. You can create different sets of uploads - one for document attachments, one for photos, etc. - and the application can be configured to save them all in different places and to generate different URLs for them.

Installation

$ pip install Flask-Reuploaded

Getting started

create an UploadSet

from flask_uploads import IMAGES

photos = UploadSet("photos", IMAGES)

configure your Flask app and this extension

app.config["UPLOADED_PHOTOS_DEST"] = "static/img"
app.config["SECRET_KEY"] = os.urandom(24)
configure_uploads(app, photos)

use photos in your view function

photos.save(request.files['photo'])

Please have a look at the project’s README file for a complete working example application.

Configuration

If you’re just deploying an application that uses Flask-Reuploaded, you can customize its behavior extensively from the application’s configuration. Check the application’s documentation or source code to see how it loads its configuration.

The settings below apply for a single set of uploads, replacing FILES with the name of the set (i.e. PHOTOS, ATTACHMENTS):

UPLOADED_FILES_DEST

This indicates the directory uploaded files will be saved to.

UPLOADED_FILES_URL

If you have a server set up to serve the files in this set, this should be the URL they are publicly accessible from. Include the trailing slash.

UPLOADED_FILES_ALLOW

This lets you allow file extensions not allowed by the upload set in the code.

UPLOADED_FILES_DENY

This lets you deny file extensions allowed by the upload set in the code.

To save on configuration time, there are two settings you can provide that apply as “defaults” if you don’t provide the proper settings otherwise.

UPLOADS_DEFAULT_DEST

If you set this, then if an upload set’s destination isn’t otherwise declared, then its uploads will be stored in a subdirectory of this directory. For example, if you set this to /var/uploads, then a set named photos will store its uploads in /var/uploads/photos.

UPLOADS_DEFAULT_URL

If you have a server set up to serve from UPLOADS_DEFAULT_DEST, then set the server’s base URL here. Continuing the example above, if /var/uploads is accessible from http://localhost:5001, then you would set this to http://localhost:5001/ and URLs for the photos set would start with http://localhost:5001/photos. Include the trailing slash.

If you want to serve the uploaded files via http, and you expect heavy traffic, you should think about serving the files directly by a web/proxy server as e.g. Nginx.

By default Flask doesn’t put any limits on the size of the uploaded data. To limit the max upload size, you can use Flask’s MAX_CONTENT_LENGTH.

UPLOADS_AUTOSERVE

This turns AUTOSERVE on or off via True or False. AUTOSERVE enables automatic viewing/downloading of uploaded files. When the name of the UploadSet is photos and the name of the uploaded file is snow.jpg, the file is available via http://localhost:5000/_uploads/photos/snow.jpg. In order to stay compatible with Flask-Uploads, for Flask-Reuploaded < 1.0.0 UPLOADS_AUTOSERVE defaulted to True. Since version 1.0.0 UPLOADS_AUTOSERVE defaults to False, as this feature is a bit of a surprise, as it was undocumented for a long time.

Upload Sets

An UploadSet is a single collection of files. You just declare them in the code:

photos = UploadSet('photos', IMAGES)

And then you can use the UploadSet.save method to save uploaded files and UploadSet.path and UploadSet.url to access them. For example:

@app.route('/upload', methods=['GET', 'POST'])
def upload():
    if request.method == 'POST' and 'photo' in request.files:
        filename = photos.save(request.files['photo'])
        rec = Photo(filename=filename, user=g.user.id)
        rec.store()
        flash("Photo saved.")
        return redirect(url_for('show', id=rec.id))
    return render_template('upload.html')

@app.route('/photo/<id>')
def show(id):
    photo = Photo.load(id)
    if photo is None:
        abort(404)
    url = photos.url(photo.filename)
    return render_template('show.html', url=url, photo=photo)

If you have a “default location” for storing uploads - for example, if your app has an “instance” directory and uploads should be saved to the instance directory’s uploads folder - you can pass a default_dest callable to the set constructor. It takes the application as its argument. For example:

media = UploadSet('media', default_dest=lambda app: app.instance_path)

This won’t prevent a different destination from being set in the config, though. It’s just to save your users a little configuration time.

App Configuration

An UploadSet’s configuration is stored on an app. That way, you can have upload sets being used by multiple apps at once. You use the configure_uploads function to load the configuration for the UploadSet`s. You pass in the app and all of the `UploadSet`s you want configured. Calling `configure_uploads more than once is safe.

configure_uploads(app, (photos, media))

If your app has a factory function, that is a good place to call this function.

File Upload Forms

To actually upload the files, you need to properly set up your form. A form that uploads files needs to have its method set to POST and its enctype set to multipart/form-data. If it’s set to GET, it won’t work at all, and if you don’t set the enctype, only the filename will be transferred.

The field itself should be an <input type=file>.

<form method=POST enctype=multipart/form-data action="{{ url_for('upload') }}">
    ...
    <input type=file name=photo>
    ...
</form>

API Documentation

This documentation is generated directly from the source code.

Upload Sets

class flask_uploads.UploadSet(name: str = 'files', extensions: Iterable[str] = ('txt', 'rtf', 'odf', 'ods', 'gnumeric', 'abw', 'doc', 'docx', 'xls', 'xlsx', 'pdf', 'jpg', 'jpe', 'jpeg', 'png', 'gif', 'svg', 'bmp', 'webp', 'csv', 'ini', 'json', 'plist', 'xml', 'yaml', 'yml'), default_dest: Optional[Callable[[flask.app.Flask], str]] = None)

This represents a single set of uploaded files. Each upload set is independent of the others. This can be reused across multiple application instances, as all configuration is stored on the application object itself and found with flask.current_app.

Parameters
  • name – The name of this upload set. It defaults to files, but you can pick any alphanumeric name you want. (For simplicity, it’s best to use a plural noun.)

  • extensions – The extensions to allow uploading in this set. The easiest way to do this is to add together the extension presets (for example, TEXT + DOCUMENTS + IMAGES). It can be overridden by the configuration with the UPLOADED_X_ALLOW and UPLOADED_X_DENY configuration parameters. The default is DEFAULTS.

  • default_dest – If given, this should be a callable. If you call it with the app, it should return the default upload destination path for that app.

property config: flask_uploads.flask_uploads.UploadConfiguration

This gets the current configuration. By default, it looks up the current application and gets the configuration from there. But if you don’t want to go to the full effort of setting an application, or it’s otherwise outside of a request context, set the _config attribute to an UploadConfiguration instance, then set it back to None when you’re done.

extension_allowed(ext: str) bool

This determines whether a specific extension is allowed. It is called by file_allowed, so if you override that but still want to check extensions, call back into this.

Parameters

ext – The extension to check, without the dot.

file_allowed(storage: werkzeug.datastructures.FileStorage, basename: str) bool

This tells whether a file is allowed.

It should return True if the given werkzeug.datastructures.FileStorage object can be saved with the given basename, and False if it can’t.

The default implementation just checks the extension, so you can override this if you want.

Parameters
  • storage – The werkzeug.datastructures.FileStorage to check.

  • basename – The basename it will be saved under.

path(filename: str, folder: Optional[str] = None) str

This returns the absolute path of a file uploaded to this set. It doesn’t actually check whether said file exists.

Parameters
  • filename – The filename to return the path for.

  • folder – The subfolder within the upload set previously used to save to.

resolve_conflict(target_folder: str, basename: str) str

If a file with the selected name already exists in the target folder, this method is called to resolve the conflict. It should return a new basename for the file.

The default implementation splits the name and extension and adds a suffix to the name consisting of an underscore and a number, and tries that until it finds one that doesn’t exist.

Parameters
  • target_folder – The absolute path to the target.

  • basename – The file’s original basename.

save(storage: werkzeug.datastructures.FileStorage, folder: Optional[str] = None, name: Optional[str] = None) str

This saves the storage into this upload set.

A storage is a werkzeug.datastructures.FileStorage.

If the upload is not allowed, an UploadNotAllowed error will be raised.

Otherwise, the file will be saved and its name (including the folder) will be returned.

Parameters
  • storage – The uploaded file to save.

  • folder – The subfolder within the upload set to save to.

  • name – The name to save the file as. If it ends with a dot, the file’s extension will be appended to the end. (If you are using name, you can include the folder in the name instead of explicitly using folder, i.e. uset.save(file, name="someguy/photo_123.")

url(filename: str) str

This function gets the URL a file uploaded to this set would be accessed at. It doesn’t check whether said file exists.

Parameters

filename – The filename to return the URL for.

class flask_uploads.UploadConfiguration(destination: str, base_url: Optional[str] = None, allow: Union[Tuple[()], Tuple[str, ...]] = (), deny: Union[Tuple[()], Tuple[str, ...]] = ())

This holds the configuration for a single UploadSet. The constructor’s arguments are also the attributes.

Parameters
  • destination – The directory to save files to.

  • base_url – The URL (ending with a /) that files can be downloaded from. If this is None, Flask-Reuploaded will serve the files itself.

  • allow – A list of extensions to allow, even if they’re not in the UploadSet extensions list.

  • deny – A list of extensions to deny, even if they are in the UploadSet extensions list.

Application Setup

flask_uploads.configure_uploads(app: flask.app.Flask, upload_sets: Union[flask_uploads.flask_uploads.UploadSet, Iterable[flask_uploads.flask_uploads.UploadSet]]) None

Call this after the app has been configured. It will go through all the upload sets, get their configuration, and store the configuration on the app. It will also register the uploads module if it hasn’t been set. This can be called multiple times with different upload sets.

Changed in version 0.1.3: The uploads module/blueprint will only be registered if it is needed to serve the upload sets.

Parameters
  • app – The ~flask.Flask instance to get the configuration from.

  • upload_sets – The UploadSet instances to configure.

Extension Constants

These are some default sets of extensions you can pass to the UploadSet constructor.

class flask_uploads.AllExcept(items: Iterable[str])

This can be used to allow all file types except certain ones. For example, to ban .exe and .iso files, pass:

AllExcept(('exe', 'iso'))

to the UploadSet constructor as extensions. You can use any container, for example:

AllExcept(SCRIPTS + EXECUTABLES)
flask_uploads.DEFAULTS = ('txt', 'rtf', 'odf', 'ods', 'gnumeric', 'abw', 'doc', 'docx', 'xls', 'xlsx', 'pdf', 'jpg', 'jpe', 'jpeg', 'png', 'gif', 'svg', 'bmp', 'webp', 'csv', 'ini', 'json', 'plist', 'xml', 'yaml', 'yml')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

flask_uploads.ALL = <flask_uploads.extensions.All object>

This type can be used to allow all extensions. There is a predefined instance named ALL.

flask_uploads.TEXT = ('txt',)

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

flask_uploads.IMAGES = ('jpg', 'jpe', 'jpeg', 'png', 'gif', 'svg', 'bmp', 'webp')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

flask_uploads.AUDIO = ('wav', 'mp3', 'aac', 'ogg', 'oga', 'flac')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

flask_uploads.DOCUMENTS = ('rtf', 'odf', 'ods', 'gnumeric', 'abw', 'doc', 'docx', 'xls', 'xlsx', 'pdf')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

flask_uploads.DATA = ('csv', 'ini', 'json', 'plist', 'xml', 'yaml', 'yml')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

flask_uploads.SCRIPTS = ('js', 'php', 'pl', 'py', 'rb', 'sh')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

flask_uploads.ARCHIVES = ('gz', 'bz2', 'zip', 'tar', 'tgz', 'txz', '7z')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

flask_uploads.EXECUTABLES = ('so', 'exe', 'dll')

Built-in immutable sequence.

If no argument is given, the constructor returns an empty tuple. If iterable is specified the tuple is initialized from iterable’s items.

If the argument is a tuple, the return value is the same object.

Testing Utilities

class flask_uploads.TestingFileStorage(stream: Optional[BinaryIO] = None, filename: Optional[str] = None, name: Optional[str] = None, content_type: str = 'application/octet-stream', content_length: int = - 1, headers: Optional[Any] = None)

This is a helper for testing upload behavior in your application. You can manually create it, and its save method is overloaded to set saved to the name of the file it was saved to. All of these parameters are optional, so only bother setting the ones relevant to your application.

Parameters
  • stream – A stream. The default is an empty stream.

  • filename – The filename uploaded from the client. The default is the stream’s name.

  • name – The name of the form field it was loaded from. The default is None.

  • content_type – The content type it was uploaded as. The default is application/octet-stream.

  • content_length – How long it is. The default is -1.

  • headers – Multipart headers as a werkzeug.Headers. The default is None.

Backwards Compatibility

Version 1.0

  • Removal of patch_request_class

  • autoserve is now deactivated by default

Version 0.1.3

  • The _uploads module/blueprint will not be registered if it is not needed to serve uploads.

Version 0.1.1

  • patch_request_class now changes max_content_length instead of max_form_memory_size.