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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Stores the state of Flask-Store from application init.

flask_store.store_provider()[source]

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[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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

static app_defaults(app)[source]

Sets sensible application configuration settings for this provider.

Parameters:app (flask.app.Flask) – Flask application at init
exists(filename)[source]

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)[source]

Joins paths together in a safe manor.

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

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()[source]

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)[source]

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

save()[source]

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)[source]

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)[source]

Sets sensible application configuration settings for this provider.

Parameters:app (flask.app.Flask) – Flask application at init
bucket(s3connection)[source]

Returns an S3 bucket instance

connect()[source]

Returns an S3 connection instance.

exists(filename)[source]

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)[source]

Joins paths into a url.

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

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

Returns:In memory file data
Return type:_io.BytesIO
save()[source]

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.