rituals package

Common tasks for ‘Invoke’ that are needed again and again.

The rituals package provides PyInvoke tasks that work for any project, based on its project metadata, to automate common developer chores like ‘clean’, ‘build’, ‘dist’, ‘test’, ‘check’, and ‘release-prep’ (for the moment).

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 tasks.py). Invoke tasks can use Setuptools ones as building blocks, but never the other way ‘round – this avoids bootstrapping head- aches during package installations using pip.

The easiest way to get a working project based on rituals is the py-generic-project cookiecutter template. That way you have a working project skeleton within minutes that is fully equipped, with all aspects of bootstrapping, building, testing, quality checks, continuous integration, documentation, and releasing covered. See here for more:

https://github.com/Springerle/py-generic-project

Copyright ⓒ 2015 - 2019 Jürgen Hermann

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

The full LICENSE file and source are available at

https://github.com/jhermann/rituals

Subpackages

• rituals.acts package
  • Submodules
  • rituals.acts.basic module
  • rituals.acts.devpi module
  • rituals.acts.documentation module
  • rituals.acts.github module
  • rituals.acts.inspection module
  • rituals.acts.jenkins module
  • rituals.acts.pkgdeb module
  • rituals.acts.releasing module
  • rituals.acts.testing module
• rituals.util package
  • Subpackages
    • rituals.util.scm package
      • Submodules
      • rituals.util.scm.base module
      • rituals.util.scm.git module
      • rituals.util.scm.null module
  • Submodules
  • rituals.util.antglob module
  • rituals.util.filesys module
  • rituals.util.notify module
  • rituals.util.shell module
  • rituals.util.which module

Submodules

rituals.config module

Project configuration and layout.

rituals.config.get_project_root()

Determine location of tasks.py.

rituals.config.load()

Load and return configuration as a Bunch.

Values are based on DEFAULTS, and metadata from setup.py.

rituals.config.set_flat_layout()

Switch default project layout to everything top-level.

rituals.config.set_maven_layout()

Switch default project layout to Maven-like.

rituals.easy module

Default namespace for convenient wildcard import in task definition modules.

class rituals.easy.Collection(*args, **kwargs)

Bases: object

A collection of executable tasks. See /concepts/namespaces.

New in version 1.0.

add_collection(coll, name=None)

Add .Collection coll as a sub-collection of this one.

Parameters:

• coll – The .Collection to add.
• name (str) – The name to attach the collection as. Defaults to the collection’s own internal name.

New in version 1.0.

add_task(task, name=None, aliases=None, default=None)

Add .Task task to this collection.

Parameters:

• task – The .Task object to add to this collection.
• name – Optional string name to bind to (overrides the task’s own self-defined name attribute and/or any Python identifier (i.e. .func_name.)
• aliases – Optional iterable of additional names to bind the task as, on top of the primary name. These will be used in addition to any aliases the task itself declares internally.
• default – Whether this task should be the collection default.

New in version 1.0.

configuration(taskpath=None)

Obtain merged configuration values from collection & children.

Parameters:taskpath – (Optional) Task name/path, identical to that used for ~.Collection.__getitem__ (e.g. may be dotted for nested tasks, etc.) Used to decide which path to follow in the collection tree when merging config values. Returns:A dict containing configuration values.

New in version 1.0.

configure(options)

(Recursively) merge options into the current .configuration.

Options configured this way will be available to all tasks. It is recommended to use unique keys to avoid potential clashes with other config options

For example, if you were configuring a Sphinx docs build target directory, it’s better to use a key like 'sphinx.target' than simply 'target'.

Parameters:options – An object implementing the dictionary protocol. Returns:None.

New in version 1.0.

classmethod from_module(module, name=None, config=None, loaded_from=None, auto_dash_names=None)

Return a new .Collection created from module.

Inspects module for any .Task instances and adds them to a new .Collection, returning it. If any explicit namespace collections exist (named ns or namespace) a copy of that collection object is preferentially loaded instead.

When the implicit/default collection is generated, it will be named after the module’s __name__ attribute, or its last dotted section if it’s a submodule. (I.e. it should usually map to the actual .py filename.)

Explicitly given collections will only be given that module-derived name if they don’t already have a valid .name attribute.

If the module has a docstring (__doc__) it is copied onto the resulting .Collection (and used for display in help, list etc output.)

Parameters:

• name (str) – A string, which if given will override any automatically derived collection name (or name set on the module’s root namespace, if it has one.)
• config (dict) –

  Used to set config options on the newly created .Collection before returning it (saving you a call to .configure.)

  If the imported module had a root namespace object, config is merged on top of it (i.e. overriding any conflicts.)

• loaded_from (str) – Identical to the same-named kwarg from the regular class constructor - should be the path where the module was found.
• auto_dash_names (bool) – Identical to the same-named kwarg from the regular class constructor - determines whether emitted names are auto-dashed.

New in version 1.0.

serialized()

Return an appropriate-for-serialization version of this object.

See the documentation for .Program and its json task listing format; this method is the driver for that functionality.

New in version 1.0.

subcollection_from_path(path)

Given a path to a subcollection, return that subcollection.

New in version 1.0.

subtask_name(collection_name, task_name)

task_names

Return all task identifiers for this collection as a one-level dict.

Specifically, a dict with the primary/”real” task names as the key, and any aliases as a list value.

It basically collapses the namespace tree into a single easily-scannable collection of invocation strings, and is thus suitable for things like flat-style task listings or transformation into parser contexts.

New in version 1.0.

task_with_config(name)

Return task named name plus its configuration dict.

E.g. in a deeply nested tree, this method returns the .Task, and a configuration dict created by merging that of this .Collection and any nested Collections <.Collection>, up through the one actually holding the .Task.

See ~.Collection.__getitem__ for semantics of the name argument.

Returns:Two-tuple of (.Task, dict).

New in version 1.0.

to_contexts()

Returns all contained tasks and subtasks as a list of parser contexts.

New in version 1.0.

transform(name)

Transform name with the configured auto-dashes behavior.

If the collection’s auto_dash_names attribute is True (default), all non leading/trailing underscores are turned into dashes. (Leading/trailing underscores tend to get stripped elsewhere in the stack.)

If it is False, the inverse is applied - all dashes are turned into underscores.

New in version 1.0.

rituals.easy.task(*args, **kwargs)

Marks wrapped callable object as a valid Invoke task.

May be called without any parentheses if no extra options need to be specified. Otherwise, the following keyword arguments are allowed in the parenthese’d form:

• name: Default name to use when binding to a .Collection. Useful for avoiding Python namespace issues (i.e. when the desired CLI level name can’t or shouldn’t be used as the Python level name.)
• aliases: Specify one or more aliases for this task, allowing it to be invoked as multiple different names. For example, a task named mytask with a simple @task wrapper may only be invoked as "mytask". Changing the decorator to be @task(aliases=['myothertask']) allows invocation as "mytask" or "myothertask".
• positional: Iterable overriding the parser’s automatic “args with no default value are considered positional” behavior. If a list of arg names, no args besides those named in this iterable will be considered positional. (This means that an empty list will force all arguments to be given as explicit flags.)
• optional: Iterable of argument names, declaring those args to have optional values. Such arguments may be given as value-taking options (e.g. --my-arg=myvalue, wherein the task is given "myvalue") or as Boolean flags (--my-arg, resulting in True).
• iterable: Iterable of argument names, declaring them to build iterable values.
• incrementable: Iterable of argument names, declaring them to increment their values.
• default: Boolean option specifying whether this task should be its collection’s default task (i.e. called if the collection’s own name is given.)
• auto_shortflags: Whether or not to automatically create short flags from task options; defaults to True.
• help: Dict mapping argument names to their help strings. Will be displayed in --help output.
• pre, post: Lists of task objects to execute prior to, or after, the wrapped task whenever it is executed.
• autoprint: Boolean determining whether to automatically print this task’s return value to standard output when invoked directly via the CLI. Defaults to False.
• klass: Class to instantiate/return. Defaults to .Task.

If any non-keyword arguments are given, they are taken as the value of the pre kwarg for convenience’s sake. (It is an error to give both *args and pre at the same time.)

New in version 1.0.

Changed in version 1.1: Added the klass keyword argument.

rituals.easy.pushd(*args, **kwds)

A context that enters a given directory and restores the old state on exit.

The original directory is returned as the context variable.

rituals.easy.fail(message, exitcode=1)

Exit with error code and message.