calmjs.bower 1.0.2

Alternative installation methods (advanced users)

Development is still ongoing with calmjs.bower, for the latest features and bug fixes, the development version can be installed through git like so:

$ pip install calmjs
$ pip install git+https://github.com/calmjs/calmjs.bower.git#egg=calmjs.bower

Alternatively, the git repository can be cloned directly and execute python setup.py develop while inside the root of the source directory.

Keep in mind that calmjs MUST be available before the setup.py within the calmjs.bower source tree is executed, for it needs the package_json writing capabilities in calmjs. Please refer to the base package for further information.

As calmjs is declared as both a namespace and a package, mixing installation methods as described above when installing with other calmjs packages may result in the module importer being unable to look up the target module. While this normally will not affect end users, provided they use the same, standard installation method (i.e. wheel), for developers it can be troublesome. To resolve this, either stick to the same installation method for all packages (i.e. python setup.py develop), or import a module from the main calmjs package. Here is an example run:

>>> import calmjs.bower
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: No module named 'calmjs.bower'
>>> import calmjs.base
>>> import calmjs.bower
>>>

If this behavior (and workaround) is undesirable, please ensure the installation of all calmjs related packages follow the same method (i.e. either python setup.py develop for all packages, or using the wheels acquired through pip).

Testing the installation

To ensure that the calmjs installation is functioning correctly, the built-in testsuite can be executed by the following command:

$ python -m unittest calmjs.bower.tests.make_suite

If there are failures, please file an issue on the issue tracker with the full traceback, and/or the method of installation. Please also remember to include platform specific information, such as Python version, operating system environments and version, and other related information related to the issue at hand.

Declare a bower.json for a given Python package

If a package wish to declare dependencies on packages available through bower, it may do something like this in its setup.py:

from setuptools import setup

bower_json = {
    "dependencies": {
        "jquery": "~3.0.0",
        "underscore": "~1.8.0",
    }
}

setup(
    name='example.package',
    ...
    install_requires=[
        'calmjs.bower',
        ...
    ],
    bower_json=bower_json,
    ...
)

This will let users of this package install all the dependencies through the appropriate package managers as outlined above in the installation section.

Declare explicit dependencies on paths inside bower_components

Given that the dependencies on specific versions of packages sourced from bower is explicitly specified, build tools will benefit again from explicit declarations on files needed from those packages. Namely, the compiled packages could be declared in the extras_calmjs section in JSON string much like bower_json, like so:

extras_calmjs = {
    'bower_components': {
        'jquery': 'jquery/dist/jquery.js',
        'underscore': 'underscore/underscore.js',
    },
}

setup(
    name='example.package',
    ...
    extras_calmjs=extras_calmjs,
    ...
)

Since bower_components is declared to be an extras_key, conflicts with existing declarations in other packages within the environment will be merged like how dependencies sections declared in bower_json.

Please do note that complete paths must be declared (note that the .js filename suffix is included in the example); directories can also be declared. However, as these declarations are done from within Python, explicit, full paths are required thus it is up to downstream integration packages to properly handle and/or convert this into the conventions that standard Node.js tools might expect (i.e. where the .js filename suffix is omitted).

As of now, the support of .bowerrc configuration settings is not currently implemented, so behavior of usage of bower through calmjs will not account for locations that may be specified in that file. For the standard use case where dependencies are installed to some separate directory as part of a typical calmjs workflow it should not pose a problem.

RuntimeWarning: Unable to locate the ‘bower’ binary;

If this message appears, this simply means the default module setup (i.e. from calmjs import bower) could not find a usable bower binary/runtime when it was imported. As the default runtime does various setup it only means that the helper methods may not be usable out of the box. This can always be rectified by having bower already installed in the current directory (through npm) or have it be available through the PATH environment variable. Full details on what can be done is written in the error message.