<commit_before>Flask-CDN
*********
.. module:: flask_cdn

Flask-CDN allows you to easily serve all your `Flask`_ application's
static assets from a CDN (like `Amazon Cloudfront`_), without having to modify
your templates.

.. _Amazon Cloudfront: https://aws.amazon.com/cloudfront/
.. _Flask: http://flask.pocoo.org/


How it works
============

Flask-CDN replaces the URLs that Flask's :func:`flask.url_for` function would
insert into your templates, with URLs that point to your CDN. This makes
setting up an origin pull CDN extremely easy.

Internally, every time ``url_for`` is called in one of your
application's templates, `flask_cdn.url_for` is instead invoked. If the
endpoint provided is deemed to refer to static assets, then the CDN URL
for the asset specified in the `filename` argument is instead returned.
Otherwise, `flask_cdn.url_for` passes the call on to `flask.url_for`.


Installation
============

If you use pip then installation is simply::

    $ pip install flask-cdn

or, if you want the latest github version::

    $ pip install git+git://github.com/wichitacode/flask-cdn.git

You can also install Flask-CDN via Easy Install::

    $ easy_install flask-cdn

Dependencies
------------

There are no additional dependencies besides Flask itself. **Note**: Flask-CDN
currently only supports applications that use the `jinja2`_ templating system.

.. _jinja2: http://jinja.pocoo.org/docs/


Using Flask-CDN
===============

Flask-CDN is incredibly simple to use. In order to start serving your
Flask application's assets from Amazon CDN, the first thing to do is let
Flask-CDN know about your :class:`flask.Flask` application object.

.. code-block:: python

    from flask import Flask
    from flask.ext.cdn import CDN

    app = Flask(__name__)
    app.config['CDN_DOMAIN'] = 'mycdnname.cloudfront.net'
    CDN(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-CDN provides a simple function,
``init_app``, which takes your application as an argument.

.. code-block:: python

    from flask import Flask
    from flask.ext.cdn import CDN

    cdn = CDN()

    def start_app():
        app = Flask(__name__)
        cdn.init_app(app)
        return app

In terms of getting your application to use external CDN URLs when
referring to your application's static assets, passing your ``Flask``
object to the ``CDN`` object is all that needs to be done. Once your
app is running, any templates that contained relative static asset
locations, will instead be pulled from your CDN.

Static Asset URLs
-----------------

URLs generated by Flask-CDN will look like the following:

``/static/foo/style.css`` becomes
``https://mycdnname.cloudfront.net/static/foo/style.css``, assuming
that ``mycdnname.cloudfront.net`` is the domain of your CDN, and you have
chosen to have assets served over HTTPS.

Flask-CDN Options
-----------------

Within your Flask application's settings you can provide the following
settings to control the behaviour of Flask-CDN. None of the settings are
required.

=========================== ===================================================
`CDN_DOMAIN`                Set the base domain for your CDN here.
                            **Default:** `None`
`CDN_HTTPS`                 Specifies whether or not to serve your assets over
                            HTTPS.
                            **Default:** `False`
`CDN_TIMESTAMP`             Specifies whether or not to add a timestamp to the
                            generated urls.
                            **Default:** `True`
`CDN_DEBUG`                 By default, Flask-CDN 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-CDN in debug mode, set this value to `True`.
                            **Default:** `False`
=========================== ===================================================

.. _debug: http://flask.pocoo.org/docs/config/#configuration-basics


Serve Static Assets with CloudFront
===================================

CloudFront is a very simple way to seamlessly serve your static assets with
it’s CDN. When a request comes into CloudFront, if the asset is not on the CDN
or has expired, then CloudFront can get the asset from an “origin server”.
This type of setup is called an origin pull CDN.

To setup a new CloudFront “Distribution”:

- Signup for an `AWS Account`_
- Open the `Cloudfront Management Console`_
- Select Create Distribution
- Leave Download selected as the delivery method and select Continue
- In the Origin Domain Name field enter the domain name for your application<commit_msg>Update docs with the new default value.<commit_after>Flask-CDN
*********
.. module:: flask_cdn

Flask-CDN allows you to easily serve all your `Flask`_ application's
static assets from a CDN (like `Amazon Cloudfront`_), without having to modify
your templates.

.. _Amazon Cloudfront: https://aws.amazon.com/cloudfront/
.. _Flask: http://flask.pocoo.org/


How it works
============

Flask-CDN replaces the URLs that Flask's :func:`flask.url_for` function would
insert into your templates, with URLs that point to your CDN. This makes
setting up an origin pull CDN extremely easy.

Internally, every time ``url_for`` is called in one of your
application's templates, `flask_cdn.url_for` is instead invoked. If the
endpoint provided is deemed to refer to static assets, then the CDN URL
for the asset specified in the `filename` argument is instead returned.
Otherwise, `flask_cdn.url_for` passes the call on to `flask.url_for`.


Installation
============

If you use pip then installation is simply::

    $ pip install flask-cdn

or, if you want the latest github version::

    $ pip install git+git://github.com/wichitacode/flask-cdn.git

You can also install Flask-CDN via Easy Install::

    $ easy_install flask-cdn

Dependencies
------------

There are no additional dependencies besides Flask itself. **Note**: Flask-CDN
currently only supports applications that use the `jinja2`_ templating system.

.. _jinja2: http://jinja.pocoo.org/docs/


Using Flask-CDN
===============

Flask-CDN is incredibly simple to use. In order to start serving your
Flask application's assets from Amazon CDN, the first thing to do is let
Flask-CDN know about your :class:`flask.Flask` application object.

.. code-block:: python

    from flask import Flask
    from flask.ext.cdn import CDN

    app = Flask(__name__)
    app.config['CDN_DOMAIN'] = 'mycdnname.cloudfront.net'
    CDN(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-CDN provides a simple function,
``init_app``, which takes your application as an argument.

.. code-block:: python

    from flask import Flask
    from flask.ext.cdn import CDN

    cdn = CDN()

    def start_app():
        app = Flask(__name__)
        cdn.init_app(app)
        return app

In terms of getting your application to use external CDN URLs when
referring to your application's static assets, passing your ``Flask``
object to the ``CDN`` object is all that needs to be done. Once your
app is running, any templates that contained relative static asset
locations, will instead be pulled from your CDN.

Static Asset URLs
-----------------

URLs generated by Flask-CDN will look like the following:

``/static/foo/style.css`` becomes
``https://mycdnname.cloudfront.net/static/foo/style.css``, assuming
that ``mycdnname.cloudfront.net`` is the domain of your CDN, and you have
chosen to have assets served over HTTPS.

Flask-CDN Options
-----------------

Within your Flask application's settings you can provide the following
settings to control the behaviour of Flask-CDN. None of the settings are
required.

=========================== ===================================================
`CDN_DOMAIN`                Set the base domain for your CDN here.
                            **Default:** `None`
`CDN_HTTPS`                 Specifies whether or not to serve your assets over
                            HTTPS. If not specified the asset will be served
                            by the same method the request comes in as.
                            **Default:** `None`
`CDN_TIMESTAMP`             Specifies whether or not to add a timestamp to the
                            generated urls.
                            **Default:** `True`
`CDN_DEBUG`                 By default, Flask-CDN 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-CDN in debug mode, set this value to `True`.
                            **Default:** `False`
=========================== ===================================================

.. _debug: http://flask.pocoo.org/docs/config/#configuration-basics


Serve Static Assets with CloudFront
===================================

CloudFront is a very simple way to seamlessly serve your static assets with
it’s CDN. When a request comes into CloudFront, if the asset is not on the CDN
or has expired, then CloudFront can get the asset from an “origin server”.
This type of setup is called an origin pull CDN.

To setup a new CloudFront “Distribution”:

- Signup for an `AWS Account`_
- Open the `Cloudfront Management Console`_
- Select Create Distribution
- Leave Download selected as the delivery method and select Continue
- In the Origin Domain Name field enter the domain name for your application
{'fraction_non_alphanumeric': 0.11888042725744238, 'fraction_numerical': 0.0003956087429532193, 'mean_word_length': 2.993680884676145, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 3, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6835987', 'n_tokens_mistral': 2729, 'n_tokens_neox': 2583, 'n_words': 1202}