Skip to content
Compiles and concatenates JavaScript and CSS assets. Inspired by Ruby's Sprockets.
Python Shell JavaScript Other
Failed to load latest commit information.
docs
gears Another try to implement public directive Apr 24, 2014
tests Fix UnicodeDecodeError during installation using pip 1.5.* Apr 28, 2014
.gitignore #10: Added support for Python 3, cleaned up the code from future imports Oct 12, 2012
.travis.yml Remove python 3.2 support, as glob2 package doesn't support it Apr 22, 2014
AUTHORS Add Yaoda Liu to the authors list Jan 29, 2014
LICENSE 2012 -> 2013 Apr 6, 2013
MANIFEST.in Avoid code duplication in tests Dec 2, 2012
Makefile Add Makefile with 'clean' task Nov 25, 2011
README.rst Mention public directive in readme Apr 28, 2014
setup.py Bump version number Apr 28, 2014
tox.ini

README.rst

Gears

https://secure.travis-ci.org/gears/gears.png?branch=develop

Gears is a library to compile and concatenate JavaScript and CSS assets, highly inspired by Ruby's Sprockets. You can also write scripts, styles and client templates using CoffeeScript, Handlebars, Stylus, Less, and compile them using external packages (gears-coffeescript, gears-handlebars, gears-stylus, gears-less). These packages already include all required node.js modules, so you don't need to worry about installing them yourself.

There is also:

  • django-gears, an app for Django that integrates Gears with Django project;
  • Flask-Gears, an extension that integrates Gears with Flask application;
  • gears-cli, a command-line utility that compiles assets. It also can watch assets for changes and automaticaly re-compile them.

Features

  • Dependency management using directives in header comments. For example:

    /* Dependencies:
     *= require jquery
     *= require underscore
     *= require backbone
     *= require_tree views
     *= require_directory templates
     */
    

    Six directive types is supported for now:

    • require :path: includes the contents of the asset path suffixed with the same extension as the current asset (e.g., if js/app.js.coffee has directive require views, js/views.js.coffee will be included). Supports globbing: require models/*.
    • require_directory :path: includes the contents of the every asset in the directory path with the same suffix as the current asset in alphabetical order.
    • require_tree :path: includes the contents of the every asset with the same suffix as the current asset in the directory path and all its subdirectories in alphabetical order.
    • require_self: includes the contents of the current asset at the current place. If there is no require_self directive, the contents will be appended at the end of asset.
    • depend_on :path: it is useful when you need to specify files that affect an asset, but not to include them into bundled asset or to include them using compilers. E.g., if you use @import functionality in some CSS pre-processors (Less or Stylus). Supports globbing: depend_on app/*.
    • public: mark the asset as public.
  • Scripting and styling in modern languages like CoffeeScript, Stylus, Less (support for new languages can be easily added).

  • Writing client templates using Handlebars.

  • The list of compilers for the asset is specified with asset extensions appended to the original extension. E.g., for the asset named js/app.js.coffee CoffeeScript compiler will be used. Here are extensions for the supported compilers (through external packages):

    • CoffeeScript - .js.coffee;
    • Handlebars - .js.handlebars;
    • Stylus - .css.styl;
    • Less - .css.less.
  • Caching

  • Compressing. Supported compressors:

    New compilers can be also easily added.

  • Supports Python 3.

Installation

You can install Gears using pip:

$ pip install Gears

If you want to use node.js-dependent compilers or compressors, you need to install other dependencies:

$ pip install gears-less          # LESS
$ pip install gears-stylus        # Stylus
$ pip install gears-handlebars    # Handlebars
$ pip install gears-coffeescript  # CoffeeScript

$ pip install gears-uglifyjs      # UglifyJS
$ pip install gears-clean-css     # clean-css

Please note that all these compilers and compressors require node.js to be installed on your system.

Usage

This example compiles public assets (default: assets/js/script.js, assets/css/style.css, all assets that aren't compiled to .css or .js and assets marked as public using public directive) from assets directory to static:

import os

from gears.environment import Environment
from gears.finders import FileSystemFinder


ROOT_DIR = os.path.abspath(os.path.dirname(__file__))
ASSETS_DIR = os.path.join(ROOT_DIR, 'assets')
STATIC_DIR = os.path.join(ROOT_DIR, 'static')

env = Environment(STATIC_DIR)
env.finders.register(FileSystemFinder([ASSETS_DIR]))
env.register_defaults()

if __name__ == '__main__':
    env.save()

There is already mentioned django-gears app, which you may want to use in your Django projects.

Contributing

Feel free to fork, send pull requests or report bugs and issues on github.

Something went wrong with that request. Please try again.