Command

class face.Command(func, name=None, doc=None, **kwargs)

The central type in the face framework. Instantiate a Command, populate it with flags and subcommands, and then call command.run() to execute your CLI.

Note that only the first three constructor arguments are positional, the rest are keyword-only.

Parameters:

• func (callable) – The function called when this command is run with an argv that contains no subcommands.
• name (str) – The name of this command, used when this command is included as a subcommand. (Defaults to name of function)
• doc (str) – A description or message that appears in various help outputs.
• flags (list) – A list of Flag instances to initialize the Command with. Flags can always be added later with the .add() method.
• posargs (bool) – Pass True if the command takes positional arguments. Defaults to False. Can also pass a PosArgSpec instance.
• post_posargs (bool) – Pass True if the command takes additional positional arguments after a conventional ‘–’ specifier.
• help (bool) – Pass False to disable the automatically added –help flag. Defaults to True. Also accepts a HelpHandler instance, see those docs for more details.
• middlewares (list) – A list of @face_middleware decorated callables which participate in dispatch. Also addable via the .add() method. See Middleware docs for more details.

add(*a, **kw)

Add a flag, subcommand, or middleware to this Command.

If the first argument is a callable, this method contructs a Command from it and the remaining arguments, all of which are optional. See the Command docs for for full details on names and defaults.

If the first argument is a string, this method constructs a Flag from that flag string and the rest of the method arguments, all of which are optional. See the Flag docs for more options.

If the argument is already an instance of Flag or Command, an exception is only raised on conflicting subcommands and flags. See add_command for details.

Middleware is only added if it is already decorated with @face_middleware. Use .add_middleware() for automatic wrapping of callables.

add_command(subcmd)

Add a Command, and all of its subcommands, as a subcommand of this Command.

Middleware from the current command is layered on top of the subcommand’s. An exception may be raised if there are conflicting middlewares or subcommand names.

add_middleware(mw)

Add a single middleware to this command. Outermost middleware should be added first. Remember: first added, first called.

get_dep_names(path=())

Get a list of the names of all required arguments of a command (and any associated middleware).

By specifying path, the same can be done for any subcommand.

get_flag_map(path=(), with_hidden=True)

Command’s get_flag_map differs from Parser’s in that it filters the flag map to just the flags used by the endpoint at the associated subcommand path.

prepare(paths=None)

Compile and validate one or more subcommands to ensure all dependencies are met. Call this once all flags, subcommands, and middlewares have been added (using .add()).

This method is automatically called by .run() method, but it only does so for the specific subcommand being invoked. More conscientious users may want to call this method with no arguments to validate that all subcommands are ready for execution.

run(argv=None, extras=None, print_error=None)

Parses arguments and dispatches to the appropriate subcommand handler. If there is a parse error due to invalid user input, an error is printed and a CommandLineError is raised. If not caught, a CommandLineError will exit the process, typically with status code 1. Also handles dispatching to the appropriate HelpHandler, if configured.

Defaults to handling the arguments on the command line (sys.argv), but can also be explicitly passed arguments via the argv parameter.

Parameters:

• argv (list) – A sequence of strings representing the command-line arguments. Defaults to sys.argv.
• extras (dict) – A map of additional arguments to be made available to the subcommand’s handler function.
• print_error (callable) – The function that formats/prints error messages before program exit on CLI errors.

Note

For efficiency, run() only checks the subcommand invoked by argv. To ensure that all subcommands are configured properly, call prepare().

Command Exception Types

In addition to all the Parser-layer exceptions, a command or user endpoint function can raise:

class face.CommandLineError(msg, code=1)

A FaceException and SystemExit subtype that enables safely catching runtime errors that would otherwise cause the process to exit.

If instances of this exception are left uncaught, they will exit the process.

If raised from a run() call and print_error is True, face will print the error before reraising. See face.Command.run() for more details.

class face.UsageError(msg, code=1)

Application developers should raise this CommandLineError subtype to indicate to users that the application user has used the command incorrectly.

Instead of printing an ugly stack trace, Face will print a readable error message of your choosing, then exit with a nonzero exit code.