static assets from Amazon S3, without having to modify your templates.
Merging and modifying the functionality from both repository,
In Flask-S3-Bower you don’t have to modify the templates. Use defualt url_for for serving file from both s3, bower and default static folder.
Flask-S3-Bower has two main functions:
- Walk through your application’s static folders, gather all your static assets together, and upload them to a bucket of your choice on S3; It also includes BOWER_COMPONENTS_ROOT folder if it is placed outside static folder via BOWER_COMPONENTS_ROOT in settings;
- Replace the URLs that Flask’s flask.url_for() function would insert into your templates, with URLs that point to the static assets in your S3 bucket.
The process of gathering and uploading your static assets to S3 need only be done once, and your application does not need to be running for it to work. The location of the S3 bucket can be inferred from Flask-S3 settings specified in your Flask application, therefore when your application is running there need not be any communication between the Flask application and Amazon S3.
Internally, every time url_for is called in one of your application’s templates, flask_s3.url_for is instead invoked. If the endpoint provided is deemed to refer to static assets, then the S3 URL for the asset specified in the filename argument is instead returned. Otherwise, flask_s3.url_for passes the call on to flask.url_for.
By default in production mode it will use S3 url_for, and in development mode with USE_BOWER=True has set, it will use bower url_for.
If you use pip then installation is simply:
$ pip install flask-s3-bower
or, if you want the latest github version:
$ pip install git+git://github.com/ibrahim12/flask-s3-bower.git
You can also install Flask-S3 via Easy Install:
$ easy_install flask-s3-bower
Flask-S3-Bower is incredibly simple to use. In order to start serving your Flask application’s assets from Amazon S3, the first thing to do is let Flask-S3-Bower know about your flask.Flask application object.
from flask import Flask
from flask_s3_bower import FlaskS3Bower
app = Flask(__name__)
app.config['S3_BUCKET_NAME'] = 'mybucketname'
s3bower = FlaskS3Bower(app)
In many cases, however, one cannot expect a Flask instance to be ready at import time, and a common pattern is to return a Flask instance from within a function only after other configuration details have been taken care of. In these cases, Flask-S3 provides a simple function, init_app, which takes your application as an argument.
from flask import Flask
from flask_s3_bower import FlaskS3Bower
s3bower = FlaskS3Bower()
def start_app():
app = Flask(__name__)
s3bower.init_app(app)
return app
In terms of getting your application to use external Amazon S3 URLs when referring to your application’s static assets, passing your Flask object to the FlaskS3 object is all that needs to be done. Once your app is running, any templates that contained relative static asset locations, will instead contain hosted counterparts on Amazon S3.
You only need to upload your static assets to Amazon S3 once. Of course, if you add or modify your existing assets then you will need to repeat the uploading process.
Uploading your static assets from a Python console is as simple as follows.
>>> import flask_s3_bower
>>> from my_application import app
>>> flask_s3_bower.create_all(app)
>>>
Flask-S3-Bower will proceed to walk through your application’s static assets, including those belonging to registered blueprints, and upload them to your Amazon S3 bucket.
Within your bucket on S3, Flask-S3-Bower replicates the static file hierarchy defined in your application object and any registered blueprints. URLs generated by Flask-S3-Bower will look like the following:
/static/foo/style.css becomes https://mybucketname.s3.amazonaws.com/static/foo/style.css, assuming that mybucketname is the name of your S3 bucket, and you have chosen to have assets served over HTTPS.
or If you choose bower via USE_BOWER=True in settings urls become, /bower/foo/style.css
To set custom HTTP headers on the files served from S3 specify what headers you want to use with the S3_HEADERS option.
S3_HEADERS = {
'Expires': 'Thu, 15 Apr 2010 20:00:00 GMT',
'Cache-Control': 'max-age=86400',
}
See Yahoo! more information on how to set good values for your headers.
Within your Flask application’s settings you can provide the following settings to control the behaviour of Flask-S3-Bower. None of the settings are required, but if not present, some will need to be provided when uploading assets to S3.
AWS_ACCESS_KEY_ID | Your AWS access key. This does not need to be stored in your configuration if you choose to pass it directly when uploading your assets. |
AWS_SECRET_ACCESS_KEY | Your AWS secret key. As with the access key, this need not be stored in your configuration if passed in to create_all. |
S3_BUCKET_DOMAIN | The domain part of the URI for your S3 bucket. You probably won’t need to change this. Default: u's3.amazonaws.com' |
S3_CDN_DOMAIN | AWS makes it easy to attach CloudFront to an S3 bucket. If you want to use this or another CDN, set the base domain here. This is distinct from the S3_BUCKET_DOMAIN since it will not include the bucket name in the base url. |
S3_BUCKET_NAME | The desired name for your Amazon S3 bucket. Note: the name will be visible in all your assets’ URLs. |
S3_URL_STYLE | Set to 'host' to use virtual-host-style URLs, e.g. bucketname.s3.amazonaws.com. Set to 'path' to use path-style URLs, e.g. s3.amazonaws.com/bucketname. Default: 'host' |
S3_USE_HTTPS | Specifies whether or not to serve your assets stored in S3 over HTTPS. Default: True |
USE_S3 | This setting allows you to toggle whether Flask-S3 is active or not. When set to False your application’s templates will revert to including static asset locations determined by flask.url_for. Default: True Note: if you run your application in debug mode (and USE_S3_DEBUG is False - see next item), USE_S3 will be changed to False. This allows the USE_S3 config variable to be the definitive check as to whether flask_s3.url_for is overriding flask.url_for. |
USE_S3_DEBUG | By default, Flask-S3 will be switched off when running your application in debug mode, so that your templates include static asset locations specified by flask.url_for. If you wish to enable Flask-S3 in debug mode, set this value to True. Note: if USE_S3 is set to False then templates will always include asset locations specified by flask.url_for. |
S3_HEADERS | Sets custom headers to be sent with each file to S3. Default: {} |
S3_ONLY_MODIFIED | Only upload files that have been modified since last upload to S3. SHA-1 file hashes are used to compute file changes. You can delete file-hashes from your S3 bucket to force all files to upload again. |
S3_CACHE_CONTROL | Deprecated. Please use S3_HEADERS instead. |
S3_USE_CACHE_CONTROL | Deprecated. Please use S3_HEADERS instead. |
USE_BOWER | By default USE_BOWER is set to False. If DEBUG is set to False and USE_S3 is enabled USE_BOWER is ignored. To Enable bower support, make USE_BOWER=True and make USE_S3=False or DEBUG=True |
Flask-S3-Bower is a very simple extension. The few exposed objects, methods and functions are as follows.
The FlaskS3Bower object allows your application to use Flask-S3 and Bower togather. Its a merge of two project, FlaskS3 and Flask-Bower
When initialising a FlaskS3Bower object you may optionally provide your flask.Flask application object if it is ready. Otherwise, you may provide it later by using the init_app() method.
Parameters: | app (flask.Flask or None) – optional flask.Flask application object |
---|
An alternative way to pass your flask.Flask application object to Flask-S3-Bower. init_app() also takes care of some default settings.
Parameters: | app – the flask.Flask application object. |
---|
Uploads of the static assets associated with a Flask application to Amazon S3.
All static assets are identified on the local filesystem, including any static assets associated with registered blueprints. In turn, each asset is uploaded to the bucket described by bucket_name. If the bucket does not exist then it is created.
Flask-S3 creates the same relative static asset folder structure on S3 as can be found within your Flask application.
Many of the optional arguments to create_all can be specified instead in your application’s configuration using the Flask-S3 configuration variables.
Parameters: |
|
---|
Generates a URL to the given endpoint.
If the endpoint is for a static resource then an Amazon S3 URL is generated, otherwise the call is passed on to flask.url_for.
Because this function is set as a jinja environment variable when FlaskS3.init_app is invoked, this function replaces flask.url_for in templates automatically. It is unlikely that this function will need to be directly called from within your application code, unless you need to refer to static assets outside of your templates.