===========================
RevAssets
===========================

.. image:: https://travis-ci.org/jpscaletti/rev-assets.svg?branch=master
   :target: https://travis-ci.org/jpscaletti/rev-assets
   :alt: Build Status

You care about the performance of your site, so you've configured the web server to cache all your assets for a long time. The most used way to bypass that cache when deploying a new version, is to add a hash of the assets to their names.
::
	'scripts/home.js' --> 'scripts/home.1a23b.js'
	'styles/home.css' --> 'styles/home.aef45.css'

The problem is, now your Python web app can't find the file unless you manually –and painstakingly— update all the URLs in the templates.

.. code:: html+jinja

	<script src="{{ url_for('static', filename='scripts/home.js') }}></script>
	<link rel="stylesheet" href="{{ url_for('static', filename='styles/home.css') }}</script>

Whit this library, there is no need for that. Just change your templates to:

.. code:: html+jinja

	<script src="{{ 'scripts/home.js' | asset_url }}></script>
	<link rel="stylesheet" href="{{ 'styles/home.css' | asset_url }}</script>

and use this code:

.. code:: python

	# app.py
	from flask import Flask, render_template
	from rev_assets import RevAssets

	app = flask.Flask(__name__)

	rev = RevAssets(reload=app.debug)
	app.context_processor(lambda: {'asset_url': rev.asset_url})

	@app.route('/')
	def index():
	    return render_template('index.html')

and it will work for every version of the assets that you build.

This works by reading the ``manifest.json`` generated by the revision tool (so don't forget to configure your task runner to make one).

You can continue to use the old method to link un-versioned assets, like ``favicon.ico`` and others like it.

Note that *this is not a Flask extension*, but a Python library. You can use it with any other framework. You can also have many instances of ``RevAssets`` linked to differents manifests.


Run the tests
======================

We use some external dependencies, listed in ``requirements_tests.txt``::

    $  pip install -r requirements-tests.txt
    $  python setup.py develop

To run the tests in your current Python version do::

    $  make test

To run them in every supported Python version do::

    $  tox

Our test suite `runs continuously on Travis CI <https://travis-ci.org/jpscaletti/rev-assets>`_ with every update.


Contributing
======================

#. Check for `open issues <https://github.com/jpscaletti/rev-assets/issues>`_ or open
   a fresh issue to start a discussion around a feature idea or a bug.
#. Fork the `RevAssets repository on Github <https://github.com/jpscaletti/rev-assets>`_
   to start making your changes.
#. Write a test which shows that the bug was fixed or that the feature works
   as expected.
#. Send a pull request and bug the maintainer until it gets merged and published.
   :) Make sure to add yourself to ``AUTHORS``.

______

:copyright: `Juan-Pablo Scaletti <http://jpscaletti.com/>`_.
:license: BSD-3-Clause, see LICENSE.
