{"id":15029241,"url":"https://github.com/onelivesleft/prettyerrors","last_synced_at":"2025-05-14T05:10:30.180Z","repository":{"id":45667964,"uuid":"157737460","full_name":"onelivesleft/PrettyErrors","owner":"onelivesleft","description":"Prettify Python exception output to make it legible.","archived":false,"fork":false,"pushed_at":"2024-03-05T23:33:11.000Z","size":329,"stargazers_count":2891,"open_issues_count":14,"forks_count":86,"subscribers_count":32,"default_branch":"master","last_synced_at":"2025-04-10T23:59:45.539Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onelivesleft.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELIST.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"onelivesleft","custom":["https://twitch.tv/onelivesleft"]}},"created_at":"2018-11-15T16:02:27.000Z","updated_at":"2025-04-08T06:56:48.000Z","dependencies_parsed_at":"2024-06-18T12:42:34.668Z","dependency_job_id":"a6e907b7-46b3-4f54-ab66-e1a053571712","html_url":"https://github.com/onelivesleft/PrettyErrors","commit_stats":{"total_commits":120,"total_committers":6,"mean_commits":20.0,"dds":"0.23333333333333328","last_synced_commit":"f61574e7fec2b7118fee5a59de61a8a734459ca1"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onelivesleft%2FPrettyErrors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onelivesleft%2FPrettyErrors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onelivesleft%2FPrettyErrors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onelivesleft%2FPrettyErrors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onelivesleft","download_url":"https://codeload.github.com/onelivesleft/PrettyErrors/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076850,"owners_count":22010611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T20:10:05.126Z","updated_at":"2025-05-14T05:10:30.148Z","avatar_url":"https://github.com/onelivesleft.png","language":"Python","funding_links":["https://github.com/sponsors/onelivesleft","https://twitch.tv/onelivesleft"],"categories":[],"sub_categories":[],"readme":"# pretty-errors\n\nPrettifies Python exception output to make it legible. Install it with\n```bash\npython -m pip install pretty_errors\n```\n\nIf 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:\n```bash\npython -m pretty_errors\n```\nThis 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`).\n\n---\n\n![Example](https://raw.githubusercontent.com/onelivesleft/PrettyErrors/master/example.png)\n\n---\n\nIf you have not installed it universally you can use it in your project simply by importing it:\n```python\nimport pretty_errors\n```\nNote 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.\n\n![Monochrome](https://raw.githubusercontent.com/onelivesleft/PrettyErrors/master/exampleMono.png)\n\nIf you want to configure the output then use `pretty_errors.configure()`, `pretty_errors.whitelist()`, `pretty_errors.blacklist()`, `pretty_errors.pathed_config()`.  For example:\n```python\nimport pretty_errors\npretty_errors.configure(\n    separator_character = '*',\n    filename_display    = pretty_errors.FILENAME_EXTENDED,\n    line_number_first   = True,\n    display_link        = True,\n    lines_before        = 5,\n    lines_after         = 2,\n    line_color          = pretty_errors.RED + '\u003e ' + pretty_errors.default_config.line_color,\n    code_color          = '  ' + pretty_errors.default_config.line_color,\n    truncate_code       = True,\n    display_locals      = True\n)\npretty_errors.blacklist('c:/python')\n```\n\n![Result](https://raw.githubusercontent.com/onelivesleft/PrettyErrors/master/example2.png)\n\n---\n\n##### Scraping STDERR\n\nSometimes 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:\n```python\npretty_errors.replace_stderr()\n```\nNote 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.  A good API will generally have a way to interact with the exception stack, which will allow for using `excepthook`: `replace_stderr` should be the last resort.  [See this comment for an example](https://github.com/onelivesleft/PrettyErrors/issues/16#issuecomment-751463605)\n\n---\n\n##### Whitelist / Blacklist:\n\nYou 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.\n\n---\n\n##### Pathed Configurations\n\nYou 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:\n\n```python\nmeh = pretty_errors.config.copy()\nmeh.line_color = meh.code_color = meh.filename_color = meh.function_color = meh.line_number_color = (\n    pretty_errors.GREY\n)\npretty_errors.pathed_config(meh, 'c:/python')\n```\n\n---\n\n##### Environment Variables\n\n* PYTHON_PRETTY_ERRORS\u003cbr\u003e\nYou may disable `pretty_errors` by setting the environment variable `PYTHON_PRETTY_ERRORS` to `0`.  i.e. at a command prompt:\n```bash\nset PYTHON_PRETTY_ERRORS=0\n```\n\nCalling `pretty_errors.activate()` will override this.\n\nIf you wish to selectively utilize `pretty_errors`, then use the above, and in your code perform your calculation to determine whether or not to call `pretty_errors.activate()`.\n\n* PYTHON_PRETTY_ERRORS_ISATTY_ONLY\u003cbr\u003e\nIt may be desirable to disable `pretty_errors` when you are redirecting output to a file (to keep error logs, for instance).  If you wish to do so, then setting `PYTHON_PRETTY_ERRORS_ISATTY_ONLY` to non-zero will cause `pretty_errors` to check if it is running in an interactive terminal, and only activate if so.\n\n```bash\nset PYTHON_PRETTY_ERRORS_ISATTY_ONLY=1\n```\n\nSetting this will disable `replace_stderr()` in the same situations, unless you call it with the `force` parameter: `replace_stderr(force=True)`.\n\nCalling `pretty_errors.activate()` will override this.\n\nYou may check `pretty_errors.terminal_is_interactive` to see if the terminal is interactive (`pretty_errors` sets this by checking `sys.stderr.isatty()`).  You can use this to select a different config.  For example:\n\n```python\nif not pretty_errors.terminal_is_interactive:\n    pretty_errors.mono()\n```\n\n\n---\n\n##### Configuration settings:\n\nConfiguration 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`.\n\n* `name`\u003cbr\u003e\nOptional field to store config name in.\n\n* `line_length`\u003cbr\u003e\nOutput will be wrapped at this point.  If set to `0` (which is the default) it will automatically match your console width.\n\n* `full_line_newline`\u003cbr\u003e\nInsert 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.\n\n* `separator_character`\u003cbr\u003e\nCharacter used to create the header line.  Hyphen is used by default.  If set to `None` or `''` then header will be disabled.\n\n* `display_timestamp`\u003cbr\u003e\nWhen enabled a timestamp is written in the traceback header.\n\n* `timestamp_function`\u003cbr\u003e\nFunction called to generate timestamp.  Default is `time.perf_counter`.\n\n* `exception_above`\u003cbr\u003e\nWhen enabled the exception is displayed above the stack trace.\n\n* `exception_below`\u003cbr\u003e\nWhen enabled the exception is displayed below the stack trace.\n\n* `stack_depth`\u003cbr\u003e\nThe maximum number of entries from the stack trace to display.  When `0` will display the entire stack, which is the default.\n\n* `top_first`\u003cbr\u003e\nWhen enabled the stack trace will be reversed, displaying the top of the stack first.\n\n* `always_display_bottom`\u003cbr\u003e\nWhen enabled (which is the default) the bottom frame of the stack trace will always be displayed.\n\n* `show_suppressed`\u003cbr\u003e\nWhen enabled all suppressed exceptions in the stack trace will be shown (typically they are suppressed because an exception above them has replaced them).  The normal python behaviour is to hide them.\n\n* `filename_display`\u003cbr\u003e\nHow the filename is displayed: may be `pretty_errors.FILENAME_COMPACT`, `pretty_errors.FILENAME_EXTENDED`, or `pretty_errors.FILENAME_FULL`\n\n* `line_number_first`\u003cbr\u003e\nWhen enabled the line number will be displayed first, rather than the filename.\n\n* `display_link`\u003cbr\u003e\nWhen enabled a link is written below the error location, which VSCode will allow you to click on.\n\n* `lines_after`, `lines_before`\u003cbr\u003e\nHow many lines of code to display for the top frame, before and after the line the exception occurred on.\n\n* `trace_lines_after`, `trace_lines_before`\u003cbr\u003e\nHow many lines of code to display for each other frame in the stack trace, before and after the line the exception occurred on.\n\n* `truncate_code`\u003cbr\u003e\nWhen enabled each line of code will be truncated to fit the line length.\n\n* `display_locals`\u003cbr\u003e\nWhen enabled, local variables appearing in the top stack frame code will be displayed with their values.\n\n* `display_trace_locals`\u003cbr\u003e\nWhen enabled, local variables appearing in other stack frame code will be displayed with their values.\n\n* `truncate_locals`\u003cbr\u003e\nWhen enabled the values of displayed local variables will be truncated to fit the line length.\n\n* `display_arrow`\u003cbr\u003e\nWhen enabled an arrow will be displayed for syntax errors, pointing at the offending token.\n\n* `arrow_head_character`, `arrow_tail_character`\u003cbr\u003e\nCharacters used to draw the arrow which points at syntax errors.\n\n* `inner_exception_message`\u003cbr\u003e\nMessage displayed when one exception occurs inside another, between the two exceptions.  Default is `None`, which will simply display the exceptions separated by the header.  If you want to emulate the default non-pretty behaviour, use this:\n\n`inner_exception_message = pretty_errors.MAGENTA + \"\\n  During handling of the above exception, another exception occurred:\\n\"`\n\nNote that if you use `top_first` then the order will be reversed, so you should use a message like this instead:\n\n`inner_exception_message = pretty_errors.MAGENTA + \"\\n  The above exception occurred during another exception:\\n\"`\n\n* `inner_exception_separator`\u003cbr\u003e\nDefault is `False`.  When set to `True` a header will be written before the `inner_exception_message`.\n\n* `prefix`\u003cbr\u003e\nText string which is displayed at the top of the report, just below the header.\n\n* `infix`\u003cbr\u003e\nText string which is displayed between each frame of the stack.\n\n* `postfix`\u003cbr\u003e\nText string which is displayed at the bottom of the exception report.\n\n* `reset_stdout`\u003cbr\u003e\nWhen 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.\n\n---\n\nThese 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.\n\n* `header_color`\u003cbr\u003e\nEscape sequence to set header color.\n\n* `timestamp_color`\u003cbr\u003e\nEscape sequence to set timestamp color.\n\n* `exception_color`\u003cbr\u003e\nEscape sequence to set exception color.\n\n* `exception_arg_color`\u003cbr\u003e\nEscape sequence to set exception arguments color.\n\n* `exception_file_color`\u003cbr\u003e\nEscape sequence to set color of filenames in exceptions (for example, in a FileNotFoundError).\n\n* `filename_color`\u003cbr\u003e\nEscape sequence to set filename color.\n\n* `line_number_color`\u003cbr\u003e\nEscape sequence to set line number color.\n\n* `function_color`\u003cbr\u003e\nEscape sequence to set function color.\n\n* `link_color`\u003cbr\u003e\nEscape sequence to set link color.\n\n* `line_color`\u003cbr\u003e\nEscape sequence to set the color of the line of code which caused the exception.\n\n* `code_color`\u003cbr\u003e\nEscape sequence to set the color of other displayed lines of code.\n\n* `arrow_head_color`, `arrow_tail_color`\u003cbr\u003e\nEscape sequence to set the color of the arrow which points at syntax errors.\n\n* `syntax_error_color`\u003cbr\u003e\nEscape sequence to set the color of the syntax error token.\n\n* `local_name_color`\u003cbr\u003e\nEscape sequence to set the color of local variable names.\n\n* `local_value_color`\u003cbr\u003e\nEscape sequence to set the color of local variable values.\n\n* `local_len_color`\u003cbr\u003e\nEscape sequence to set the color of local value length when local is truncated.\n\n`pretty_errors` has some built in escape sequence constants you can use when setting these colors:\n\n* `BLACK`\n* `GREY`\n* `RED`\n* `GREEN`\n* `YELLOW`\n* `BLUE`\n* `MAGENTA`\n* `CYAN`\n* `WHITE`\n\nFor 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`).\n\nFor example:\n```python\npretty_errors.configure(\n    line_color = pretty_errors.CYAN_BACKGROUND + pretty_errors.BRIGHT_WHITE\n)\n```\n\n---\n\n##### Further customization\n\nFor 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.\n\nFor example:\n\n```python\nclass MyExceptionWriter(pretty_errors.ExceptionWriter):\n    def write_header(self):\n        self.output_text('######## ERROR ########')\n\npretty_errors.exception_writer = MyExceptionWriter()\n```\n\nRun `help(pretty_errors.ExceptionWriter)` in the python interpreter for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonelivesleft%2Fprettyerrors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonelivesleft%2Fprettyerrors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonelivesleft%2Fprettyerrors/lists"}