Errors

face uses a hierarchy of exceptions for parse errors and runtime errors. All inherit from FaceException.

Exception hierarchy

FaceException
+-- ArgumentParseError
|   +-- ArgumentArityError
|   +-- InvalidSubcommand
|   +-- UnknownFlag
|   +-- InvalidFlagArgument
|   +-- InvalidPositionalArgument
|   +-- MissingRequiredFlags
|   +-- DuplicateFlag
+-- CommandLineError (also inherits SystemExit)
    +-- UsageError

Parse errors

These are raised during argument parsing, before the handler runs.

class face.FaceException

The basest base exception Face has. Rarely directly instantiated if ever, but useful for catching.

class face.ArgumentParseError

A base exception used for all errors raised during argument parsing.

Many subtypes have a “.from_parse()” classmethod that creates an exception message from the values available during the parse process.

class face.errors.ArgumentArityError

Raised when too many or too few positional arguments are passed to the command. See PosArgSpec for more info.

class face.InvalidSubcommand

Raised when an unrecognized subcommand is passed.

class face.UnknownFlag

Raised when an unrecognized flag is passed.

class face.InvalidFlagArgument

Raised when the argument passed to a flag (the value directly after it in argv) fails to parse. Tries to automatically detect when an argument is missing.

class face.errors.InvalidPositionalArgument

Raised when one of the positional arguments does not parse/validate as specified. See PosArgSpec for more info.

class face.errors.MissingRequiredFlags

Raised when a required flag is not passed. See Flag for more info.

class face.DuplicateFlag

Raised when a flag is passed multiple times, and the flag’s “multi” setting is set to ‘error’.

Parse errors in practice

When a command is run via Command.run(), parse errors are caught internally, printed to stderr, and the process exits with code 1. When using CommandChecker in tests, parse errors surface through the exit_code attribute.

To trigger specific parse errors:

from face import Command, Flag, ERROR

cmd = Command(lambda: None, name='example')
cmd.add('--count', parse_as=int, missing=ERROR)

# Missing required flag -> MissingRequiredFlags
# Bad flag value like --count abc -> InvalidFlagArgument
# Unknown flag like --bogus -> UnknownFlag
# Duplicate flag like --count 1 --count 2 -> DuplicateFlag (default multi='error')

Runtime errors

Runtime errors are raised from handler or middleware code during execution.

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.

CommandLineError inherits from both FaceException and SystemExit. If uncaught, it exits the process with code 1.

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.

Raise UsageError in a handler to signal incorrect usage:

import os
from face import UsageError

def my_handler(path):
    if not os.path.exists(path):
        raise UsageError(f'path does not exist: {path}')

When Command.run() catches a UsageError, it prints the message to stderr and exits with code 1. In tests with CommandChecker, use fail() or fail_1() to assert the error.