Skip to content

cli ¤

Module that contains the command line application.

ArgParser ¤

Bases: ArgumentParser

A custom argument parser with a helper method to add boolean flags.

add_bool_argument ¤

add_bool_argument(
    truthy: Sequence[str],
    falsy: Sequence[str],
    truthy_help: str = "",
    falsy_help: str = "",
    **kwargs: Any
) -> None

Add a boolean flag/argument to the parser.

Parameters:

  • truthy (Sequence[str]) –

    Values that will store true in the destination.

  • falsy (Sequence[str]) –

    Values that will store false in the destination.

  • truthy_help (str, default: '' ) –

    Help for the truthy arguments.

  • falsy_help (str, default: '' ) –

    Help for the falsy arguments.

  • **kwargs (Any, default: {} ) –

    Remaining keyword arguments passed to argparse.ArgumentParser.add_argument.

Source code in src/failprint/cli.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def add_bool_argument(
    self,
    truthy: Sequence[str],
    falsy: Sequence[str],
    truthy_help: str = "",
    falsy_help: str = "",
    **kwargs: Any,
) -> None:
    """Add a boolean flag/argument to the parser.

    Arguments:
        truthy: Values that will store true in the destination.
        falsy: Values that will store false in the destination.
        truthy_help: Help for the truthy arguments.
        falsy_help: Help for the falsy arguments.
        **kwargs: Remaining keyword arguments passed to `argparse.ArgumentParser.add_argument`.
    """
    truthy_kwargs = {**kwargs, "help": truthy_help, "action": "store_true"}
    falsy_kwargs = {**kwargs, "help": falsy_help, "action": "store_false"}

    mxg = self.add_mutually_exclusive_group()
    mxg.add_argument(*truthy, **truthy_kwargs)
    mxg.add_argument(*falsy, **falsy_kwargs)

add_flags ¤

add_flags(
    parser: ArgParser, *, set_defaults: bool = True
) -> ArgParser

Add some boolean flags to the parser.

We made this method separate and public for its use in duty.

Parameters:

  • parser (ArgParser) –

    The parser to add flags to.

  • set_defaults (bool, default: True ) –

    Whether to set default values on arguments.

Returns:

Source code in src/failprint/cli.py 
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
def add_flags(parser: ArgParser, *, set_defaults: bool = True) -> ArgParser:
    """Add some boolean flags to the parser.

    We made this method separate and public
    for its use in [duty](https://github.com/pawamoy/duty).

    Arguments:
        parser: The parser to add flags to.
        set_defaults: Whether to set default values on arguments.

    Returns:
        The augmented parser.
    """
    # IMPORTANT: the arguments destinations should match
    # the parameters names of the failprint.runners.run function.
    # As long as names are consistent between the two,
    # it's very easy to pass CLI args to the function,
    # and it also allows to avoid duplicating the parser arguments
    # in dependent projects like duty (https://github.com/pawamoy/duty) :)
    parser.add_argument(
        "-c",
        "--capture",
        choices=list(Capture),
        type=Capture,
        help="Which output to capture. Colors are supported with 'both' only, unless the command has a 'force color' option.",
    )
    parser.add_argument(
        "-f",
        "--fmt",
        "--format",
        dest="fmt",
        choices=formats.keys(),
        type=accept_custom_format,
        default=None,
        help="Output format. Pass your own Jinja2 template as a string with '-f custom=TEMPLATE'. "
        "Available variables: command, title (command or title passed with -t), code (exit status), "
        "success (boolean), failure (boolean), number (command number passed with -n), "
        "output (command output), nofail (boolean), quiet (boolean), silent (boolean). "
        "Available filters: indent (textwrap.indent).",
    )
    parser.add_bool_argument(
        ["-y", "--pty"],
        ["-Y", "--no-pty"],
        dest="pty",
        default=True if set_defaults else None,
        truthy_help="Enable the use of a pseudo-terminal. PTY doesn't allow programs to use standard input.",
        falsy_help="Disable the use of a pseudo-terminal. PTY doesn't allow programs to use standard input.",
    )
    parser.add_bool_argument(
        ["-p", "--progress"],
        ["-P", "--no-progress"],
        dest="progress",
        default=True if set_defaults else None,
        truthy_help="Print progress while running a command.",
        falsy_help="Don't print progress while running a command.",
    )
    # TODO: specific to the format
    parser.add_bool_argument(
        ["-q", "--quiet"],
        ["-Q", "--no-quiet"],
        dest="quiet",
        default=False if set_defaults else None,
        truthy_help="Don't print the command output, even if it failed.",
        falsy_help="Print the command output when it fails.",
    )
    # TODO: specific to the format
    parser.add_bool_argument(
        ["-s", "--silent"],
        ["-S", "--no-silent"],
        dest="silent",
        default=False if set_defaults else None,
        truthy_help="Don't print anything.",
        falsy_help="Print output as usual.",
    )
    parser.add_bool_argument(
        ["-z", "--zero", "--nofail"],
        ["-Z", "--no-zero", "--strict"],
        dest="nofail",
        default=False if set_defaults else None,
        truthy_help="Don't fail. Always return a success (0) exit code.",
        falsy_help="Return the original exit code.",
    )
    return parser

get_parser ¤

get_parser() -> ArgParser

Return the CLI argument parser.

Returns:

Source code in src/failprint/cli.py 
137
138
139
140
141
142
143
144
145
146
147
148
149
def get_parser() -> ArgParser:
    """Return the CLI argument parser.

    Returns:
        An argparse parser.
    """
    parser = add_flags(ArgParser(prog="failprint"))
    # TODO: specific to the format
    parser.add_argument("-n", "--number", type=int, default=1, help="Command number. Useful for the 'tap' format.")
    # TODO: specific to the format
    parser.add_argument("-t", "--title", help="Command title. Default is the command itself.")
    parser.add_argument("cmd", metavar="COMMAND", nargs="+")
    return parser

main ¤

main(args: list[str] | None = None) -> int

Run the main program.

This function is executed when you type failprint or python -m failprint.

Parameters:

  • args (list[str] | None, default: None ) –

    Arguments passed from the command line.

Returns:

  • int –

    An exit code.

Source code in src/failprint/cli.py 
152
153
154
155
156
157
158
159
160
161
162
163
164
165
def main(args: list[str] | None = None) -> int:
    """Run the main program.

    This function is executed when you type `failprint` or `python -m failprint`.

    Parameters:
        args: Arguments passed from the command line.

    Returns:
        An exit code.
    """
    parser = get_parser()
    opts = parser.parse_args(args).__dict__.items()
    return run(**{_: value for _, value in opts if value is not None}).code