# A PEP Style Guide for Error Messages?

**URL:** <https://discuss.python.org/t/a-pep-style-guide-for-error-messages/30842>\
**Category:** Ideas\
**Tags:** error-handling\
**Created:** [August 2, 2023, 6:33pm UTC](https://discuss.python.org/t/a-pep-style-guide-for-error-messages/30842 "2023-08-02T18:33:31Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![Pathos315](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/pathos315/32/12020_2.png) [@Pathos315](https://discuss.python.org/u/Pathos315)\
**Post date:** [August 2, 2023, 6:33pm UTC](https://discuss.python.org/t/a-pep-style-guide-for-error-messages/30842/1 "2023-08-02T18:33:32Z")

</div>

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](https://www.nngroup.com/articles/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.

---

<div class="post-metadata">

**Author:** ![cofiem](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/cofiem/32/12747_2.png) [@cofiem](https://discuss.python.org/u/cofiem)\
**Post date:** [August 3, 2023, 11:46am UTC](https://discuss.python.org/t/a-pep-style-guide-for-error-messages/30842/2 "2023-08-03T11:46:09Z")

</div>

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](http://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](https://github.com/numpy/numpy/blob/f0b2fca91a1f5f50ff696895072f6fe9e69c1466/numpy/exceptions.py)
- django exceptions: [Django Exceptions | Django documentation | Django](https://docs.djangoproject.com/en/4.2/ref/exceptions/)
- flake8-errmsg linter, a “Flake8 checker for raw literals inside raises.”: [GitHub - henryiii/flake8-errmsg: Flake8 checker for raw literals inside raises.](https://github.com/henryiii/flake8-errmsg)
- tryceratops is a linter for issues with how custom exceptions are defined and used. [https://github.com/guilatrova/tryceratops/tree/main/docs/violations](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)