View on GitHub

Rituals

Project automation tasks for ‘Invoke’ that are needed again and again.

Download this project as a .zip file Download this project as a tar.gz file

GINOSAJI … and again and again.

GroupsTravis CICoverallsGitHub IssuesLicenseDevelopment StatusLatest VersionDownload formatDownloads

Overview

“Rituals” is a task library for Invoke that keeps the most common tasks you always need out of your project, and makes them centrally maintained. This leaves your tasks.py small and to the point, with only things specific to the project at hand. The following lists the common task implementations that the rituals.easy module offers. See the next section on how to integrate them into your tasks.py.

The guiding principle for these tasks is to strictly separate low-level tasks for building and installing (via setup.py) from high-level convenience tasks a developer uses (via invoke). Invoke tasks can use Setuptools ones as building blocks, but never the other way 'round – this avoids any bootstrapping headaches during package installations.

Use inv -h ‹task› as usual to get details on the options of these tasks. Look at the modules in acts if you want to know what these tasks do exactly.

:bulb: The easiest way to get a working project using rituals is the py-generic-project cookiecutter archetype. That way you have a working project skeleton within minutes that is fully equipped, with all aspects of building, testing, quality checks, continuous integration, documentation, and releasing covered.

Some Practical Examples

In projects that include Rituals in their tasks.py (e.g. this one), the following commands can be used.

Command Description
inv test.tox --clean -e py34 Run tox for Python 3.4 with a clean status, i.e. an empty .tox directory.
inv bump Set the tag_build value in setup.cfg to something like 0.3.0.dev117+0.2.0.g993edd3.20150408t1747, uniquely identifying dev builds, even in dirty working directories.

Usage

Add common tasks to your project's task.py

Add rituals to your dev-requirements.txt or a similar file, or add it to setup_requires in your setup.py. Then at the start of your tasks.py, use the following statement to define all tasks that are considered standard:

from rituals.easy import *

Note that this defines Invoke's Collection and task identifiers, the root namespacewith Ritual's default tasks, and some common helpers (see the documentation for details). Of course, you can also do more selective imports, or build your own Invoke namespaces with the specific tasks you need.

:warning: These tasks expect an importable setup.py that defines a project dict with the setup parameters, see javaprops and py-generic-project for examples.

To refer to the current GitHub master branch, use a pip requirement like this:

-e git+https://github.com/jhermann/rituals.git#egg=rituals

Change default project layout

By default, sources are expected in src/‹packagename› and tests in src/tests.

You can change this by calling one of the following functions, directly after the import from rituals.invoke_tasks.

Change default project configuration

TODO

Contributing

To create a working directory for this project, call these commands:

git clone "https://github.com/jhermann/rituals.git"
cd rituals
. .env --yes --develop
invoke build --docs

To use the source in this working directory within another project, change your current directory to this project, then call bin/pip from that project's virtualenv like so:

…/.venv/…/bin/pip install -e .

See CONTRIBUTING for more.

Throughput Graph

Releasing

This is the process of releasing rituals itself, projects that use it will have an identical to very similar sequence of commands.

inv release.prep
inv dist --devpi # local release + tox testing

git push && git push --tags # … and wait for Travis CI to do its thing

twine upload -r pypi dist/*

If you have any pending changes, staged or unstaged, you'll get an error like this:

uncommitted changes

Related Projects

Acknowledgements