djblets.extensions.packaging¶

Packaging support for extensions.

class BuildStaticFiles(dist, **kw)¶

Bases: Command

Builds static files for the extension.

This will build the static media files used by the extension. JavaScript bundles will be minified and versioned. CSS bundles will be processed through lesscss (if using .less files), minified and versioned.

This must be subclassed by the project offering the extension support. The subclass must provide the extension_entrypoint_group and django_settings_module parameters.

extension_entrypoint_group is the group name that entry points register into.

django_settings_module is the Python module path for the project’s settings module, for use in the DJANGO_SETTINGS_MODULE environment variable.

description = 'Build static media files'¶

extension_entrypoint_group = None¶

django_settings_module = None¶

user_options = [('remove-source-files', None, 'remove source files from the package')]¶

boolean_options = ['remove-source-files']¶

initialize_options()¶

Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, ‘initialize_options()’ implementations are just a bunch of “self.foo = None” assignments.

This method must be implemented by all command classes.

finalize_options()¶

Set final values for all the options that this command supports. This is always called as late as possible, ie. after any option assignments from the command-line or from other commands have been done. Thus, this is the place to code option dependencies: if ‘foo’ depends on ‘bar’, then it is safe to set ‘foo’ from ‘bar’ as long as ‘foo’ still has the same value it was assigned in ‘initialize_options()’.

This method must be implemented by all command classes.

get_lessc_global_vars()¶

Returns a dictionary of LessCSS global variables and their values.

This can be implemented by subclasses to provide global variables for .less files for processing.

By default, this defines two variables: STATIC_ROOT and DEBUG.

STATIC_ROOT is set to /static/. Any imports using @{STATIC_ROOT} will effectively look up the requested file in <import_path>/@{STATIC_ROOT}. This assumes that the project serving the static files keeps them in static/appname/.

Projects using less.js for the runtime can then define STATIC_ROOT to settings.STATIC_URL, ensuring lookups work for development and packaged extensions.

DEBUG is set to false. Runtimes using less.js can set this to settings.DEBUG for templates. This can be useful for LessCSS guards.

This requires LessCSS 1.5.1 or higher.

get_lessc_include_path()¶

Returns the include path for LessCSS imports.

By default, this will include the parent directory of every path in STATICFILES_DIRS, plus the static directory of the extension.

install_pipeline_deps(extension, css_bundles, js_bundles)¶

Install dependencies needed for the static media pipelining.

This will install the LessCSS and UglifyJS tools, if needed for the packaging process. These will only be installed if they’d be used, which is determined based on the contents of the bundles.

Subclasses can override this to support additional tools.

Parameters:

• extension (djblets.extensions.extension.Extension) – The extension being packaged.

• css_bundles (dict) – A dictionary of CSS bundles being built for the package.

• js_bundles (dict) – A dictionary of JavaScript bundles being built for the package.

get_bundle_file_matches(bundles, pattern)¶

Return whether there’s any files in a bundle matching a pattern.

Parameters:

• bundles (dict) – A dictionary of bundles.

• pattern (unicode) – The filename pattern to match against.

Returns:

True if a filename in one or more bundles matches the pattern. False if no filenames match.

Return type:

bool

npm_install(package_spec=None)¶

Install a package via npm.

This will first determine if npm is available, and then attempt to install the given package.

Parameters:

package_spec (unicode, optional) – The package specification (name and optional version range) to install. If not specified, this will use the default behavior of reading package.json.

Raises:

distutils.errors.DistutilsExecError – npm could not be found, or there was an error installing the package.

run()¶

A command’s raison d’etre: carry out the action it exists to perform, controlled by the options initialized in ‘initialize_options()’, customized by other commands, the setup script, the command-line, and config files, and finalized in ‘finalize_options()’. All terminal output and filesystem interaction should be done by ‘run()’.

This method must be implemented by all command classes.

class BuildPy(dist, **kw)¶

Bases: build_py

run()¶

Build modules, packages, and copy data files to build directory

build_extension_cmdclass(build_static_files_cls)¶

Builds a cmdclass to pass to setup.

This is passed a subclass of BuildStaticFiles, and returns something that can be passed to setup().