API

Environment

class gears.environment.Environment(root, public_assets=(<function <lambda> at 0x3542230>, '^css/style\.css$', '^js/script\.js$'), manifest_path=None, cache=None, gzip=False, fingerprinting=True)

This is the central object, that links all Gears parts. It is passed the absolute path to the directory where public assets will be saved. Environment contains registries for file finders, compilers, compressors, processors and supported MIME types.

Parameters:
  • root – the absolute path to the directory where handled public assets will be saved by save() method.
  • public_assets – a list of public assets paths.
  • cache – a cache object. It is used by assets and dependencies to store compilation results.
  • fingerprinting – if set to True, fingerprinted versions of assets won’t be created.
find(item, logical=False)

Find files using finders registry. The item parameter can be an instance of AssetAttributes class, a path to the asset or a logical path to the asset. If item is a logical path, logical parameter must be set to True.

Returns a tuple with AssetAttributes instance for found file path as first item, and absolute path to this file as second item.

If nothing is found, gears.exceptions.FileNotFound exception is rased.

list(path, mimetype=None)

Yield two-tuples for all files found in the directory given by path parameter. Result can be filtered by the second parameter, mimetype, that must be a MIME type of assets compiled source code. Each tuple has AssetAttributes instance for found file path as first item, and absolute path to this file as second item.

Usage example:

# Yield all files from 'js/templates' directory.
environment.list('js/templates/*')

# Yield only files that are in 'js/templates' directory and have
# 'application/javascript' MIME type of compiled source code.
environment.list('js/templates/*', mimetype='application/javascript')
paths

The list of search paths. It is built from registered finders, which has paths property. Can be useful for compilers to resolve internal dependencies.

register_defaults()

Register default compilers, preprocessors and MIME types.

register_entry_points(exclude=())

Allow Gears plugins to inject themselves to the environment. For example, if your plugin’s package contains such entry_points definition in setup.py, gears_plugin.register function will be called with current enviroment during register_entry_points call:

entry_points = {
    'gears': [
        'register = gears_plugin:register',
    ],
}

Here is an example of such function:

def register(environment):
    assets_dir = os.path.join(os.path.dirname(__file__), 'assets')
    assets_dir = os.path.absolute_path(assets_dir)
    environment.register(FileSystemFinder([assets_dir]))

If you want to disable this behavior for some plugins, list their packages using exclude argument:

environment.register_entry_points(exclude=['plugin'])
save()

Save handled public assets to root directory.

suffixes

The registry for supported suffixes of assets. It is built from MIME types and compilers registries, and is cached at the first call. See Suffixes for more information.

File Finders Registry

class gears.environment.Finders

The registry for file finders. This is just a list of finder objects. Each finder object must be an instance of any BaseFinder subclass. Finders from this registry are used by Environment object in the order they were added.

register(finder)

Append passed finder to the list of finders.

unregister(finder)

Remove passed finder from the list of finders. If finder does not found in the registry, nothing happens.

MIME Types Registry

class gears.environment.MIMETypes

The registry for MIME types. It acts like a dict with extensions as keys and MIME types as values. Every registered extension can have only one MIME type.

register(extension, mimetype)

Register passed mimetype MIME type with extension extension.

register_defaults()

Register MIME types for .js and .css extensions.

unregister(extension)

Remove registered MIME type for passed extension extension. If MIME type for this extension does not found in the registry, nothing happens.

Compilers Registry

class gears.environment.Compilers

The registry for compilers. It acts like a dict with extensions as keys and compilers as values. Every registered extension can have only one compiler.

register(extension, compiler)

Register passed compiler with passed extension.

unregister(extension)

Remove registered compiler for passed extension. If compiler for this extension does not found in the registry, nothing happens.

Preprocessors Registry

class gears.environment.Preprocessors

The registry for asset preprocessors. It acts like a dictionary with MIME types as keys and lists of processors as values. Every registered MIME type can have many preprocessors. Preprocessors for the MIME type are used in the order they were added.

register_defaults()

Register DirectivesProcessor as a preprocessor for text/css and application/javascript MIME types.

Postprocessors Registry

class gears.environment.Postprocessors

The registry for asset postprocessors. It acts like a dictionary with MIME types as keys and lists of processors as values. Every registered MIME type can have many postprocessors. Postprocessors for the MIME type are used in the order they were added.

Compressors Registry

class gears.environment.Compressors

The registry for asset compressors. It acts like a dictionary with MIME types as keys and compressors as values. Every registered MIME type can have only one compressor.

register(mimetype, compressor)

Register passed compressor for passed mimetype.

unregister(mimetype)

Remove registered compressors for passed mimetype. If compressor for this MIME type does not found in the registry, nothing happens.

Suffixes Registry

class gears.environment.Suffixes

The registry for asset suffixes. It acts like a list of dictionaries. Every dictionary has three keys: extensions, result_mimetype and mimetype:

  • suffix is a suffix as a list of extensions (e.g. ['.js', '.coffee']);
  • result_mimetype is a MIME type of a compiled asset with this suffix;
  • mimetype is a MIME type, for which this suffix is registered.

Asset Attributes

class gears.asset_attributes.AssetAttributes(environment, path)

Provides access to asset path properties. The attributes object is created with environment object and relative (or logical) asset path.

Some properties may be useful or not, depending on the type of passed path. If it is a relative asset path, you can use all properties except search_paths. In case of a logical asset path it makes sense to use only those properties that are not related to processors and compressor.

Parameters:
  • environment – an instance of Environment class.
  • path – a relative or logical path of the asset.
compiler_extensions

The list of compiler extensions. Example:

>>> attrs = AssetAttributes(environment, 'js/lib/external.min.js.coffee')
>>> attrs.compiler_extensions
['.coffee']
compiler_format_extension

Implicit format extension on the asset by its compilers.

compiler_mimetype

Implicit MIME type of the asset by its compilers.

compilers

The list of compilers used to build asset.

compressor

The compressors used to compress the asset.

extensions

The list of asset extensions. Example:

>>> attrs = AssetAttributes(environment, 'js/models.js.coffee')
>>> attrs.extensions
['.js', '.coffee']

>>> attrs = AssetAttributes(environment, 'js/lib/external.min.js.coffee')
>>> attrs.format_extension
['.min', '.js', '.coffee']
format_extension

The format extension of asset. Example:

>>> attrs = AssetAttributes(environment, 'js/models.js.coffee')
>>> attrs.format_extension
'.js'

>>> attrs = AssetAttributes(environment, 'js/lib/external.min.js.coffee')
>>> attrs.format_extension
'.js'
logical_path

The logical path to asset. Example:

>>> attrs = AssetAttributes(environment, 'js/models.js.coffee')
>>> attrs.logical_path
'js/models.js'
mimetype

MIME type of the asset.

path_without_suffix

The relative path to asset without suffix. Example:

>>> attrs = AssetAttributes(environment, 'js/app.js')
>>> attrs.path_without_suffix
'js/app'
postprocessors

The list of postprocessors used to build asset.

preprocessors

The list of preprocessors used to build asset.

processors

The list of all processors (preprocessors, compilers, postprocessors) used to build asset.

search_paths

The list of logical paths which are used to search for an asset. This property makes sense only if the attributes was created with logical path.

It is assumed that the logical path can be a directory containing a file named index with the same suffix.

Example:

>>> attrs = AssetAttributes(environment, 'js/app.js')
>>> attrs.search_paths
['js/app.js', 'js/app/index.js']

>>> attrs = AssetAttributes(environment, 'js/app/index.js')
>>> attrs.search_paths
['js/models/index.js']
suffix

The list of asset extensions starting from the first known extension. Example:

>>> attrs = AssetAttributes(environment, 'js/lib/external.min.js.coffee')
>>> attrs.suffix
['.js', '.coffee']
unknown_extensions

The list of unknown extensions, which are actually parts of asset filename. Example:

>>> attrs = AssetAttributes(environment, 'js/lib-2.0.min.js')
>>> attrs.suffix
['.0', '.min']

Asset Handlers

class gears.asset_handler.BaseAssetHandler

Base class for all asset handlers (processors, compilers and compressors). A subclass has to implement __call__() which is called with asset as argument.

__call__(asset)

Subclasses have to override this method to implement the actual handler function code. This method is called with asset as argument. Depending on the type of the handler, this method must change asset state (as it does in Directivesprocessor) or return some value (in case of asset compressors).

classmethod as_handler(**initkwargs)

Converts the class into an actual handler function that can be used when registering different types of processors in Environment class instance.

The arguments passed to as_handler() are forwarded to the constructor of the class.

class gears.asset_handler.ExecMixin

Provides the ability to process asset through external command.

get_args()

Returns the list of subprocess.Popen arguments.

get_process()

Returns subprocess.Popen instance with args from get_args() result and piped stdin, stdout and stderr.

run(input)

Runs executable with input as stdin. AssetHandlerError exception is raised, if execution is failed, otherwise stdout is returned.

Processors

class gears.processors.BaseProcessor

Base class for all asset processors. Subclass’s __call__() method must change asset’s processed_source attribute.

Compilers

class gears.compilers.BaseCompiler

Base class for all asset compilers. Subclass’s __call__() method must change asset’s processed_source attribute.