A PEP Style Guide for Error Messages?

[Pathos315 (John Fallot)]

This is less a full fledged idea and more of an invitation to get thoughts and feedback.

Is there a widely established and uniform (or semi-uniform) style guide for error message handling?

In PEP8 currently, it mentions exceptions briefly, stating about exception hierarchies:

"Aim to answer the question “What went wrong?” programmatically, rather than only stating that “A problem occurred…”

But PEP8 doesn’t state best practices for logging errors, such as:

• when to include a repr in an error message (if at all)
• what to include in the error message
• whether or not to include a traceback, and if so, how
• what form a recovery message for an error should take (e.g. something along the lines of NNGroup’s Error Message Guidelines for user experience design)

I think a PEP that spells out the above could go a long way in helping new coders write better code that’s easier to diagnose and fix when errors arise. But I also acquiesce that I don’t know all the answers or best practices and I’d like to hear folks’ thoughts on this.

[cofiem (Mark)]

I like the idea of centralising good patterns for Python exceptions.

There are a range of tools and examples in popular libraries, but I agree that PEP8 and the Python docs are maybe a bit light on details.

A general discussion of what makes a good message would be beneficial, but I don’t know if that belongs in docs.python.org or somewhere more general in nature?

In terms of ‘style’, there is also the consideration of how to create and use custom exceptions.

Here are a few examples and linters that I’ve used to try to make useful and clear custom exceptions:

• Numpy exceptions: https://github.com/numpy/numpy/blob/f0b2fca91a1f5f50ff696895072f6fe9e69c1466/numpy/exceptions.py
• django exceptions: Django Exceptions | Django documentation | Django
• flake8-errmsg linter, a “Flake8 checker for raw literals inside raises.”: GitHub - henryiii/flake8-errmsg: Flake8 checker for raw literals inside raises.
• tryceratops is a linter for issues with how custom exceptions are defined and used. https://github.com/guilatrova/tryceratops/tree/main/docs/violations Some of the things it detects:
  • “Avoid specifying long messages outside the exception class”
  • “Define __reduce__ to make exception pickable”
  • “Do not log the exception object” (when using logging.exception, as it already logs the exception message)