API¶
Environment¶
- class gears.environment.Environment(root, public_assets=(<function <lambda> at 0x2c96668>, '^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 environment 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.
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.