Command lines
Command
A single parsed shell command with executable, arguments, env vars, and redirects.
Usage
Command()Use Command.parse(raw) to parse a command string, or access via CommandLine.
Attributes
raw: builtins.str-
The command’s source text.
executable: builtins.str-
The command name, or “” when nothing parsed.
args: tuple[str, …]-
The arguments after the executable.
env: tuple[tuple[str, str], …]-
The leading
VAR=valassignments, as name/value pairs. redirects: tuple[Redirect, …]-
The command’s file redirects.
span: tuple[builtins.int, builtins.int] | None- The command’s byte span in the line, or None when a redirect absorbed a trailing word; excluded from equality and repr.
Attributes
| Name | Description |
|---|---|
| words |
The structural words: words[0] is the executable, words[1:] parallel args.
|
words
The structural words: words[0] is the executable, words[1:] parallel args.
words: tuple[Word, …]
CommandLine
A full parsed bash command line, potentially containing multiple commands joined by operators.
Usage
CommandLine()Use CommandLine.parse(raw) (or the cached parse_command_line) to parse. Access individual commands via .commands or the final command via .primary.
Attributes
raw: builtins.str-
The line’s source text.
parts: tuple[tuple[Command, str | None], …]-
Each command paired with the operator that follows it (None for the last).
commands: tuple[Command, …]-
The parsed commands, in line order.
primary: Command | None-
The final command, or None when nothing parsed.
head: Command | None-
The first command, or None when nothing parsed.
prefixes: tuple[str, …]-
The permission-style prefix of each command, absent prefixes dropped.
q: CommandLineQuery-
The predicate helper for this line.
occurrences: tuple[Occurrence, …]- One Occurrence per part, in line order.
Methods
| Name | Description |
|---|---|
| quote() |
Quote text as one POSIX-sh word, with Python shlex.quote semantics.
|
quote()
Quote text as one POSIX-sh word, with Python shlex.quote semantics.
Usage
quote(text)CommandLineQuery
Predicate helpers for inspecting a parsed CommandLine. Obtain one via CommandLine.q.
Usage
CommandLineQuery()Attributes
line: CommandLine- The command line these predicates run over.
Occurrence
One command of a CommandLine with its position and joining context.
Usage
Occurrence()Attributes
line: CommandLine-
The command line this occurrence belongs to.
index: builtins.int-
This command’s index into
line.parts. command: Command-
The command at this occurrence’s index.
prev_op: builtins.str | None-
The operator joining the previous command; None at index 0.
next_op: builtins.str | None-
The operator joining this command to the next; None for the final command.
piped: builtins.bool- Whether this command sits on either side of a pipe.
Attributes
| Name | Description |
|---|---|
| host | The occurrence hosting this nested part, or None at top level. |
| nesting | Substitution/payload hops below top level; 0 for a top-level command. |
| quote_contexts |
Enclosing payload quote layers outermost-first: "'", '"', or "" (bare).
|
host
The occurrence hosting this nested part, or None at top level.
host: Occurrence | None
nesting
Substitution/payload hops below top level; 0 for a top-level command.
nesting: builtins.int
quote_contexts
Enclosing payload quote layers outermost-first: "'", '"', or "" (bare).
quote_contexts: tuple[str, …]
Methods
| Name | Description |
|---|---|
| embeddable() |
Whether splicing text at this occurrence survives every enclosing quote layer.
|
| quote_for() |
One shell-word spelling of text that survives every enclosing layer, or None.
|
embeddable()
Whether splicing text at this occurrence survives every enclosing quote layer.
Usage
embeddable(text)quote_for()
One shell-word spelling of text that survives every enclosing layer, or None.
Usage
quote_for(text)Redirect
A shell redirect parsed from a bash command (e.g. > file.txt, 2>&1).
Usage
Redirect()Attributes
op: builtins.str-
The redirect operator (
>,>>,2>&1yields>&). target: builtins.str-
The redirect target word.
fd: builtins.int | None- The leading file descriptor number, or None when unspecified.
Word
One structural word of a parsed command (Command.words).
Usage
Word()Attributes: raw: verbatim source text. value: literal with quotes/escapes removed; None when an expansion taints it. span: byte span in the owning CommandLine.raw; None without verbatim source. expandable: bash would glob/brace/tilde-expand despite the literal value.
parse_command_line
parse_command_line=lru_cache(maxsize=4096)(CommandLine.parse)
command_prefixes()
Permission-style prefixes for each command of a shell command line.
Usage
command_prefixes(command)Splits command at shell operators via the bash grammar, then per command unwraps leading wrappers (sudo, env, timeout, …) to reach the real executable. A multi-level tool (git, docker, …) keeps its first non-flag argument as the subcommand.
Example
>>> command_prefixes("sudo git push -f && echo hi")(‘git push’, ‘echo’)