Metadata-Version: 1.1
Name: pyramid-webassets
Version: 0.9
Summary: pyramid_webassets
Home-page: http://github.com/sontek/pyramid_webassets
Author: John Anderson
Author-email: sontek@gmail.com
License: UNKNOWN
Description: Installation
        ===================
        
        [![Build Status](https://travis-ci.org/sontek/pyramid_webassets.svg?branch=master)](https://travis-ci.org/sontek/pyramid_webassets)
        [![Coverage](https://img.shields.io/coveralls/sontek/pyramid_webassets.svg)](https://coveralls.io/r/sontek/pyramid_webassets)
        
        Install the package:
        
        ``` bash
        $ pip install pyramid_webassets
        ```
        
        EITHER add it to your Pyramid `production.ini` and `development.ini`:
        
        ```
        pyramid.includes =
            pyramid_debugtoolbar
            pyramid_tm
            pyramid_webassets
        ```
        
        OR include it when configuring your application, usually in `__init__.py`:
        
        ``` python
        def main(global_config, **settings):
            ...
            config.include('pyramid_webassets')
        ```
        
        Configuration
        ====================
        You are required to set ``base_dir`` and ``base_url``, the rest are optional,
        but we currently support:
        
         * ``base_dir``: The directory to output and search for assets
         * ``base_url``: The url static assets will be located
         * ``debug``: If webassets should be in debug mode (i.e no compression)
         * ``updater``: Different update configurations (i.e always, timestamp)
         * ``cache``: If we should use webassets cache (if boolean), or override default path to cache directory
         * ``jst_compiler``: A custom jst compiler, by default it uses underscore
         * ``url_expire``: If a cache-busting query string should be added to URLs
         * ``static_view``: If assets should be registered as a static view using Pyramid config.add_static_view()
         * ``cache_max_age``: If static_view is true, this is passed as the static view's cache_max_age argument (allowing control of expires and cache-control headers)
         * ``paths``: A JSON dictionary of PATH=URL mappings to add paths to alternative asset locations (`URL` can be null to only add the path)
         * ``bundles``: filename or [asset-spec] (or a list of either) (http://docs.pylonsproject.org/projects/pyramid/en/latest/glossary.html#term-asset-specification) of a YAML [bundle spec](http://webassets.readthedocs.org/en/latest/loaders.html?highlight=loader#webassets.loaders.YAMLLoader) whose bundles will be auto-registered
        
        ``` ini
        webassets.base_dir              = %(here)s/app/static
        webassets.base_url              = static
        webassets.debug                 = True
        webassets.updater               = timestamp
        webassets.cache                 = False
        webassets.jst_compiler          = Handlebars.compile
        webassets.url_expire            = False
        webassets.static_view           = True
        webassets.cache_max_age         = 3600
        webassets.bundles               = mypackage:webassets.yaml
        ```
        
        Then you can just use config.add_webasset to add bundles to your environment
        
        ``` python
        from webassets import Bundle
        
        jst = Bundle('templates/*.html',
                filters='jst',
                output='js/jst.js', debug=False)
        
        config.add_webasset('jst', jst)
        ```
        
        All other configurations are passed through to webassets, including
        filter settings. These are adjusted as follows: if a value is exactly
        ``true`` or ``false``, then it is converted to a boolean; if a value
        is prefixed with the string ``json:``, then it is JSON-parsed. This
        allows pyramid-webassets to handle basic extensible filter
        configurations without needing any python code, for example:
        
        ``` ini
        webassets.less_run_in_debug     = true
        webassets.less_extra_args       = json:["--line-numbers=mediaquery", "-O2"]
        ```
        
        Use asset specs instead of files and urls
        ----------------------------------------------
        It's possible to use an asset specifications (package:file) instead of simple file names.
        
        - If the asset specifications declares a path outside the base_dir, the file will be copied.
        - Otherwise, it will work like a normal bundle file.
        
        If files are bundled from other packages and those packages act like pyramid
        plugins adding their own ``add_static_view``, webassets will use those static
        view urls to show the individual files if needed (for example, in development mode).
        
        If you have defined your own static route and you want to use it with webassets,
        for example:
        
        ``` python
        config.add_static_view('static-stuff', 'my.super.app:static')
        ```
        
        Setting the base url configuration option to an asset specification:
        
        ```
        base_url = my.super.app:static
        ```
        
        Will make webassets use the ``/static-stuff`` route for your assets. Note:
        the absolute or relative path depends on where is your application is deployed.
        
        Use with templates
        ========================
        Included are helpers that you can use with your templates. Additional helpers
        are documented below in the section labeled "Extras".
        
        Mako
        -----
        
        You can use the global webassets tag:
        ``` python
        % for url in webassets(request, 'css/bootstrap.css', 'css/bootstrap-responsive.css', output='css/generated.css', filters='cssmin'):
            <link href="${url}" rel="stylesheet">
        % endfor
        ```
        
        or you can grab the environment from the request.
        
        Jinja2
        -------
        If you are using Jinja2, you can just do the following configuration (this assumes use of pyramid_jinja2):
        
        ``` python
        config.add_jinja2_extension('webassets.ext.jinja2.AssetsExtension')
        assets_env = config.get_webassets_env()
        jinja2_env = config.get_jinja2_environment()
        jinja2_env.assets_environment = assets_env
        ```
        and then:
        
        ``` python
        {% assets "jst" %}
        <script type="text/javascript" src="{{ ASSET_URL }}"></script>
        {% endassets %}
        ```
        
        Generic
        --------
        It's always possible to access the environment from the request.
        
        ```python
        jst_urls = request.webassets_env['jst'].urls()
        ```
        
        Extras
        ====================
        
        There are a few more utility methods you can use to make working with webassets
        within your Pyramid application easier.
        
        Configuration
        ---------------
        These methods can be called on the `Configurator` instance during startup:
        
        ``add_webasset(name, bundle)``: Registers a bundle with webassets
        
        ``add_webassets_setting(key, value)``: Update the environment configuration
        
        ``add_webassets_path(path, url)``: Append a URL mapping to the environment
        
        ``get_webassets_env_from_settings(settings, prefix='static_assets')``: Pass a
        dictionary of your settings and an optional keyword argument of the prefix in
        your configuration and it will return a webassets environment.
        
        ``get_webassets_env()``: This will pull the environment out of the registry.
        
        Request handling
        ------------------
        These properties and helpers are attached to the `Request` object:
        
        ``request.webassets_env``: Access the webassets environment
        
        ``request.webassets(*bundle_names, **kwargs)``: Build the named bundles.
        Keyword arguments will be passed to webassets to influence bundling.
        
        Building assets from a script
        =======================================
        The `webassets` module includes a command line script, also called `webassets`,
        which can be used to build bundles offline. When integrating with Pyramid, it
        can be helpful to bootstrap the environment using paster instead, like so:
        
        ``` python
        import pyramid.paster
        import webassets.script
        
        app_env = pyramid.paster.bootstrap('config.ini')
        assets_env = app_env['request'].webasset_env
        webassets.script.main(['build'], assets_env)
        ```
        
        
        0.9 (2014-10-21)
        ================
        
        Features
        --------
        
        - Support for overriding named bundles when using the ``webassets.bundles``
          setting. Files earlier in the list take precedence and can override named
          bundles defined in later files. Combined with asset specifications for the
          file names this makes it easy to extend the bundle configuration of other
          packages.
        
        0.8 (2014-08-04)
        ================
        
        Features
        --------
        
        - Support versions of webassets v0.8.x, v0.9.x, and 0.10.x.
        
        - Support glob specifications for input files.
        
        - Introduced support for specifying the base directory and input files, and
          output directories using asset specs. Patches by Randall Leeds and John
          Anderson, documentation by Javier Gonel. See
          https://github.com/pyramid_webassets/issues/13
          https://github.com/pyramid_webassets/issues/14
          https://github.com/pyramid_webassets/issues/31 and
          https://github.com/pyramid_webassets/issues/41 .
        
        - A new configuration directive, ``add_webassets_setting``, that updates the
          provided key and value in the webassets environment configuration can be
          called from ``Configurator`` instances.
        
        - A new configuration directive, ``add_webassets_path``, that adds an
          additional mapping from a path to a URL prefix can be called from
          ``Configurator`` instances. Patch by Jason Brumwell.
        
        - Support for ``auto_build``, ``jst_namespace``, and ``url_expire``
          webassets settings. Patches by Svante Paldan, Olaf Conradi, and Randall
          Leeds. See https://github.com/pyramid_webassets/issues/15
          https://github.com/pyramid_webassets/issues/17 and
          https://github.com/pyramid_webassets/issues/20 .
        
        - A new ``paths`` setting allows a JSON dictionary of mappings from paths to
          URLs to be specified in order to support multiple load paths and URL
          prefixes. Patch by metagriffin.
        
        - Support for multiple values in the ``load_path`` setting. Patch by Greg
          Kempe. See https://github.com/pyramid_webassets/issues/33 .
        
        - A new ``cache_max_age`` setting controls the expiration and caching
          behavior of the static view. The value of this setting is passed through to
          the ``add_static_view`` invocation.
        
        - A ``bundles`` setting can now be specified which lists YAML files to parse
          for bundle definitions. Earlier entries override bundles defined in later
          entries. Patch by metagriffin and multiple value support by Randall Leeds.
          See https://github.com/pyramid_webassets/issues/35 .
        
        - Configuration values prefixed with the string 'json:' are parsed as JSON
          before being passed to webassets. Patch by metagriffin.
        
        Bug Fixes
        ---------
        
        - Assets can now be built without an active request.
        
        - The ``cache`` and ``manifest`` options now support valid non-boolean values
          as described by the webassets documentation. Patch by Mike Wirth. See
          https://github.com/pyramid_webassets/issues/11 .
        
        - If the ``cache`` argument specifies a directory ensure that it exists.
          Patch by metagriffin. See https://github.com/pyramid_webassets/issues/29 .
        
        Documentation
        -------------
        
        - Cleaned up documentation markup. Patch by Michael Merickel.
          https://github.com/pyramid_webassets/issues/18
        
        - Fix typo in documentation of ``url_expire`` setting. The setting had been
          spelled (incorrectly) as ``url_expires``. Patch by Greg Kempe.
          See https://github.com/pyramid_webassets/issues/34 .
        
        - Add an example of building assets from the command line.
        
        - Include the MIT License.
        
        Backwards Incompatibilities
        ---------------------------
        
        - Support for webassets releases older than v0.8 has been dropped.
        
        - A static view for the configured directory and url is no longer added
          automatically. Set the configuration value ``static_views`` to true to have
          it added when pyramid_webassets is included.
        
Keywords: web wsgi bfg pylons pyramid
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Framework :: Pylons
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
