Skip to content

📝 """Docstring"""

Having installed documented, you can use DocumentedError as base for your custom exception classes. The immediate effect of that is that raising these exceptions will print their docstrings in the stack trace.

examples/docstring.py

from documented import DocumentedError


class HALHasGoneCrazy(DocumentedError):
    """
    Something is amiss.

    It would seem that HAL9000 has gone crazy!
    """

raise HALHasGoneCrazy()

python

Traceback (most recent call last):
  File "📂/docstring.py", line 11, in <module>
    raise HALHasGoneCrazy()
HALHasGoneCrazy: Something is amiss.

It would seem that HAL9000 has gone crazy!

Styling Recommendations

  • Create your own exception classes in terms of your domain, to play a part in your business logic, instead of using built-in Exception or ValueError.
  • Refrain from using the word Exception or Error in their names.
  • A good IDE can convey the information that something is an exception;
  • Even discarding that, seeing raise FooBarBaz is sufficient to understand what kind of guy FooBarBaz is.

🙂 Good

  • ✅ BalanceInsufficient
  • ✅ PlanetNotFound
  • ✅ TetOffline
  • ✅ OrderDeclined

🙁 Not so good

  • 🚫 BalanceInsufficientError
  • 🚫 PlanetNotFoundException
  • 🚫 CatastrophicalError
  • 🚫 UnknownError