fabric-webbuilders

fabric-webbuilders is a collection of Fabric/Fabric3 tasks to easily build customized up-to-date versions of various HTML/JavaScript/CSS libraries. Currently supported are jQuery and Bootstrap. It also provides tasks to minify CSS and JavaScript.

The fabfile tasks in this package are just a frontend to the "build from source" instructions of the respective packages. This means that any command-line requirements for building the libraries from source have to be satisfied as well.

Quickstart

1. Install fabric-webbuilders:

   pip install fabric-webbuilders
   

2. Add tasks to your fabfile.py:

   from fabric_webbuilders import BuildJqueryTask, BuildBootstrapTask
   
   build_jquery = BuildJqueryTask()
   build_bootstrap = BuildBootstrapTask()

3. Make sure you have npm installed, e.g. on Debian/Ubuntu, do:

   sudo apt-get install npm
   
   # required on most Debian/Ubuntu systems
   sudo ln -s /usr/bin/nodejs /usr/local/bin/node
   

4. If you want to run the minification tasks, install clean-css and uglify-js:

   npm install clean-css uglify-js
   

5. Start building the latest versions of jQuery and Bootstrap:

   fab build_jquery build_bootstrap
   

Configuration

fabric-webbuilders is designed to be very configurable. Every global and task-specific configuration variable can be configured via your env dictionary, either as <library>_<option> or just <option> (the former has precedence), the tasks constructor or via the command-line. For example, this would all configure were libraries get built:

from fabric.state import env

from fabric_webbuilders import BuildJqueryTask

# global build_dir for all libraries:
env['build_dir'] = 'build/'
# just for jquery, takes precedence over above option:
env['jquery_build_dir'] = 'build/jquery/'

# overrides any env variables:
build_jquery = BuildJquery_task(build_dir='build/jquery/')

and then executing:

fab build_jquery:build_dir=build/jquery/  # overrides env and task constructor

The following configuration options are avialable for all tasks:

• build_dir: The build-directory where the libraries are downloaded and build. The default is ./<library>/ or $(VIRTUALENV_DIR)/build/<library>/ inside a virtualenv. Note that env['build_dir'] should not contain a library name, e.g. this would both build jquery in build/jquery/:

  env['build_dir'] = 'build/'
  env['jquery_build_dir'] = 'build/jquery/'

• origin: The default origin to download the source from. For git-based tasks (jQuery and Bootstrap) this is their respective official git repositories. When overriden, it follow the same semantics as the default, e.g. a fork of the original repository.

• version: The version to build. By default the latest version found is build.

  For git-based tasks this can be HEAD (which will build the current HEAD of the master branch), any treeish object (e.g. a tag or branch found in the git-repository) or a string starting with ~, which will build the latest release matching the version, e.g. build_jquery:version=~1 would build the latest jQuery 1.x version.

  Note that env['version'] is ignored because it's populated by fabric.

• dest-dir: Where to copy the built libraries after building.

jQuery

Requires: git, npm, grunt (if excludes are given), bower (jQuery <= 2.1.1)

fabric_webbuilders.BuildJqueryTask clones/updates the official git repository and builds jQuery with npm run build or with grunt custom:<excludes> if excludes are given.

Additional options;

• exclude: Excludes passed to grunt custom to exclude parts of jQuery. Note that without this option there really isn't much difference to just downloading the latest minified version.

Bootstrap

Requires: git, npm, grunt

fabric_webbuilders.BuildBootstrap clones/updates the official git repository and builds Bootstrap with grunt dist.

The Gruntfile unfortunately doesn't allow much automatic customization (or it's at least not documented) so if you pass a config.json with the config parameter, the task dynamically rewrites less/variables.less and less/bootstrap.less and removes any unwanted javascript (as recommended). This works for some common cases I've tested but might break in some cases. Please don't be shy to file an issue.

Additional options:

• config: Use a config.json generated by Bootstrap's customizer. This may be rather fragile, see above.

Minification tasks

Minification tasks try to minimize the size of files (e.g. by removing unnecessary spaces, comments, etc.) and concatenate them to one single file that can be used in production environments.

Minification tasks do not use the env dictionary, so you can configure them only using the tasks constructor or on the command-line. All tasks share three command-line parameters:

• dest: The destination filename.

• files: A list of files to minify. Due to the complexity of the parameter this can only be given as a constructor argument.

  Elements of the list can either be a simple string, in which case the file is used verbatim. If an element is a dictionary, it can contains a src_dir (default: .) and a list of patterns (default: *.<pattern>, e.g. *.css for CSS minification). patterns are applied sequentially using Pythons fnmatch function. Patterns starting with a ! exclude files matching it. Patterns that end with os.sep can be used to skip directories, if the directory starts with os.sep, only top-level directories are skipped. Example:

  from fabric_webbuilders import MinifyCSSTask
  
  minify_css = MinifyCSSTask(dest='minified.css', files=[
    'custom.css',  # custom.css in the current directory
    {  
        'src_dir': 'static/dir1',
        # all *.css files in static/dir1, excluding *.min.css files.
        'patterns': [
            '*.css',  # all files ending with '.css'
            '!*.min.css',  # but exclude .min.css files
            '!subdir/',  # skip any directory called 'subdir'
            '!/subdir?/',  # skip any 'subdirA', 'subdirB' etc. at the root-level
        ],
    },
  ])

• verbose: If a string starting with y, output files that will be minified. Only useable via the command-line.

• options: All other keyword arguments passed via the command-line are passed to the underlying tool. Must be a dictionary if passed via the constructor. By default, options starting with a - are passed with the first - stripped, single-letter options are prepended with a -, other options are prepended with --. If a non-empty string is passed as value, it is appended to the option string. Example:

  from fabric_webbuilders import MinifyCSSTask
  
  minify_css = MinifyCSSTask(files=['output.css'], dest=minified.css, options={
    'd': '',  # Adds "-d" to the command-line
    'verbose': '',  # Adds "--verbose" to the command-line
    'whatever': 'yes',  # Adds "--whatever yes" to the command-line
    '-xyz': 'value',  # Adds "xyz value" to the command-line
    '----xyz': 'value',  # Adds "---xyz value" to the command-line (1st - stripped)
  })

  The same can be given via the command-line:

  fab minify_css:d=,verbose=,whatever=yes,-xyz=value,----xyz=value
  

Minify CSS

Requires: clean-css

fabric_webbuilders.MinifyCSSTask minifies CSS files using clean-css.

Minify JavaScript

Requires: uglify-js

fabric_webbuilders.MinifyJSTask minifys JavaScript files using UglifyJS2.

ChangeLog

0.3 (2016-04-24)

• Tasks for building jQuery and Bootstrap now build with the git repository as the true working directory and that directories node_modules/.bin in the path. As a result, no longer have to locally install npm packages or take care of any PATH issues.
• Minification tasks add node_modules/.bin to the path as well.
• Python3 compatability fixes.
• Do not depend on any particular version of Fabric, so you can use Fabric3.
• Update GitPython dependency, do not list pip-tools in requirements.txt.

0.2 (2014-12-06)

• Fix dest_dir parameter for bootstrap.
• Add tasks to minify JavaScript and CSS.

0.1 (2014-11-30)

• initial release, featuring builders for jQuery and Bootstrap