command

command

Redirect dataclass

Redirect(op: str, target: str, fd: int | None = None)

A shell redirect parsed from a bash command (e.g. > file.txt, 2>&1).

Command dataclass

Command(
    raw: str,
    executable: str,
    args: tuple[str, ...],
    env: tuple[tuple[str, str], ...] = (),
    redirects: tuple[Redirect, ...] = (),
)

A single parsed shell command with executable, arguments, env vars, and redirects.

Use Command.parse(raw) to parse a command string, or access via CommandLine.

CommandLine dataclass

CommandLine(
    raw: str, parts: tuple[tuple[Command, str | None], ...]
)

A full parsed bash command line, potentially containing multiple commands joined by operators.

Use CommandLine.parse(raw) to parse. Access individual commands via .commands or the final command via .primary.

CommandLineQuery dataclass

CommandLineQuery(line: CommandLine)

Predicate helpers for inspecting a parsed CommandLine.

Wraps a CommandLine to answer common yes/no questions a hook condition needs — which executable runs, whether a subcommand or token appears, or whether the line redirects/pipes. Obtain one via CommandLine.q.

runs

runs(*argv: str) -> bool

Return whether the primary command's argv starts with argv.

Parameters:

Name	Type	Description	Default
*argv	str	Leading argv tokens to match, e.g. ("git", "push").	()

Returns:

Type	Description
bool	True if argv is non-empty and is a prefix of the primary
bool	command's argv.

has_subcommand

has_subcommand(name: str) -> bool

Return whether any command in the line carries name as an argument.

Parameters:

Name	Type	Description	Default
name	str	The subcommand/argument token to look for (e.g. "push").	required

Returns:

Type	Description
bool	True if name appears in the arguments of any parsed command.

any_command

any_command(pred: Callable[[Command], bool]) -> bool

Return whether any command in the line satisfies pred.

Parameters:

Name	Type	Description	Default
pred	Callable[[Command], bool]	Predicate applied to each parsed Command.	required

Returns:

Type	Description
bool	True if pred returns truthy for at least one command.

uses_redirect

uses_redirect() -> bool

Return whether the line redirects output or pipes between commands.

Returns:

Type	Description
bool	True if any command has a file redirect or the parts are joined
bool	by a pipe (|) operator.

contains_token

contains_token(token: str) -> bool

Return whether token appears as a whole argv element in any command.

Unlike has_subcommand this matches the executable as well as the arguments and requires an exact element match, not a substring.

Parameters:

Name	Type	Description	Default
token	str	The exact argv token to look for.	required

Returns:

Type	Description
bool	True if token equals an argv element of any parsed command.