invoke.program.Program

Create a new, parameterized `.Program` instance. :param str version: The program's version, e.g. ``"0.1.0"``. Defaults to ``"unknown"``. :param 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 :option:`--list` and :option:`--collection` for inspecting or selecting specific namespaces. If given a `.Collection` object, will use it as if it had been handed to :option:`--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. :param str name: 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``. :param str binary: 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). :param binary_names: List of binary name strings, for use in completion scripts. This list ensures that the shell completion scripts generated by :option:`--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 :option:`--print-completion-script`) is used in a single-item list. :param loader_class: The `.Loader` subclass to use when loading task collections. Defaults to `.FilesystemLoader`. :param executor_class: The `.Executor` subclass to use when executing tasks. Defaults to `.Executor`; may also be overridden at runtime by the :ref:`configuration system <default-values>` and its ``tasks.executor_class`` setting (anytime that setting is not ``None``). :param config_class: The `.Config` subclass to use for the base config object. Defaults to `.Config`. .. versionchanged:: 1.2 Added the ``binary_names`` argument.

Return default core `.Argument` objects, as a list. .. versionadded:: 1.0

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. .. versionadded:: 1.0

Undocumented

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 :ref:`config system <default-values>` (which may allow you to avoid using a custom Program entirely). .. versionadded:: 1.0

Undocumented

Undocumented

Undocumented

Undocumented

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

Undocumented

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. .. versionadded:: 1.0

Post-parsing, pre-execution steps such as --help, --list, etc. .. versionadded:: 1.0

Load a tasks collection & project-level config. .. versionadded:: 1.0

Undocumented

Filter out core args, leaving any tasks or their args for later. Sets ``self.core`` to the `.ParseResult` from this step. .. versionadded:: 1.0

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). .. versionadded:: 1.0

Print tabbed columns from (name, help) ``tuples``. Useful for listing tasks + docstrings, flags + help strings, etc. .. versionadded:: 1.0

Undocumented

Print help for a specific task, e.g. ``inv --help <taskname>``. .. versionadded:: 1.0

Undocumented

Execute main CLI logic, based on ``argv``. :param argv: The arguments to execute against. May be ``None``, a list of strings, or a string. See `.normalize_argv` for details. :param bool exit: 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! .. versionadded:: 1.0

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). .. versionadded:: 1.0

Undocumented

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``. :param bool merge: Whether to merge at the end, or defer. Primarily useful for subclassers. Default: ``True``. .. versionadded:: 1.0