Using with Flask

This guide explains how to use libsass with the Flask web framework. sassutils package provides several tools that can be integrated into web applications written in Flask.

Directory layout

Imagine the project contained in such directory layout:

  • setup.py

  • myapp/

    • __init__.py

    • static/

      • sass/

      • css/

    • templates/

Sass/SCSS files will go inside myapp/static/sass/ directory. Compiled CSS files will go inside myapp/static/css/ directory. CSS files can be regenerated, so add myapp/static/css/ into your ignore list like .gitignore or .hgignore.

Defining manifest

The sassutils defines a concept named manifest. Manifest is the build settings of Sass/SCSS. It specifies some paths related to building Sass/SCSS:

  • The path of the directory which contains Sass/SCSS source files.

  • The path of the directory which the compiled CSS files will go.

  • The path, exposed to HTTP (through WSGI), of the directory that will contain the compiled CSS files.

Every package may have its own manifest. Paths have to be relative to the path of the package.

For example, in the above project, the package name is myapp. The path of the package is myapp/. The path of the Sass/SCSS directory is static/sass/ (relative to the package directory). The path of the CSS directory is static/css/. The exposed path is /static/css.

These settings can be represented as the following manifests:

{
    'myapp': ('static/sass', 'static/css', '/static/css')
}

As you can see the above, the set of manifests are represented in dictionary, in which the keys are packages names and the values are tuples of paths.

Building Sass/SCSS for each request

See also

Flask — Hooking in WSGI Middlewares

The section which explains how to integrate WSGI middlewares to Flask.

Flask — flask:app-dispatch

The documentation which explains how Flask dispatches each request internally.

In development, manually building Sass/SCSS files for each change is a tedious task. SassMiddleware makes the web application build Sass/SCSS files for each request automatically. It’s a WSGI middleware, so it can be plugged into the web app written in Flask.

SassMiddleware takes two required parameters:

  • The WSGI-compliant callable object.

  • The set of manifests represented as a dictionary.

So:

from flask import Flask
from sassutils.wsgi import SassMiddleware

app = Flask(__name__)

app.wsgi_app = SassMiddleware(app.wsgi_app, {
    'myapp': ('static/sass', 'static/css', '/static/css')
})

And then, if you want to link a compiled CSS file, use the url_for() function:

<link href="{{ url_for('static', filename='css/style.scss.css') }}"
      rel="stylesheet" type="text/css">

Note

The linked filename is style.scss.css, not just style.scss. All compiled filenames have trailing .css suffix.

Building Sass/SCSS for each deployment

Note

This section assumes that you use setuptools for deployment.

See also

Flask — flask:distribute-deployment

How to deploy Flask application using setuptools.

If libsass is installed in the site-packages (for example, your virtualenv), the setup.py script also gets a new command provided by libsass: build_sass. The command is aware of the sass_manifests option of setup.py and builds all Sass/SCSS sources according to the manifests.

Add these arguments to setup.py script:

setup(
    # ...,
    setup_requires=['libsass >= 0.6.0'],
    sass_manifests={
        'myapp': ('static/sass', 'static/css', '/static/css')
    }
)

The setup_requires option makes sure that libsass is installed in site-packages (for example, your virtualenv) before the setup.py script. That means if you run the setup.py script and libsass isn’t installed in advance, it will automatically install libsass first.

The sass_manifests specifies the manifests for libsass.

Now setup.py build_sass will compile all Sass/SCSS files in the specified path and generates compiled CSS files inside the specified path (according to the manifests).

If you use it with sdist or bdist commands, the packed archive will also contain the compiled CSS files!

$ python setup.py build_sass sdist

You can add aliases to make these commands always run the build_sass command first. Make setup.cfg config:

[aliases]
sdist = build_sass sdist
bdist = build_sass bdist

Now it automatically builds Sass/SCSS sources and include the compiled CSS files to the package archive when you run setup.py sdist.