program

class invoke.program.Program(version: Optional[str] = None, namespace: Optional[Collection] = None, name: Optional[str] = None, binary: Optional[str] = None, loader_class: Optional[Type[Loader]] = None, executor_class: Optional[Type[Executor]] = None, config_class: Optional[Type[Config]] = None, binary_names: Optional[List[str]] = 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: Optional[str] = None, namespace: Optional[Collection] = None, name: Optional[str] = None, binary: Optional[str] = None, loader_class: Optional[Type[Loader]] = None, executor_class: Optional[Type[Executor]] = None, config_class: Optional[Type[Config]] = None, binary_names: Optional[List[str]] = None) → 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) –

    Descriptive lowercase binary name string used in help text.

    For example, Invoke’s own internal value for this is inv[oke], denoting that it is installed as both inv and invoke. As this is purely text intended for help display, it may be in any format you wish, though it should match whatever you’ve put into your setup.py’s console_scripts entry.

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

  • binary_names –

    List of binary name strings, for use in completion scripts.

    This list ensures that the shell completion scripts generated by --print-completion-script instruct the shell to use that completion for all of this program’s installed names.

    For example, Invoke’s internal default for this is ["inv", "invoke"].

    If None (the default), the first word in argv (in the invocation of --print-completion-script) is used in a single-item list.

  • 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; may also be overridden at runtime by the configuration system and its tasks.executor_class setting (anytime that setting is not None).

  • config_class –

    The Config subclass to use for the base config object.

    Defaults to Config.

Changed in version 1.2: Added the binary_names argument.

__weakref__

list of weak references to the object (if defined)

property args: Lexicon

Obtain core program args from self.core parse result.

New in version 1.0.

property binary: str

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

New in version 1.0.

property binary_names: List[str]

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

New in version 1.2.

property called_as: str

Returns the program name we were actually called as.

Specifically, this is the (Python’s os module’s concept of a) basename of the first argument in the parsed argument vector.

New in version 1.2.

core_args() → List[invoke.parser.argument.Argument]

Return default core Argument objects, as a list.

New in version 1.0.

create_config() → None

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() → None

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__, or override tasks.executor_class anywhere in the config system (which may allow you to avoid using a custom Program entirely).

New in version 1.0.

property initial_context: invoke.parser.context.ParserContext

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() → None

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

New in version 1.0.

property name: str

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

New in version 1.0.

normalize_argv(argv: Optional[List[str]]) → None

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() → None

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

New in version 1.0.

parse_collection() → None

Load a tasks collection & project-level config.

New in version 1.0.

parse_core_args() → None

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() → None

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.

Also modifies self.core to include the data from core_via_tasks (so that it correctly reflects any supplied core flags regardless of where they appeared).

New in version 1.0.

print_columns(tuples: Sequence[Tuple[str, Optional[str]]]) → None

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: str) → None

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

New in version 1.0.

run(argv: Optional[List[str]] = None, exit: bool = True) → None

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() → List[invoke.parser.argument.Argument]

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: bool = True) → None

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.