API

Core

flask_fs.by_name(name)[source]

Get a storage by its name

flask_fs.init_app(app, *storages)[source]

Initialize Storages configuration Register blueprint if necessary.

Parameters:
  • app – The ~flask.Flask instance to get the configuration from.
  • storages – A Storage instance list to register and configure.
class flask_fs.Storage(name=u'files', extensions=[u'txt', u'rtf', u'odf', u'ods', u'gnumeric', u'abw', u'doc', u'docx', u'xls', u'xlsx', u'jpg', u'jpe', u'jpeg', u'png', u'gif', u'svg', u'bmp', u'csv', u'ini', u'json', u'plist', u'xml', u'yaml', u'yml'], upload_to=None, overwrite=False)[source]

This represents a single set of files. Each Storage 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 (str) – The name of this storage. It defaults to files, but you can pick any alphanumeric name you want.
  • extensions (tuple) – The extensions to allow uploading in this storage. 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 {NAME}_FS_ALLOW and {NAME}_FS__DENY configuration parameters. The default is DEFAULTS.
  • upload_to (str|callable) – 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.
  • overwrite (bool) – Whether or not to allow overwriting
base_url

The public URL for this storage

configure(app)[source]

Load configuration from application configuration.

For each storage, the configuration is loaded with the following pattern:

FS_{BACKEND_NAME}_{KEY} then
{STORAGE_NAME}_FS_{KEY}

If no configuration is set for a given key, global config is taken as default.

delete(filename)[source]

Delete a file.

Parameters:filename (str) – The storage root-relative filename
exists(filename)[source]

Verify whether a file exists or not.

extension_allowed(ext)[source]

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 (str) – The extension to check, without the dot.
file_allowed(storage, basename)[source]

This tells whether a file is allowed.

It should return True if the given 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.FileStorage to check.
  • basename – The basename it will be saved under.
has_url

Whether this storage has a public URL or not

list_files()[source]

Returns a filename generator to iterate through all the file in the storage bucket

metadata(filename)[source]

Get some metadata for a given file.

Can vary from a backend to another but some are always present: - filename: the base filename (without the path/prefix) - url: the file public URL - checksum: a checksum expressed in the form algo:hash - ‘mime’: the mime type - modified: the last modification date

open(filename, mode=u'r', **kwargs)[source]

Open the file and return a file-like object.

Parameters:
  • filename (str) – The storage root-relative filename
  • mode (str) – The open mode ((r|w)b?)
Raises:

FileNotFound – If trying to read a file that does not exists

path(filename)[source]

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.
Raises:

OperationNotSupported – when the backenddoesn’t support direct file access

read(filename)[source]

Read a file content.

Parameters:filename (string) – The storage root-relative filename
Raises:FileNotFound – If the file does not exists
resolve_conflict(target_folder, basename)[source]

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 (str) – The absolute path to the target.
  • basename (str) – The file’s original basename.
save(file_or_wfs, filename=None, prefix=None, overwrite=None)[source]

Saves a file or a FileStorage into this storage.

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:
  • file_or_wfs – a file or werkzeug.FileStorage file to save.
  • filename (string) – The expected filename in the storage. Optionnal with a FileStorage but allow to override clietn value
  • prefix (string) – a path or a callable returning a path to be prepended to the filename.
  • overwrite (bool) – if specified, override the storage default value.
Raises:

UnauthorizedFileType – If the file type is not allowed

serve(filename)[source]

Serve a file given its filename

url(filename, external=False)[source]

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 (string) – The filename to return the URL for.
  • external (bool) – If True, returns an absolute URL
write(filename, content, overwrite=False)[source]

Write content to a file.

Parameters:
  • filename (str) – The storage root-relative filename
  • content – The content to write in the file
  • overwrite (bool) – Whether to wllow overwrite or not
Raises:

FileExists – If the file exists and overwrite is False

File types

flask_fs.TEXT = [u'txt']

list() -> new empty list list(iterable) -> new list initialized from iterable’s items

flask_fs.DOCUMENTS = [u'rtf', u'odf', u'ods', u'gnumeric', u'abw', u'doc', u'docx', u'xls', u'xlsx']

list() -> new empty list list(iterable) -> new list initialized from iterable’s items

flask_fs.IMAGES = [u'jpg', u'jpe', u'jpeg', u'png', u'gif', u'svg', u'bmp']

list() -> new empty list list(iterable) -> new list initialized from iterable’s items

flask_fs.AUDIO = [u'wav', u'mp3', u'aac', u'ogg', u'oga', u'flac']

list() -> new empty list list(iterable) -> new list initialized from iterable’s items

flask_fs.DATA = [u'csv', u'ini', u'json', u'plist', u'xml', u'yaml', u'yml']

list() -> new empty list list(iterable) -> new list initialized from iterable’s items

flask_fs.SCRIPTS = [u'js', u'php', u'pl', u'py', u'rb', u'sh', u'bat']

list() -> new empty list list(iterable) -> new list initialized from iterable’s items

flask_fs.ARCHIVES = [u'gz', u'bz2', u'zip', u'tar', u'tgz', u'txz', u'7z']

list() -> new empty list list(iterable) -> new list initialized from iterable’s items

flask_fs.EXECUTABLES = [u'so', u'exe', u'dll']

list() -> new empty list list(iterable) -> new list initialized from iterable’s items

flask_fs.DEFAULTS = [u'txt', u'rtf', u'odf', u'ods', u'gnumeric', u'abw', u'doc', u'docx', u'xls', u'xlsx', u'jpg', u'jpe', u'jpeg', u'png', u'gif', u'svg', u'bmp', u'csv', u'ini', u'json', u'plist', u'xml', u'yaml', u'yml']

list() -> new empty list list(iterable) -> new list initialized from iterable’s items

flask_fs.ALL = <flask_fs.files.All object>

This “contains” all items. You can use it to allow all extensions to be uploaded.

class flask_fs.All[source]

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

class flask_fs.AllExcept(items)[source]

This can be used to allow all file types except certain ones.

For example, to exclude .exe and .iso files, pass:

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

to the Storage constructor as extensions parameter.

You can use any container, for example:

AllExcept(SCRIPTS + EXECUTABLES)

This module handle image operations (thumbnailing, resizing…)

flask_fs.images.make_thumbnail(file, size, bbox=None)[source]

Generate a thumbnail for a given image file.

Parameters:
  • file (file) – The source image file to thumbnail
  • size (int) – The thumbnail size in pixels (Thumbnails are squares)
  • bbox (tuple) – An optionnal Bounding box definition for the thumbnail

Backends

class flask_fs.backends.BaseBackend(name, config)[source]

Abstract class to implement backend.

as_binary(content, encoding=u'utf8')[source]

Perform content encoding for binary write

copy(filename, target)[source]

Copy a file given its filename to another path in the storage

delete(filename)[source]

Delete a file given its filename in the storage

exists(filename)[source]

Test wether a file exists or not given its filename in the storage

get_metadata(filename)[source]

Backend specific method to retrieve metadata for a given file

metadata(filename)[source]

Fetch all available metadata for a given file

move(filename, target)[source]

Move a file given its filename to another path in the storage

Default implementation perform a copy then a delete. Backends should overwrite it if there is a better way.

open(filename, *args, **kwargs)[source]

Open a file given its filename relative to the storage root

read(filename)[source]

Read a file content given its filename in the storage

save(file_or_wfs, filename, overwrite=False)[source]

Save a file-like object or a werkzeug.FileStorage with the specified filename.

Parameters:
  • storage – The file or the storage to be saved.
  • filename – The destination in the storage.
  • overwrite – if False, raise an exception if file exists in storage
Raises:

FileExists – when file exists and overwrite is False

serve(filename)[source]

Serve a file given its filename

write(filename, content)[source]

Write content into a file given its filename in the storage

class flask_fs.backends.local.LocalBackend(name, config)[source]

A local file system storage

Expect the following settings:

  • root: The file system root
get_metadata(filename)[source]

Fetch all available metadata

path(filename)[source]

Return the full path for a given filename in the storage

serve(filename)[source]

Serve files for storages with direct file access

class flask_fs.backends.s3.S3Backend(name, config)[source]

An Amazon S3 Backend (compatible with any S3-like API)

Expect the following settings:

  • endpoint: The S3 API endpoint
  • region: The region to work on.
  • access_key: The AWS credential access key
  • secret_key: The AWS credential secret key
get_metadata(filename)[source]

Fetch all availabe metadata

class flask_fs.backends.swift.SwiftBackend(name, config)[source]

An OpenStack Swift backend

Expect the following settings:

  • authurl: The Swift Auth URL
  • user: The Swift user in
  • key: The user API Key
class flask_fs.backends.gridfs.GridFsBackend(name, config)[source]

A Mongo GridFS backend

Expect the following settings:

  • mongo_url: The Mongo access URL
  • mongo_db: The database to store the file in.

Mongo

class flask_fs.mongo.FileField(fs=None, upload_to=None, basename=None, *args, **kwargs)[source]

Store reference to files in a given storage.

proxy_class

alias of FileReference

to_mongo(value)[source]

Convert a Python type to a MongoDB-compatible type.

to_python(value)[source]

Convert a MongoDB-compatible type to a Python type.

class flask_fs.mongo.FileReference(fs=None, filename=None, upload_to=None, basename=None, instance=None, name=None)[source]

Implements the FileField interface

save(wfs, filename=None)[source]

Save a Werkzeug FileStorage object

class flask_fs.mongo.ImageField(max_size=None, thumbnails=None, optimize=None, *args, **kwargs)[source]

Store reference to images in a given Storage.

Allow to automatically generate thumbnails or resized image. Original image always stay untouched.

proxy_class

alias of ImageReference

class flask_fs.mongo.ImageReference(original=None, max_size=None, thumbnail_sizes=None, thumbnails=None, bbox=None, optimize=None, **kwargs)[source]

Implements the ImageField interface

best_url(size=None, external=False)[source]

Provide the best thumbnail for downscaling.

If there is no match, provide the bigger if exists or the original

full(external=False)[source]

Get the full image URL in respect with max_size

rerender()[source]

Rerender all derived images from the original. If optmization settings or expected sizes changed, they will be used for the new rendering.

save(file_or_wfs, filename=None, bbox=None, overwrite=None)[source]

Save a Werkzeug FileStorage object

thumbnail(size)[source]

Get the thumbnail filename for a given size

Errors

These are all errors used accross this extensions.

exception flask_fs.errors.FSError[source]

Base class for all Flask-FS Exceptions

exception flask_fs.errors.FileExists[source]

Raised when trying to overwrite an existing file

exception flask_fs.errors.FileNotFound[source]

Raised when trying to access a non existant file

exception flask_fs.errors.UnauthorizedFileType[source]

This exception is raised when trying to upload an unauthorized file type.

exception flask_fs.errors.UploadNotAllowed[source]

Raised when trying to upload into storage where upload is not allowed.

exception flask_fs.errors.OperationNotSupported[source]

Raised when trying to perform an operation not supported by the current backend

Internals

These are internal classes or helpers. Most of the time you shouldn’t have to deal directly with them.

class flask_fs.storage.Config[source]

Wrap the configuration for a single Storage.

Basically, it’s an ObjectDict