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
[source]¶ 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 anErrorAction
).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.
-
static
exc_message
(exc_type, exc_value, exc_tb)[source]¶ 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)[source]¶ Returns the first argument of the exception instance. In the case of
SystemExit
this is the expected return code of the script.
-
static
-
class
pibootctl.term.
ErrorAction
(message, exitcode)[source]¶ 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
()[source]¶ Returns
True
if stdout is something other than a TTY (e.g. a file redirection or a pipe).
-
pibootctl.term.
term_is_utf8
()[source]¶ Returns
True
if the code-set of the current locale is ‘UTF-8’.
-
pibootctl.term.
pager
(enable=None)[source]¶ 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 isTrue
stdout will always be redirected, and likewise when enable isFalse
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!")