`program`¶

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