pyramid_assetmutator provides simple and flexible asset mutation (also known
as compiling or piping) for your Pyramid applications.
Its goal is to provide Pyramid developers with a basic and straightforward mechanism for utilizing asset compilation (e.g. for CoffeeScript/Sass), minification (e.g. with jsmin), and optimization (e.g. with pngcrush).
As of version 0.3, it also adds experimental support for template language
parsing (e.g. you could use Pyramid helpers like
your CoffeeScript files by using
application.coffee.pt as the asset source
This package only supports Pyramid 1.3 or later.
To install, simply:
pip install pyramid_assetmutator
pyramid_assetmutator is installed, you must include it in your Pyramid
project's configuration. This is typically done using Pyramid's
:meth:`config.include <pyramid.config.Configurator.include>` mechanism in your
config = Configurator(...) config.include('pyramid_assetmutator')
Next, you must assign one or more mutators via the newly injected
:meth:`~pyramid_assetmutator.assign_assetmutator` configuration method, so that
your application can know what kind of assets you'll be asking it to mutate. The
configuration syntax for your Pyramid project's
config.assign_assetmutator('SOURCE EXTENSION', 'COMMAND', 'OUTPUT EXTENSION')
For example, the following configuration would activate
in your app, and initialize mutators for CoffeeScript and Less files (allowing
config = Configurator(...) config.include('pyramid_assetmutator') config.assign_assetmutator('coffee', 'coffee -c -p', 'js') config.assign_assetmutator('less', 'lessc', 'css')
Once you have included the module and configured your mutators, you will then be able to call one of the following view helper methods in your templates to reference (with Pyramid's asset specification syntax) and "mutate" (if needed) an asset:
.. automodule:: pyramid_assetmutator :noindex:
.. autoclass:: AssetMutator :noindex: :members:
Template Language Parsing
In version 0.3, experimental support for template language parsing was added. As long as the template language is known to Pyramid (e.g. one of these bindings has been configured), you can append the expected template filename extension to your asset filename and it will attempt to parse it before mutation.
For example, if the
pyramid_jinja2 package was configured, you could specify
an asset path to an asset named
pyramid_assetmutator would run it through the Jinja2 renderer before
Current support is experimental, and there are a few caveats:
- You must specify a
mutated_pathin your configuration so that the intermediate-step sources can be stored and parsed from that directory.
- Template parsing is currently only supported when using the
each_requestconfiguration (which is the default configuration).
- If Pyramid's "reload_templates" setting is false, templates will _NOT_ be reprocessed.
- Hopefully obvious, but if the asset you are parsing uses a syntax that conflicts with the template language's syntax, things probably won't work out very well for you.
An example using the Chameleon template language (and assuming that a mutator has been assigned for "coffee" files):
And now the same example, but for
inline code output:
Or, if your default JS mutator configuration uses
jsmin, but you wanted to
uglifyjs for a particular asset:
As of version 0.3, your asset source could be parsed with Chameleon as well:
You can assign as many mutators as you like using the
config.assign_assetmutator method, but it is important to keep in mind the
- The mutator
COMMANDmust be installed, must be executable by the Pyramid process, and by default must output the mutated data to stdout. The last point can be tricky depending on the command, so be sure to check its command switches for the appropriate option (or create a wrapper as seen below).
Here are a few mutator commands that have been tested and are known to work as of this writing:
While the default settings will probably be fine for most people, custom
settings can be configured via your Pyramid application's
.ini file (in the
app section representing your Pyramid app) using the
Default: stat Options: exists | stat | checksum
Defines what type of method to use for checking if an asset source has been updated (and should therefore be remutated). If set to
exists(fastest, but not always ideal), then it will only check to see if a file matching the mutated version of the asset already exists. If set to
stat, then the size and last modified time will be checked. If set to
checksum(slowest, but most reliable), then the file contents will also be checked.
Whether or not assets should be checked/mutated during each request (whenever one of the
assetmutator_*methods is encountered).
Limited "globbing" support is available (via the :mod:`glob` module), although checks are not recursive so you must be explicit.
e.g.:assetmutator.each_boot = myapp:static/js/application.coffee myapp:static/css/*.sass myapp:static/css/admin/*.sass
A prefix to add to the mutated asset's output filename.
By default, mutated output files are stored in the same directory as their source files. If you would like to keep all mutated files in a specific directory, you can define a Pyramid asset specification here (e.g.
true, if a valid
mutated_pathis specified then any files within it will be deleted when the application boots (uses Pyramid's :class:`~pyramid.events.ApplicationCreated` event).
Defines a list of asset specifications that should always be remutated --- even if the mutated version of the asset is already present.
Limited "globbing" support is available (via the :mod:`fnmatch` module), so a value of
*.sasswould match all Sass sources, while a star value (
*) would specify that all sources should always be remutated.
e.g.:assetmutator.always_remutate = *.sass myapp:static/js/application.coffee
Combining this with the
each_requestsetting can be useful in development environments when your source files contain imports and therefore may not always change but should still be remutated so that import changes are processed. However, this can significantly affect performance so it should only be utilized in environments that require it. Alternatively, you may use a
stat(the default) or
checksumand manually "touch" a source file to trigger a remutate on the next request.
As an example, if you wanted to only check/mutate assets on each boot (a good
practice for production environments), processing CoffeeScript and Sass files in
css root and admin directories, with each mutated
_filename stored in a
myapp:static/cache/ directory, your
would look something like:
[app:main] ...other settings... assetmutator.each_request = false assetmutator.each_boot = myapp:static/js/*.coffee myapp:static/js/admin/*.coffee myapp:static/css/*.sass myapp:static/css/admin/*.sass assetmutator.mutated_path = myapp:static/cache/
Asset Concatenation (a.k.a Asset Pipeline)
A feature that is popular in some web frameworks (e.g. Ruby on Rails) is the
ability to combine all assets that share a common type into a single file for
sourcing within your templates. However, this functionality is currently
beyond the scope of
pyramid_assetmutator as we consider it to have less and
less relevance in an HTTP/2 era.
.. toctree:: :maxdepth: 1 api.rst
Development Versions / Reporting Issues
Visit http://github.com/seedifferently/pyramid_assetmutator to download development or tagged versions.
Visit http://github.com/seedifferently/pyramid_assetmutator/issues to report issues.