mirror of
https://github.com/wassname/flask-s3.git
synced 2026-07-10 00:30:27 +08:00
Rehan Dalal
205 lines
7.5 KiB
ReStructuredText
205 lines
7.5 KiB
ReStructuredText
Flask-S3
|
|
********
|
|
.. module:: flask_s3
|
|
|
|
Flask-S3 allows you to easily serve all your `Flask`_ application's static
|
|
assets from `Amazon S3`_, without having to modify your templates.
|
|
|
|
.. _Amazon S3: http://aws.amazon.com/s3
|
|
.. _Flask: http://flask.pocoo.org/
|
|
|
|
|
|
How it works
|
|
============
|
|
|
|
Flask-S3 has two main functions:
|
|
|
|
1. Walk through your application's static folders, gather all your static
|
|
assets together, and upload them to a bucket of your choice on S3;
|
|
|
|
2. Replace the URLs that Flask's :func:`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`.
|
|
|
|
|
|
Installation
|
|
============
|
|
|
|
If you use pip then installation is simply::
|
|
|
|
$ pip install flask-s3
|
|
|
|
or, if you want the latest github version::
|
|
|
|
$ pip install git+git://github.com/e-dard/flask-s3.git
|
|
|
|
You can also install Flask-S3 via Easy Install::
|
|
|
|
$ easy_install flask-s3
|
|
|
|
Dependencies
|
|
------------
|
|
|
|
Aside from the obvious dependency of Flask itself, Flask-S3 makes use of the
|
|
`boto`_ library for uploading assets to Amazon S3. **Note**: Flask-S3 currently
|
|
only supports applications that use the `jinja2`_ templating system.
|
|
|
|
.. _boto: http://docs.pythonboto.org/en/latest/
|
|
.. _jinja2: http://jinja.pocoo.org/docs/
|
|
|
|
|
|
Using Flask-S3
|
|
==============
|
|
|
|
Flask-S3 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 know
|
|
about your :class:`flask.Flask` application object.
|
|
|
|
.. code-block:: python
|
|
|
|
from flask import Flask
|
|
from flask_s3 import FlaskS3
|
|
|
|
app = Flask(__name__)
|
|
app.config['S3_BUCKET_NAME'] = 'mybucketname'
|
|
s3 = FlaskS3(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.
|
|
|
|
.. code-block:: python
|
|
|
|
from flask import Flask
|
|
from flask_s3 import FlaskS3
|
|
|
|
s3 = FlaskS3()
|
|
|
|
def start_app():
|
|
app = Flask(__name__)
|
|
s3.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.
|
|
|
|
Uploading your Static Assets
|
|
----------------------------
|
|
|
|
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.
|
|
|
|
.. code-block:: python
|
|
|
|
>>> import flask_s3
|
|
>>> from my_application import app
|
|
>>> flask_s3.create_all(app)
|
|
>>>
|
|
|
|
Flask-S3 will proceed to walk through your application's static assets,
|
|
including those belonging to *registered* `blueprints`_, and upload them to your
|
|
Amazon S3 bucket.
|
|
|
|
.. _blueprints: http://flask.pocoo.org/docs/blueprints/
|
|
|
|
Static Asset URLs
|
|
~~~~~~~~~~~~~~~~~
|
|
|
|
Within your bucket on S3, Flask-S3 replicates the static file hierarchy defined
|
|
in your application object and any registered blueprints. URLs generated by
|
|
Flask-S3 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.
|
|
|
|
|
|
.. _settings:
|
|
.. _configuration:
|
|
|
|
Flask-S3 Options
|
|
----------------
|
|
|
|
Within your Flask application's settings you can provide the following settings
|
|
to control the behvaiour of Flask-S3. 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_BUCKET_NAME` The desired name for your Amazon S3 bucket. Note:
|
|
the name will be visible in all your assets' URLs.
|
|
`S3_CACHE_CONTROL` This sets the value of the Cache-Control header that
|
|
is set in the metadata when `S3_USE_CACHE_CONTRL` is
|
|
set to `True`.
|
|
`S3_USE_CACHE_CONTROL` Specifies whether or not to set the metadata for the
|
|
Cache-Control headers.
|
|
**Default:** `False`
|
|
`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`
|
|
`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`.
|
|
=========================== ===================================================
|
|
|
|
.. _debug: http://flask.pocoo.org/docs/config/#configuration-basics
|
|
|
|
|
|
API Documentation
|
|
=================
|
|
|
|
Flask-S3 is a very simple extension. The few exposed objects, methods and
|
|
functions are as follows.
|
|
|
|
The FlaskS3 Object
|
|
------------------
|
|
.. autoclass:: FlaskS3
|
|
|
|
.. automethod:: init_app
|
|
|
|
S3 Interaction
|
|
--------------
|
|
.. autofunction:: create_all
|
|
|
|
.. autofunction:: url_for
|