pibootctl.term

The pibootctl.term module contains various utilities for determining the type of terminal the script is running under (term_is_dumb(), term_is_utf8(), and term_size()), for directing terminal output through the system’s pager(), and for constructing an overall ErrorHandler for the script.

class pibootctl.term.ErrorHandler

Global configurable application exception handler. For “basic” errors (I/O errors, keyboard interrupt, etc.) just the error message is printed as there’s generally no need to confuse the user with a complete stack trace when it’s just a missing file. Other exceptions, however, are logged with the usual full stack trace.

The configuration can be augmented with other exception classes that should be handled specially by treating the instance as a dictionary mapping exception classes to ErrorAction tuples (or any 2-tuple, which will be converted to an ErrorAction).

For example:

>>> from pibootctl.term import ErrorAction, ErrorHandler
>>> import sys
>>> sys.excepthook = ErrorHandler()
>>> sys.excepthook[KeyboardInterrupt]
(None, 1)
>>> sys.excepthook[SystemExit]
(None, <function ErrorHandler.exc_value at 0x7f6178915e18>)
>>> sys.excepthook[ValueError] = (sys.excepthook.exc_message, 3)
>>> sys.excepthook[Exception] = ("An error occurred", 1)
>>> raise ValueError("foo is not an integer")
foo is not an integer

Note the lack of a traceback in the output; if the example were a script it would also have exited with return code 3.

clear()

Remove all pre-defined error handlers.

static exc_message(exc_type, exc_value, exc_tb)

Extracts the message associated with the exception (by calling str on the exception instance). The result is returned as a one-element list containing the message.

static exc_value(exc_type, exc_value, exc_tb)

Returns the first argument of the exception instance. In the case of SystemExit this is the expected return code of the script.

static syntax_error(exc_type, exc_value, exc_tb)

Returns the message associated with the exception, and an additional line suggested the user try the --help option. This should be used in response to exceptions indicating the user made an error in their command line.

class pibootctl.term.ErrorAction(message, exitcode)

Named tuple dictating the action to take in response to an unhandled exception of the type it is associated with in ErrorHandler. The message is an iterable of lines to be output as critical error log messages, and exitcode is an integer to return as the exit code of the process.

Either of these can also be functions which will be called with the exception info (type, value, traceback) and will be expected to return an iterable of lines (for message) or an integer (for exitcode).

pibootctl.term.term_is_dumb()

Returns True if stdout is something other than a TTY (e.g. a file redirection or a pipe).

pibootctl.term.term_is_utf8()

Returns True if the code-set of the current locale is ‘UTF-8’.

pibootctl.term.term_size()

Returns the size of the console as a (rows, cols) tuple.

pibootctl.term.pager(enable=None)

Used as a context manager to redirect stdout to the system’s pager utility (“pager”, “less”, or “more” are all attempted, in that order).

By default (when enable is None), stdout will only be redirected if stdout is connected to a TTY. If enable is True stdout will always be redirected, and likewise when enable is False the function will do nothing.

For example, the following script should print “Hello, world!”, piping the result through the system’s pager:

from pibootctl.term import pager
with pager():
    print("Hello, world!")