Toolkit API reference¶

This maintained reference summarizes the Toolkit-specific public surface. It is not a generated copy of every inherited method. For ordinary task options, collections, contexts, runners, Results and exceptions, use Invoke's API reference. Feature guides supply complete runnable examples and current constraints.

Import map¶

Root exports also include Field, FieldResolutionRequest, FieldResolver, CacheConfig, cached, cache_stats, clear_task_cache, all six path factories, script, global_context, run and sudo. ConfigSchema/config_schema and schema registry helpers are imported from invoke_toolkit.config, not the root. Inherited Invoke classes/exceptions re-exported at the root retain upstream semantics.

Tasks and calls¶

task¶

Supports both @task and @task(...). Current keyword parameters and defaults:

Toolkit adds Enum/Literal validation, Path conversion, Annotated help/completion, Fields, result caching, process titles and coroutine-aware wrappers. Explicit help entries win over annotation help. Self-referential aliases warn and are dropped. Runtime objects are Task instances despite preserved callable typing; do not infer a plain function result from the type-preserving decorator annotation.

autoprint=True displays return values only for directly requested executor calls, not automatically every pre/post call. Strings and Paths use normal printing; other objects use the Toolkit Rich stdout console. It is not a universal JSON result format.

See typed arguments, Fields, caching, async and execution. Origins: #38, #41, #36, #50, #51, #121, #128, #116.

call and ToolkitCall¶

call(task_, *args, **kwargs) -> ToolkitCall supplies arguments for a dependency using Invoke's Call model. ToolkitCall.make_context(config, core_parse_result=None) -> Context preserves upstream parser remainder text. ctx.remainder is inherited Invoke behavior, not sanitized argv. Origin: #114.

Collections¶

Collection(*args, **kwargs) inherits Invoke's constructor for a name, tasks and subcollections. Standard add_task, add_collection, namespace lookup, aliases/defaults and configuration(taskpath=None) remain Invoke APIs.

load_plugins() currently has no implementation; use namespace discovery or installed collection entry points. Namespace helpers import code and can encounter name collisions. Collection names do not automatically wrap schema/config fields at the root. See composition and local precedence, schemas and plugin discovery.

Origins: #8, #21, #31, #90, #123, #133.

Context¶

Context(config: Config | None = None, remainder: str = "") extends Invoke Context.

status, status_update, print and print_err are exposed as properties returning callables. Output is not inherently machine-readable; use json.dumps for an explicit task contract. Redaction is not secret isolation and has shared-state/exception restoration limitations. run_async does not provide PTY, stdin, watchers, sudo, streaming or synchronous-runner redaction parity. See Rich output, async restrictions and execution safety.

AsyncGatherScope lives in invoke_toolkit.context.async_tools. Submit awaitables with scope(awaitable) inside async with scope; .results is a tuple after successful exit. Work starts on submission; unfinished work is cancelled on failure. Origin: #121, repairs #127.

Configuration and schemas¶

Config retains Invoke Config constructor/loading methods. Subclass definition accepts prefix=None, file_prefix=None, env_prefix=None, extra_defaults=None. global_defaults() adds Toolkit's synchronous runner, status/completion and fuzzy-finder settings.

Use ConfigSchema inheritance for APIs requiring that subclass; @config_schema alone adds helpers but does not change inheritance. Registry keys and configuration placement are separate decisions. Built-in file editing tasks are in the CLI reference, with configuration validation/format limits. Origins: #11, #52, #90, #93, #94.

Path annotations¶

Import all factories from invoke_toolkit; they return Annotated types. Their supported signatures are:

• FilePath(*, exists=False, file_okay=True, dir_okay=True) and FilePathStr with the same parameters.
• FilePattern(pattern: str, *, exists=False) and FilePatternStr with the same parameters.
• DirPath(*, exists=False) and DirPathStr with the same parameters.

The non-Str forms receive Path, the Str forms receive strings. Glob/type filters guide completion; exists=True enables runtime existence/type checks. Plain Path converts explicit strings but does not imply all completion/validation constraints. See typed paths. Origin: #41.

Fields¶

Field(default=UNSET, default_factory=UNSET, resolver=None, cleanup="pipeline") is the runtime marker; UNSET here describes omitted arguments, not a value you need to import. Field() is required, unlike Field(default=None).

• field.required reports whether it lacks a default/factory.
• A required template can be bound as field(default=...) or field(default_factory=..., cleanup=None). It preserves the resolver and inherits cleanup unless overridden.
• field.create_temporary_file(request, value: str) -> Path is the materialization hook for resolver text with a Path annotation.
• FieldResolutionRequest(parameter: str, reference: str, annotation) is a frozen request record.
• FieldResolver is a callable protocol: (ctx, requests: Sequence[FieldResolutionRequest]) -> Mapping[str, str].

Local batches use scheme plus callable identity. Results must contain exactly the requested names, with string values. Exact Path-base fields turn that text into managed files; explicit caller paths remain caller-owned. Bool/incrementable/iterable parameters do not support Field defaults. See precedence and lifetime.

Installed compatibility providers use invoke_toolkit.field_resolver; providers are not task collections. reset_field_resolver_cache() in invoke_toolkit.field_resolvers clears cached entry-point discovery/warning state for controlled process/test lifecycle use. It does not clean files or resolve values. Origin: #128.

Caching¶

• CacheConfig(enabled=True, ttl=None, key_prefix="", ignore_args=[]): task-result cache options.
• clear_task_cache(task_name: str | None = None) -> int: clear all/current-prefix task keys; hashed-key limitations apply.
• cache_stats() -> dict[str, Any]: availability and disk statistics.
• cached(ttl: float = 300.0, maxsize: int | None = None): completion callback decorator; maxsize is bytes.
• Cached completion functions expose cache_clear() and cache_info().

Task and completion keys do not automatically fingerprint source/config/environment. Requires optional diskcache for persistence. See cache ownership and correctness. Origins: #51, #76.

Programs, executors and portable scripts¶

ToolkitProgram(version=None, namespace=None, name=None, binary=None, loader_class=None, executor_class=ToolkitExecutor, config_class=Config, binary_names=None) integrates Toolkit parsing, local/plugin loading and execution. .run(argv: list[str] | None = None, exit=True) -> None executes CLI parsing/dispatch; exit=False is intended mainly for testing and is not a general exception-propagating embedding API. Async CLI dispatch owns an asyncio.run() loop.

A complete custom application, saved as app.py in an installed environment:

from invoke_toolkit import Collection, Config, Context, task
from invoke_toolkit.program import ToolkitProgram


class AppConfig(Config, prefix="myapp", extra_defaults={"app": {"label": "custom"}}):
    """Application defaults and file prefix."""


@task
def hello(ctx: Context) -> None:
    print(ctx.get_config_value("app.label"))


def main() -> None:
    namespace = Collection(hello)
    ToolkitProgram(namespace=namespace, config_class=AppConfig, name="My application").run()


if __name__ == "__main__":
    main()

python app.py hello
python app.py --list

Providing namespace is explicit collection bootstrap: normal filesystem/plugin discovery is not automatically invoked for that namespace. Project configuration still loads from the current directory. For custom collection composition, populate namespace with Collection helpers before supplying it.

ToolkitExecutor(collection, config=None, core=None) defaults to Toolkit Config and an empty upstream ParseResult. execute(*tasks) handles synchronous calls; await execute_async(*tasks) awaits coroutine results in the same sequential graph. Task inputs are names, (name, kwargs) tuples or parsed ParserContext objects; results map task objects to their returned values. In an existing event loop, call execute_async directly rather than ToolkitProgram.run.

script(argv=None, exit=True, config_prefix=None) -> None collects decorated tasks from its caller's namespace and runs a Toolkit program. Guard it with if __name__ == "__main__" and declare dependencies for a PEP 723 script. Import-time guards do not sandbox Python imports or dependency installation. Origins: #11, #17, #104, async #121, compatibility #114.

ToolkitArgument extends upstream Argument's constructor with complete=None; the callback accepts context/incomplete text. .was_explicitly_set reflects parser got_value. Most task authors should use Annotated rather than construct arguments themselves (#41, #128).

Global helpers and output utilities¶

global_context() -> Context lazily creates a singleton, with non-TTY stdin disabled. Root run(command, **kwargs) and sudo(command, **kwargs) delegate to it. They are for REPL/top-level convenience; tasks should use their supplied ctx for loaded config and pipeline lifecycle. The global helper does not promise automatic project config loading. Origin: #13.

invoke_toolkit.output.get_console(stream="err") returns a shared SecretRedactorConsole for out, err or log; log also writes stderr. SecretRedactorConsole(secret_patterns=None, substitution="${}", ...) extends Rich Console; .secret_patterns selects environment names and .redact(text) filters a string. These consoles are shared output devices, not task-local secret containers. See redaction limits (#30).

invoke_toolkit.utils.fzf exposes is_fzf_available(), select(ctx, choices, prompt="Select an option", multi=False, preview=None, preview_window="right:50%", height="40%", reverse=True, use_fallback=True, **kwargs) and select_from_command(ctx, command, ...) with the same selection options. Results are a string, list of strings for multiselect, or None. Its Rich fallback is reduced functionality, not fzf feature parity; command/preview shell inputs must be trusted. See interactive selection. Origins: #80, #81, #82, #83.

Testing support¶

invoke_toolkit.testing.TestingToolkitProgram uses a Toolkit config with stdin disabled and defaults .run(..., exit=False) for tests. Upstream MockContext and Result/exception types remain available from the root. For assertions around task behavior, prefer the real execution surface relevant to your application rather than treating help/list imports as pure discovery.

Built-in create, config, shell and uv plugin tasks are CLI surfaces documented in CLI reference and their guides. The dist module has no actionable distribution task; no binary/download packaging API is promised.