Usage

See also

When you run inv (or invoke) from a project directory or a subdirectory, then invoke finds the tasks.py in the root directory of your project. This “activates” atelier.

When you have no config.py file, Atelier will operate in single project mode: the tasks.py causes on the fly creation of a single project descriptor.

The config.py file

~/.atelier/config.py
~/_atelier/config.py
/etc/atelier/config.py

If you have more than one project, then you define the global projects list in a configuration file named ~/.atelier/config.py, which contains something like:

add_project('/home/john/myprojects/p1')
add_project('/home/john/myprojects/second_project', 'p2')

where the first argument to add_project is the name of a directory which is expected to contain a tasks.py.

The optional second argument is a nickname for that project. If no nickname is specified, the nickname will be the leaf name of that directory.

It is allowed but not recommended to have several projects with a same nickname.

Your projects’ setup.py files

If a project has a setup.py file, then atelier uses it.

SETUP_INFO
setup.py

The setup.py file of a Python project can be as simple as this:

from setuptools import setup
setup(name='foo', version='1.0.0')

But for atelier there are two additional required conventions:

  • The setup.py file must define a name SETUP_INFO which is a dict containing all those keyword arguments passed to the setup() function.

  • The setup.py file should actualy call the setup() function only if invoked from a command line, i.e. only if __name__ == ‘__main__’.

So the above minimal setup.py file becomes:

from setuptools import setup
SETUP_INFO = dict(name='foo', version='1.0.0')
if __name__ == '__main__':
    setup(**SETUP_INFO)

Atelier tries to verify these conditions and raises an exception if the setup.py doesn’t comply:

>>> from atelier.projects import get_setup_info
>>> from unipath import Path
>>> get_setup_info(Path('docs/p1'))
Traceback (most recent call last):
...
Exception: Oops, docs/p1/setup.py called sys.exit().
Atelier requires the setup() call to be in a "if __name__ == '__main__':" condition.
>>> get_setup_info(Path('docs/p3'))
Traceback (most recent call last):
...
Exception: Oops, docs/p3/setup.py doesn't define a name SETUP_INFO.
>>> d = get_setup_info(Path('docs/p2'))
>>> d == {'version': '1.0.0', 'name': 'foo'}
True
>>> d == dict(name="foo", version="1.0.0")
True

Defining shell aliases

Under Linux you can easily define abbreviations for certain commands which you use oftem. These are called shell aliases. There are several ways for defining them, we recommend to write them into your ~/.bash_aliases.

~/.bash_aliases

Conventional name for the file that holds your shell aliases. See Configuring your login sessions with dot files.

After editing your ~/.bash_aliases you must open a new terminal in order to see the changes.

The per_project command

Installing the atelier package will add the per_project script:

per_project

Usage : per_project [options] CMD …

Loop over all projects, executing the given shell command CMD in the root directory of each project.

Special case: When CMD starts with the word git, then skip all projects which don’t have their revision_control_system set to 'git'.

The projects are processed in the order defined in your ~/.atelier/config.py file.

Options:

  • --list or -l : print a list of all projects to stdout. Does not run any command.

  • --start PRJNAME : start at project PRJNAME. This is useful e.g. when you have been running the test suite on all your projects and one project failed. After repairing that failure you want to continue the started loop without repeating previous test suites again.

  • --after PRJNAME : start after project PRJNAME (like –start, but without the named project).

  • --until PRJNAME : stop after project PRJNAME.

  • --voice : Speak the result through speakers when terminated.

pp

We recommend to define an alias pp for per_project in your ~/.bash_aliases:

alias pp='per_project'

Note that the first argument which is not an option (i.e. not starting with a -) marks the beginning of the shell command to be executed. Any - after that is considered a part of the command. So the following two lines are not equivalent:

$ pp inv --help
$ pp --help inv

Usage examples:

$ pp -l
$ pp inv test
$ pp git st

See the Project management page of the Lino project for more usage examples.