Skip to main content

Prettifies Python exception output to make it legible.

Project description

pretty-errors

Prettifies Python exception output to make it legible. Install it with

python -m pip install pretty_errors

If you want pretty_errors to be used whenever you run a python script you must add it to your python startup procedure. You can do so easily by running:

python -m pretty_errors

This is the recommended way to use pretty_errors; apart from being simpler and universal, using it will mean SyntaxError exceptions also get formatted prettily (which doesn't work if you are manually importing pretty_errors).


Example


If you have not installed it universally you can use it in your project simply by importing it:

import pretty_errors

Note you need to be running in a terminal capable of colour output in order to get colour output: in Windows this means powershell, cmder, etc. If you must use a monochrome terminal then you can call the helper function pretty_errors.mono(), which will set some config options in a way that is useful for monochrome output.

If you want to configure the output then use pretty_errors.configure(), pretty_errors.whitelist(), pretty_errors.blacklist(), pretty_errors.pathed_config(). For example:

import pretty_errors
pretty_errors.configure(
    separator_character = '*',
    filename_display    = pretty_errors.FILENAME_EXTENDED,
    line_number_first   = True,
    display_link        = True,
    lines_before        = 5,
    lines_after         = 2,
    line_color          = pretty_errors.RED + '> ' + pretty_errors.default_config.line_color,
    code_color          = '  ' + pretty_errors.default_config.line_color,
    truncate_code       = True,
    display_locals      = True
)
pretty_errors.blacklist('c:/python')

Result


Scraping STDERR

Sometimes it will be impossible for pretty_errors to utilize sys.excepthook: for instance, if you are using a framework which installs its own logging (such as uvicorn). In such cases, you can make pretty_errors scrape the output to stderr instead, replacing it with its own. To do so simple call:

pretty_errors.replace_stderr()

Note that this will lose some functionality, since pretty_errors will only have access to what is being output on screen, rather then the entire stack trace.


Whitelist / Blacklist:

You may use the functions whitelist(path) and blacklist(path) to add paths which will be necessary (whitelist) or excluded (blacklist). The top frame of the stack is never excluded.


Pathed Configurations

You may set up alternate configurations, which are triggered by the path to the code file of the frame. For example, if you were not interested in the system frames (those under 'c:/python') but did not want to hide them completely by using the blacklist you could do this:

meh = pretty_errors.config.copy()
meh.line_color = meh.code_color = meh.filename_color = meh.function_color = meh.line_number_color = (
    pretty_errors.GREY
)
pretty_errors.pathed_config(meh, 'c:/python')

Environment Variable

You may temporarily disable pretty_errors by setting the environment variable PYTHON_PRETTY_ERRORS to 0. i.e. at a command prompt:

set PYTHON_PRETTY_ERRORS=0

Calling pretty_errors.activate() will override this.


Configuration settings:

Configuration settings are stored in pretty_errors.config, though should be set using pretty_errors.configure(). A reference for the default config is stored in pretty_errors.default_config.

  • line_length
    Output will be wrapped at this point. If set to 0 (which is the default) it will automatically match your console width.

  • full_line_newline
    Insert a hard newline even if the line is full. If line_length is the same as your console width and this is enabled then you will see double newlines when the line is exactly full, so usually you would only set this if they are different.

  • separator_character
    Character used to create the header line. Hyphen is used by default. If set to None or '' then header will be disabled.

  • display_timestamp
    When enabled a timestamp is written in the traceback header.

  • timestamp_function
    Function called to generate timestamp. Default is time.perf_counter.

  • exception_above
    When enabled the exception is displayed above the stack trace.

  • exception_below
    When enabled the exception is displayed below the stack trace.

  • stack_depth
    The maximum number of entries from the stack trace to display. When 0 will display the entire stack, which is the default.

  • top_first
    When enabled the stack trace will be reversed, displaying the top of the stack first.

  • always_display_bottom
    When enabled (which is the default) the bottom frame of the stack trace will always be displayed.

  • filename_display
    How the filename is displayed: may be pretty_errors.FILENAME_COMPACT, pretty_errors.FILENAME_EXTENDED, or pretty_errors.FILENAME_FULL

  • line_number_first
    When enabled the line number will be displayed first, rather than the filename.

  • display_link
    When enabled a link is written below the error location, which VSCode will allow you to click on.

  • lines_after, lines_before
    How many lines of code to display for the top frame, before and after the line the exception occurred on.

  • trace_lines_after, trace_lines_before
    How many lines of code to display for each other frame in the stack trace, before and after the line the exception occurred on.

  • truncate_code
    When enabled each line of code will be truncated to fit the line length.

  • display_locals
    When enabled, local variables appearing in the top stack frame code will be displayed with their values.

  • display_trace_locals
    When enabled, local variables appearing in other stack frame code will be displayed with their values.

  • truncate_locals
    When enabled the values of displayed local variables will be truncated to fit the line length.

  • display_arrow
    When enabled an arrow will be displayed for syntax errors, pointing at the offending token.

  • arrow_head_character, arrow_tail_character
    Characters used to draw the arrow which points at syntax errors.

  • prefix
    Text string which is displayed at the top of the report, just below the header.

  • infix
    Text string which is displayed between each frame of the stack.

  • postfix
    Text string which is displayed at the bottom of the exception report.

  • reset_stdout
    When enabled the reset escape sequence will be written to stdout as well as stderr; turn this on if your console is being left with the wrong color.


These color strings will be output before the relevant part of the exception message. You may include non-escape sequence strings if you wish; if you do not have a terminal which supports color output, or simply want to include extra demarcation.

  • header_color
    Escape sequence to set header color.

  • timestamp_color
    Escape sequence to set timestamp color.

  • exception_color
    Escape sequence to set exception color.

  • exception_arg_color
    Escape sequence to set exception arguments color.

  • filename_color
    Escape sequence to set filename color.

  • line_number_color
    Escape sequence to set line number color.

  • function_color
    Escape sequence to set function color.

  • link_color
    Escape sequence to set link color.

  • line_color
    Escape sequence to set the color of the line of code which caused the exception.

  • code_color
    Escape sequence to set the color of other displayed lines of code.

  • arrow_head_color, arrow_tail_color
    Escape sequence to set the color of the arrow which points at syntax errors.

  • syntax_error_color
    Escape sequence to set the color of the syntax error token.

  • local_name_color
    Escape sequence to set the color of local variable names.

  • local_value_color
    Escape sequence to set the color of local variable values.

  • local_len_color
    Escape sequence to set the color of local value length when local is truncated.

pretty_errors has some built in escape sequence constants you can use when setting these colors:

  • BLACK
  • GREY
  • RED
  • GREEN
  • YELLOW
  • BLUE
  • MAGENTA
  • CYAN
  • WHITE

For each color there is a matching BRIGHT_ variant (i.e. pretty_errors.BRIGHT_RED), as well as a _BACKGROUND variant to set the background color (i.e. pretty_errors.RED_BACKGROUND).

For example:

pretty_errors.configure(
    line_color = pretty_errors.CYAN_BACKGROUND + pretty_errors.BRIGHT_WHITE
)

Further customization

For the most extensive customization (short of forking the package) you may override the default ExceptionWriter class, allowing you to tailor the output however you wish. Typically you will only need to override the write_ methods.

For example:

class MyExceptionWriter(pretty_errors.ExceptionWriter):
    def write_header(self):
        self.output_text('######## ERROR ########')

pretty_errors.exception_writer = MyExceptionWriter()

Run help(pretty_errors.ExceptionWriter) in the python interpreter for more details.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pretty-errors, version 1.2.13
Filename, size File type Python version Upload date Hashes
Filename, size pretty_errors-1.2.13-py3-none-any.whl (15.5 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size pretty_errors-1.2.13.tar.gz (17.4 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page