API¶
Core¶
-
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
-
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: 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:
-
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
- file_or_wfs – a file or
-
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: Raises: FileExists – If the file exists and overwrite is False
- name (str) – The name of this storage. It defaults to
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…)
Backends¶
-
class
flask_fs.backends.
BaseBackend
(name, config)[source]¶ Abstract class to implement backend.
-
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
-
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
-
-
class
flask_fs.backends.local.
LocalBackend
(name, config)[source]¶ A local file system storage
Expect the following settings:
- root: The file system root
-
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
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
-
-
class
flask_fs.mongo.
FileReference
(fs=None, filename=None, upload_to=None, basename=None, instance=None, name=None)[source]¶ Implements the FileField interface
-
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
-
rerender
()[source]¶ Rerender all derived images from the original. If optmization settings or expected sizes changed, they will be used for the new rendering.
-