For example, we should be able to pretty-print dataclasses and dictionaries. This should also be customizeable.

It can be actually achieved using properties though, but the special syntax can be nevertheless useful due to how often this can be helpful.

│ in __setattr__:4                                                                                 │
│ ╭──────────────────────────────────── locals ─────────────────────────────────────╮              │
│ │                 cls = <class 'todoist_costs.errors.MissingDueTime'>             │              │
│ │ FrozenInstanceError = <class 'dataclasses.FrozenInstanceError'>                 │              │
│ │                name = '__traceback__'                                           │              │
│ │                self = MissingDueTime(                                           │              │
│ │                       │   …
│ │                       )                                                         │              │
│ │               value = <traceback object at 0x7f00779cd280>                      │              │
│ ╰─────────────────────────────────────────────────────────────────────────────────╯              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
FrozenInstanceError: cannot assign to field '__traceback__'

I do not think this can be fixed, it just has to be documented at https://anatoly-scherbakov.github.io/documented/compatibility/dataclasses/ page.

@documented
def calculate_customers_report(customers: List[Customer], requested_by: User) -> CustomerReport:
    """
    Build customers report.

    Requested by: {requested_by}.
    """

When this function is executed, the following message can be printed:

Build customers report.

Requested by: John Doe.

Before executing the function, its wrapper will substitute the arguments of the function call into the docstring and then will print the docstring using built-in Python logging system.

Purpose of this is to illustrate what is happening in the program in a human readable way in its log.

…on each subclass of DocumentedError.

Why

I want to create a rich Table and render it in the output. How do I do that?

What if I want to combine it with console markup?

The library documentation refers to a few articles about how exceptions might be used in controlling the control flow of an application. This is an interesting topic to explore further.

I personally very much like to write exceptions as dataclasses and inherit them from DocumentedError. This allows me to encapsulate business logic related information in those exceptions, and then to easily retrieve it in other parts of the application. For instance, I can do something like this:

def ask_hal(question: str, user_name: str):
    try:
        return hal.ask(question)
    except AnswerToAnswer as err:
        raise dataclasses.replace(
            err,
            user_name=user_name,
        )

In this question, we do not provide user_name to the internal layer of the application which is responsible for communication with HAL9000 computer, but we catch the error, enhance it with information available in the API layer, and reraise. Voilà.

Also

ExceptionList, a new feature introduced into Python recently, can be mentioned in relation to this topic.

When?

No idea; perhaps at some point I get inspired by a particular usage example and will get to writing this piece.

See: https://github.com/willmcgugan/rich

Should probably be left aligned instead.