program

class invoke.program.Program(version=None, namespace=None, name=None, binary=None, loader_class=None, executor_class=None, config_class=None)

Manages top-level CLI invocation, typically via setup.py entrypoints.

Designed for distributing Invoke task collections as standalone programs, but also used internally to implement the invoke program itself.

See also

Reusing Invoke’s CLI module as a distinct binary for a tutorial/walkthrough of this functionality.

New in version 1.0.

__init__(version=None, namespace=None, name=None, binary=None, loader_class=None, executor_class=None, config_class=None)

Create a new, parameterized Program instance.

Parameters:
  • version (str) – The program’s version, e.g. "0.1.0". Defaults to "unknown".
  • namespace –

    A Collection to use as this program’s subcommands.

    If None (the default), the program will behave like invoke, seeking a nearby task namespace with a Loader and exposing arguments such as --list and --collection for inspecting or selecting specific namespaces.

    If given a Collection object, will use it as if it had been handed to --collection. Will also update the parser to remove references to tasks and task-related options, and display the subcommands in --help output. The result will be a program that has a static set of subcommands.

  • name (str) –

    The program’s name, as displayed in --version output.

    If None (default), is a capitalized version of the first word in the argv handed to run. For example, when invoked from a binstub installed as foobar, it will default to Foobar.

  • binary (str) –

    The binary name as displayed in --help output.

    If None (default), uses the first word in argv verbatim (as with name above, except not capitalized).

    Giving this explicitly may be useful when you install your program under multiple names, such as Invoke itself does - it installs as both inv and invoke, and sets binary="inv[oke]" so its --help output implies both names.

  • loader_class –

    The Loader subclass to use when loading task collections.

    Defaults to FilesystemLoader.

  • executor_class –

    The Executor subclass to use when executing tasks.

    Defaults to Executor.

  • config_class –

    The Config subclass to use for the base config object.

    Defaults to Config.
__weakref__

list of weak references to the object (if defined)

args

Obtain core program args from self.core parse result.

New in version 1.0.

binary

Derive program’s help-oriented binary name(s) from init args & argv.

New in version 1.0.

core_args()

Return default core Argument objects, as a list.

New in version 1.0.

create_config()

Instantiate a Config (or subclass, depending) for use in task exec.

This Config is fully usable but will lack runtime-derived data like project & runtime config files, CLI arg overrides, etc. That data is added later in update_config. See Config docstring for lifecycle details.

Returns:None; sets self.config instead.

New in version 1.0.

execute()

Hand off data & tasks-to-execute specification to an Executor.

Note

Client code just wanting a different Executor subclass can just set executor_class in __init__.

New in version 1.0.

initial_context

The initial parser context, aka core program flags.

The specific arguments contained therein will differ depending on whether a bundled namespace was specified in __init__.

New in version 1.0.

load_collection()

Load a task collection based on parsed core args, or die trying.

New in version 1.0.

name

Derive program’s human-readable name based on binary.

New in version 1.0.

normalize_argv(argv)

Massages argv into a useful list of strings.

If None (the default), uses sys.argv.

If a non-string iterable, uses that in place of sys.argv.

If a string, performs a str.split and then executes with the result. (This is mostly a convenience; when in doubt, use a list.)

Sets self.argv to the result.

New in version 1.0.

parse_cleanup()

Post-parsing, pre-execution steps such as –help, –list, etc.

New in version 1.0.

parse_collection()

Load a tasks collection & project-level config.

New in version 1.0.

parse_core_args()

Filter out core args, leaving any tasks or their args for later.

Sets self.core to the ParseResult from this step.

New in version 1.0.

parse_tasks()

Parse leftover args, which are typically tasks & per-task args.

Sets self.parser to the parser used, self.tasks to the parsed per-task contexts, and self.core_via_tasks to a context holding any core flags seen within the task contexts.

New in version 1.0.

print_columns(tuples)

Print tabbed columns from (name, help) tuples.

Useful for listing tasks + docstrings, flags + help strings, etc.

New in version 1.0.

print_task_help(name)

Print help for a specific task, e.g. inv --help <taskname>.

New in version 1.0.

run(argv=None, exit=True)

Execute main CLI logic, based on argv.

Parameters:
  • argv – The arguments to execute against. May be None, a list of strings, or a string. See normalize_argv for details.
  • exit (bool) –

    When False (default: True), will ignore ParseError, Exit and Failure exceptions, which otherwise trigger calls to sys.exit.

    Note

    This is mostly a concession to testing. If you’re setting this to False in a production setting, you should probably be using Executor and friends directly instead!

New in version 1.0.

task_args()

Return default task-related Argument objects, as a list.

These are only added to the core args in “task runner” mode (the default for invoke itself) - they are omitted when the constructor is given a non-empty namespace argument (“bundled namespace” mode).

New in version 1.0.

update_config(merge=True)

Update the previously instantiated Config with parsed data.

For example, this is how --echo is able to override the default config value for run.echo.

Parameters:merge (bool) – Whether to merge at the end, or defer. Primarily useful for subclassers. Default: True.

New in version 1.0.