Usage

How it works

To install the atelier package you must say:

$ pip install atelier

Installing atelier also installs the invoke package, which installs a command inv into your Python environment.

To use atelier for your project, you must have a file named tasks.py in your project’s root directory with at least the following two lines:

from atelier.invlib.ns import ns
ns.setup_from_tasks(globals())
inv

The inv command is a kind of make tool which works by looking for a file named tasks.py.

tasks.py

In your project’s tasks.py file you must define a variable ns which you usually import from atelier.invlib.

You can specify project-specific configuration settings directly in your tasks.py file. Example content:

from atelier.tasks import ns
ns.setup_from_tasks(globals(), "mypackage",
    tolerate_sphinx_warnings=True,
    revision_control_system='git')
.invoke.py

You can specify user-wide invoke settings in a file named .invoke.py which must be in your home directory.

You can also define system-wide default configuration files. See the Invoke documentation for more information.

When you run inv (or its alias invoke) from a project directory or a subdirectory, then invoke finds the tasks.py in the root directory of your project.

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.

See also