API Reference

flask_store

Adds simple file handling for different providers to your application. Provides the following providers out of the box:

• Local file storeage
• Amazon Simple File Storage (requires boto to be installed)

class flask_store.Store(app=None)

Flask-Store integration into Flask applications. Flask-Store can be integrated in two different ways depending on how you have setup your Flask application.

You can bind to a specific flask application:

app = Flask(__name__)
store = Store(app)

Or if you use an application factory you can use flask_store.Store.init_app():

store = Store()
def create_app():
    app = Flask(__name__)
    store.init_app(app)
    return app

check_config(app)

Checks the required application configuration variables are set in the flask application.

Parameters:app (flask.app.Flask) – Flask application instance Raises:NotConfiguredError – In the event a required config parameter is required by the Store.

init_app(app)

Sets up application default confugration options and sets a Provider property which can be used to access the default provider class which handles the saving of files.

Parameters:app (flask.app.Flask) – Flask application instance

provider(app)

Fetches the provider class as defined by the application configuration.

Parameters:app (flask.app.Flask) – Flask application instance Raises:ImportError – If the class or module cannot be imported Returns:The provider class Return type:class

register_route(app)

Registers a default route for serving uploaded assets via Flask-Store, this is based on the absolute and relative paths defined in the app configuration.

Parameters:app (flask.app.Flask) – Flask application instance

set_provider_defaults(app)

If the provider has a app_defaults static method then this simply calls that method. This will set sensible application configuration options for the provider.

Parameters:app (flask.app.Flask) – Flask application instance

class flask_store.StoreState(store, app)

Stores the state of Flask-Store from application init.

flask_store.store_provider()

Returns the default provider class as defined in the application configuration.

Returns:The provider class Return type:class

flask_store.exceptions

Custom Flask-Store exception classes.

exception flask_store.exceptions.NotConfiguredError

Raise this exception in the event the flask application has not been configured properly.

flask_store.sqlalchemy

Custom SQLAlchemy types for handling Flask-Store instances in SQLAlchemy.

class flask_store.sqla.FlaskStoreType(max_length=256, location=None, *args, **kwargs)

A SQL Alchemy custom type which will save a file using the Flask Application Configured Store Provider and saves the relative path the the database.

Also creates a fresh provider instance when accessing the data attribute from an instance.

Example

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_store import Store
from flask_store.sqla import FlaskStoreType

app = Flask(__name__)

db = SQLAlchemy(app)
store = Store(app)

class MyModel(db.Model):
    field = db.Column(FlaskStoreType(location='/some/place'))

impl = Unicode(length=256)

Implements a standard unicode type

process_bind_param(value, dialect)

Called when setting the value be stored in the database field, this will be the files relative file path.

Parameters:

• value (werkzeug.datastructures.FileStorage) – The uploaded file to save
• dialect (sqlalchemy.engine.interfaces.Dialect) – The dialect

Returns:

The files realtive path on what ever storage backend defined in the Flask Application configuration

Return type:

str

process_result_value(value, dialect)

Called when accessing the value from the database and returning the appropriate provider file wrapper.

Parameters:

• value (str) – The stored relative path in the database
• dialect (sqlalchemy.engine.interfaces.Dialect) – The dialect

Returns:

An instance of the Store Provider class

Return type:

obj

flask_store.utils

flask_store.utils.is_directory(f)

Checks if an object is a string, and that it points to a directory. Taken from Pillow, all credit goes to the Pillow / PIL team.

Parameters:f – Could be anything Returns:Is a path to a directory or not Return type:bool

flask_store.utils.is_path(f)

Determines if the passed argument is a string or not, if is a string it is assumed to be a path. Taken from Pillow, all credit goes to the Pillow / PIL team.

Parameters:f – Could be anything Returns:Is a string or not Return type:bool

flask_store.utils.path_to_uri(path)

Swaps for / Other stuff will happen here in the future.

flask_store.providers

Base store functionality and classes.

class flask_store.providers.Provider(fp, location=None)

Base provider class all storage providers should inherit from. This class provides some of the base functionality for all providers. Override as required.

absolute_path

Returns the absollute file path to the file.

Returns:Absolute file path Return type:str

absolute_url

Absolute url contains a domain if it is set in the configuration, the url predix, location and the actual file name.

Returns:Full absolute URL to file Return type:str

exists(*args, **kwargs)

Placeholder “exists” method. This should be overridden by custom providers and return a boolean depending on if the file exists of not for the provider.

Raises:NotImplementedError – If the “exists” method has not been implemented

join(*args, **kwargs)

Each provider needs to implement how to safely join parts of a path together to result in a path which can be used for the provider.

Raises:NotImplementedError – If the “join” method has not been implemented

register_route = False

By default Providers do not require a route to be registered

relative_path

Returns the relative path to the file, so minus the base path but still includes the location if it is set.

Returns:Relative path to file Return type:str

relative_url

Returns the relative URL, basically minus the domain.

Returns:Realtive URL to file Return type:str

safe_filename(filename)

If the file already exists the file will be renamed to contain a short url safe UUID. This will avoid overwtites.

Parameters:filename (str) – A filename to check if it exists Returns:A safe filenaem to use when writting the file Return type:str

save(*args, **kwargs)

Placeholder “sabe” method. This should be overridden by custom providers and save the file object to the provider.

Raises:NotImplementedError – If the “save” method has not been implemented

url_join(*parts)

Safe url part joining.

Parameters:*parts (list) – List of parts to join together Returns:Joined url parts Return type:str

flask_store.providers.local

Local file storage for your Flask application.

Example

from flask import Flask, request
from flask.ext.store import Provider, Store
from wtforms import Form
from wtforms.fields import FileField

class FooForm(Form):
    foo = FileField('foo')

app = Flask(__app__)
app.config['STORE_PATH'] = '/some/file/path'

store = Store(app)

@app,route('/upload')
def upload():
    form = FooForm()
    form.validate_on_submit()

    if not form.errors:
        provider = store.Provider(request.files.get('foo'))
        provider.save()

class flask_store.providers.local.LocalProvider(fp, location=None)

The default provider for Flask-Store. Handles saving files onto the local file system.

static app_defaults(app)

Sets sensible application configuration settings for this provider.

Parameters:app (flask.app.Flask) – Flask application at init

exists(filename)

Returns boolean of the provided filename exists at the compiled absolute path.

Parameters:name (str) – Filename to check its existence Returns:Whether the file exists on the file system Return type:bool

join(*parts)

Joins paths together in a safe manor.

Parameters:*parts (list) – List of arbitrary paths to join together Returns:Joined paths Return type:str

open()

Opens the file and returns the file handler.

Returns:Open file handler Return type:file

register_route = True

Ensure a route is registered for serving files

save()

Save the file on the local file system. Simply builds the paths and calls werkzeug.datastructures.FileStorage.save() on the file object.

flask_store.providers.s3

AWS Simple Storage Service file Store.

Example

from flask import Flask, request
from flask.ext.Store import Provider, Store
from wtforms import Form
from wtforms.fields import FileField

class FooForm(Form):
    foo = FileField('foo')

app = Flask(__app__)
app.config['STORE_PROVIDER'] = 'flask_store.providers.s3.S3Provider'
app.config['STORE_S3_ACCESS_KEY'] = 'foo'
app.confog['STORE_S3_SECRET_KEY'] = 'bar'

store = Store(app)

@app,route('/upload')
def upload():
    form = FooForm()
    form.validate_on_submit()

    provider = Provider(form.files.get('foo'))
    provider.save()

class flask_store.providers.s3.S3GeventProvider(*args, **kwargs)

A Gevent Support for S3Provider. Calling save() here will spawn a greenlet which will handle the actual upload process.

save()

Acts as a proxy to the actual save method in the parent class. The save method will be called in a greenlet so gevent must be installed.

Since the origional request will close the file object we write the file to a temporary location on disk and create a new werkzeug.datastructures.FileStorage instance with the stram being the temporary file.

class flask_store.providers.s3.S3Provider(fp, location=None)

Amazon Simple Storage Service Store (S3). Allows files to be stored in an AWS S3 bucket.

REQUIRED_CONFIGURATION = ['STORE_S3_ACCESS_KEY', 'STORE_S3_SECRET_KEY', 'STORE_S3_BUCKET', 'STORE_S3_REGION']

Required application configuration variables

static app_defaults(app)

Sets sensible application configuration settings for this provider.

Parameters:app (flask.app.Flask) – Flask application at init

bucket(s3connection)

Returns an S3 bucket instance

connect()

Returns an S3 connection instance.

exists(filename)

Checks if the file already exists in the bucket using Boto.

Parameters:name (str) – Filename to check its existence Returns:Whether the file exists on the file system Return type:bool

join(*parts)

Joins paths into a url.

Parameters:*parts (list) – List of arbitrary paths to join together Returns:S3 save joined paths Return type:str

open()

Opens an S3 key and returns an oepn File Like object pointer.

Returns:In memory file data Return type:_io.BytesIO

save()

Takes the uploaded file and uploads it to S3.

Note

This is a blocking call and therefore will increase the time for your application to respond to the client and may cause request timeouts.