zuke.tools._tooling

← Python API reference

The settings every wrapper's settings extend: @zuke/core's tooling base.

zuke on PyPI ↗ 3 symbols

Symbols

#

DynamicToolSettings

class 
class DynamicToolSettings(ToolSettings)

Fluent settings for a defineTool tool: build the argv with DynamicToolSettings.arg/DynamicToolSettings.flag/DynamicToolSettings.option (in call order), plus all the shared chainers (cwd, env, noThrow, quiet, toolPath, args).

  • arg(*values: str | float) -> Self

    Append raw positional/argument tokens.

  • flag(name: str) -> Self

    Append a boolean flag, e.g. flag("verbose") → --verbose (or -v).

  • option(name: str, value: str | float) -> Self

    Append a flag and its value as two tokens, e.g. --output dist.

#

SubcommandSettings

class 
class SubcommandSettings(ToolSettings)

Base for a wrapper over a CLI organised into subcommand groups — a command path built with command plus repeatable --flag [value] options built with flag. The agent and cloud wrappers (gh, gcloud, claude, gemini, codex) share this shape; each sets its binary via ToolSettings.defaultTool and, when needed, a fixed prefix via leadingTokens or between-command global flags via middleTokens.

The argv is assembled as [...leadingTokens(), ...command, ...middleTokens(), ...flags], keeping every token a discrete argv entry so command construction stays injection-free.

  • command(*parts: str | float) -> Self

    Append command-path tokens — the group, verb, and operands — in order.

  • flag(name: str, value: str | float | None=None) -> Self

    Add an arbitrary flag. With a value it renders --name value; without one the bare --name. Repeatable.

#

ToolSettings

class 
class ToolSettings(Settings)

Abstract fluent base for tool settings. Subclasses provide the binary (defaultTool) and the pure subcommand argv (buildArgs); the base provides the shared chainers and run.

  • env(record: Mapping[str, str]) -> Self

    Merge additional environment variables for the process.

  • cwd(path: str) -> Self

    Set the working directory for the process.

  • no_throw() -> Self

    Do not throw on a non-zero exit; inspect code on the output instead.

  • quiet() -> Self

    Suppress live stdout/stderr streaming to the terminal.

  • kill_after(ms: float) -> Self

    Kill the tool if it runs longer than ms milliseconds, raising a CommandTimeoutError. Fires even under noThrow.

  • max_captured_bytes(bytes: float) -> Self

    Cap how much of each captured stream the run keeps in memory, in bytes (default 8 MiB). Once the cap is reached the oldest bytes are dropped, CommandOutput.truncated is set, and CommandOutput.text prefixes a notice. Raise it for a tool whose whole output must be parsed — a coverage report, a --json dump — and lower it to bound a chatty one. Live streaming to the terminal is never capped.

  • tool_path(path: str) -> Self

    Override the binary to run (e.g. an absolute path to the tool).

  • from_node_modules() -> Self

    Resolve the binary npx-style: walk up from the working directory looking for node_modules/.bin/<tool>, falling back to PATH on a miss. Overrides both the wrapper default and the ambient ZUKE_TOOL_RESOLUTION. Has no effect once toolPath is set (an explicit path always wins).

  • from_path() -> Self

    Resolve the binary from PATH only, ignoring any node_modules/.bin.

  • args(*extra: str | float) -> Self

    Escape hatch: append raw arguments after all typed options.