# 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!")