API

Environment

class gears.environment.Environment(root, cache=None)

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, supported MIME types and public assets.

Parameters:
  • root – the absolute path to the directory where handled public assets will be saved by save() method.
  • cache – a cache object. It is used by assets and dependencies to store compilation results.
compilers = None

The registry for asset compilers. See Compilers for more information.

compressors = None

The registry for asset compressors. See Compressors for more information.

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.

finders = None

The registry for file finders. See Finders for more information.

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/libs')

# 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')
mimetypes = None

The registry for supported MIME types. See MIMETypes for more information.

postprocessors = None

The registry for asset postprocessors. See Postprocessors for more information.

preprocessors = None

The registry for asset preprocessors. See Preprocessors for more information.

public_assets = None

The registry for public assets. Only assets from this registry will be saved to the root path. See PublicAsets for more information.

register_defaults()

Register default compilers, preprocessors, MIME types and public assets.

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.

register_defaults()

Register CoffeeScriptCompiler, HandlebarsCompiler, LessCompiler and StylusCompiler for .coffee, .handlebars, .less and .styl extensions, respectively.

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.

Public Assets Registry

class gears.environment.PublicAssets

The registry for public assets. It acts like a list of logical paths of assets.

register(path)

Register passed path as public asset.

register_defaults()

Register css/style.css and js/script.js as public assets.

unregister(path)

Remove passed path from registry. If path 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.

dirname = None

The relative path to the directory the asset.

environment = None

Used to access the registries of compilers, processors, etc. It can be also used by asset. See Environment for more information.

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 = None

The relative (or logical) path to 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 format extension. Example:

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

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.

executable = None

The name of the executable to run. It must be a command name, if it is available in the PATH environment variable, or a path to the executable.

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.

params = []

The list of executable parameters.

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.

result_mimetype = None

MIME type of the asset source code after compiling.

Project Versions

Table Of Contents

Previous topic

Installation

Next topic

Changelog

This Page