WebDepCompress 0.2
JavaScript and CSS Compression Package
License: BSD

webdepcompress
    ~~~~~~~~~~~~~~

    This package implements a simple framework-independent system for web
    dependency compression.  With the help of various compressors it
    compresses JavaScript and CSS if necessary and allows a fallback if
    the files are used uncompressed (developer mode).

    This package provides a naive, whitespace removing compressor for
    CSS and JavaScript but a powerful, yuicompressor based compressing
    algorithm will be available from the pypi that is used automatically
    if available.  This makes it possible to ship this package with an
    application for production usage and precompressed files without
    having to install yuicompressor and Java.

    Declaring Packs
    ---------------

    Add a file to your package (for example packs.py) with the following
    contents::

        from webdepcompress.manager import PackManager

        mgr = PackManager(os.path.join(os.path.dirname(__file__), 'static'),
                          lambda fn, t: '/static/' + fn)

        mgr.add_pack('default', ['style.css', 'print.css',
                                 'jquery.js', 'application.js'])

    First you have to create a pack manager.  That manager keeps a registry
    of all your packs, because you can have multiple of those.  The first
    argument to it is the path to where the files are stored.  Most of the
    time it makes sure to point to somewhere inside your package.  That path
    is used as base path for the source files and it will also be used as
    a path for the compressed files when created.

    The second argument to the manager is a function that returns the URL
    to the file.  In this case it assumes that the files are available
    as ``/static/filename.css`` and so forth.

    When you add a pack you call `PackManager.add_pack` with the
    name of the pack as first argument and the files it should pack together
    as the second.

    Using Packs
    -----------

    Packs provide a simple interface:

    >>> mgr['default']
    <Pack 'default'>
    >>> print mgr['default']
    <link rel="stylesheet" type="text/css" href="/static/style.css">
    <link rel="stylesheet" type="text/css" href="/static/print.css">
    <script type="text/javascript" src="/static/jquery.js"></script>
    <script type="text/javascript" src="/static/application.js"></script>

    As you can see, the `__str__` and `__unicode__` special methods of a
    pack return the HTML needed to include the files specified.  Please note
    that it will print out the stylesheets before the scripts by default
    and that scripts and files are kept in the order specified but grouped
    by type.  It also outputs HTML4/HTML5 by default and not XHTML.  This
    can be changed.

    Packs can be compressed by calling the `PackManager.compress`
    method on the manager or of a pack:

    >>> mgr.compress()

    That can take a while, after that you can see that the manager spits
    out the compressed includes:

    >>> print mgr['default']
    <link rel="stylesheet" type="text/css" href="/static/default.compressed.css">
    <script type="text/javascript" src="/static/default.compressed.js"></script>

    You can pass packs to your template engine easily.  The best idea is to
    forward the pack as a string or list of strings so that the template
    cannot call `compress` on it.

    Setuputils Integration
    ----------------------

    If you add a webdepcompress_manager setting to your setup call you
    can use the `compress_deps` command from `setup.py`::

        setup(
            ...,
            webdepcompress_manager='yourapplication.packs.mgr'
        )

    Then you can compile the deps from the command line::

        $ python setup.py compress_deps

    And clean the compressed files again::

        $ python setup.py compress_deps --clean


    :copyright: (c) 2009 by Armin Ronacher, see AUTHORS for more details.
    :license: BSD, see LICENSE for more details.