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.

参见

将 Invoke 的 CLI 模块重用作独立的二进制文件 for a tutorial/walkthrough of this functionality.

在 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.

参数:

  • 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.

在 1.2 版本发生变更: Added the binary_names argument.

__weakref__

list of weak references to the object

property args: Lexicon

Obtain core program args from self.core parse result.

在 1.0 版本加入.

property binary: str

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

在 1.0 版本加入.

property binary_names: List[str]

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

在 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.

在 1.2 版本加入.

core_args() → List[Argument]

Return default core Argument objects, as a list.

在 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.

返回:

None; sets self.config instead.

在 1.0 版本加入.

execute() → None

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

备注

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).

在 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__.

在 1.0 版本加入.

load_collection() → None

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

在 1.0 版本加入.

property name: str

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

在 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.

在 1.0 版本加入.

parse_cleanup() → None

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

在 1.0 版本加入.

parse_collection() → None

Load a tasks collection & project-level config.

在 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.

在 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).

在 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.

在 1.0 版本加入.

print_task_help(name: str) → None

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

在 1.0 版本加入.

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

Execute main CLI logic, based on argv.

参数:

  • 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.

    备注

    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!

在 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).

在 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.

参数:

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

在 1.0 版本加入.