Custom exceptions

[aroberge]

Background

On Twitter (https://twitter.com/willmcgugan/status/1450097933169405956), Will McGugan suggested the following:

Regarding exceptions, wouldn't it be great if:

a) the exception rendered a brief piece of markdown with a description of the problem.

b) gave you a link to a web service with a more detailed error.

c) proposed a solution

He indicated later that this was for exceptions in a custom project.

friendly already attempts to do something like a) and c) for an ever growing number of cases for standard Python exceptions. It can either give the information all at once, or breaking it up (in an interactive session) as answers to the questions "what" (for part a) and "why" (for part c). Internally, the answer to "what" is known as the "generic" explanation, and the answer to "why" is known as the "specific" explanation.

friendlyhas also a www() function that can open up a browser at some predetermined locations.

friendly uses markdown, processed by Rich (https://github.com/willmcgugan/rich).

The following screenshot is a concrete example.

In addition, friendly support translation for these explanations; currently only English and French are the only two language supported.

Comments welcome

Feel free to contribute to the discussion below.

[aroberge]

To start the discussion in concrete terms, here is a possible structure:

import sys

class MyException(Exception):
    def custom_description(self):
        return "Some description using markdown syntax"
   
    def custom_solution(self):
        exc_type, exc_value, tb = sys.exc_info
        # use the above to analyse the problem
       return "Some solution"

    def custom_link(self):
        return "Useful URL"
        

Programs making use of custom exceptions could retrieve the relevant information and do their own formatting.

Initially, I suspect that there would be very little need for translations. Still, it could easily be added after the fact by adding explicit functions, as follows:

import sys

class MyException(Exception):
    def custom_description(self):
        return "Some description using markdown syntax"

    def custom_description_fr(self):
        return "Some description in French using markdown syntax"

Suppose that a user of friendly uses French as their preferred language. Internally, friendly might do something like this:

lang = get_user_language()
if hasattr(exc, f'custom_description_{lang}'):
    description = getattr(exc, f'custom_description_{lang}')()
elif hasattr(exc, 'custom_description'):
    description =exc.custom_description()
else:
    description = ''

[willmcgugan]

That's along the lines of what I was thinking of.

I'd be tempted to make them dunder methods, to avoid any naming clashes (as unlikely as that is).

Where does get_user_language come from? Is it stdlib?

I'm thinking it might be better implemented as attributes, that way they could be properties if required to be dynamic, but the typical case would be a string:

class MyException:
    __help__ = "Something went *wrong*"

In the case of languages, they help could be a dict:

class MyException:
    __help__ = {
        "en": "Something went *wrong*"
        "fr":  "Quelque chose a mal tourné"
    }

Additional help texts could be provided via similarly named attributes, like __help_solution__.

Links could be exposed in a similar way.

Thoughts?

Once we hammer out a spec, we should get community feedback. It would be fantastic if it became a standard.

[aroberge]

About language support

get_user_lang() is not in the standard library; it is pseudo-code for something that friendly includes internally to determine what language to use to display the answer.

I suspect that 99% of the users would not want to either use or support any language other than English. This is why I thought that the default names for the attributes or functions should contain (or return) the text in English., and (to use your notation) simply require to get exc.__help__ by default rather than exc.__help__['en'].

About attributes vs functions

I do like attributes for the description (__help__). In simple cases, I could see something like

class MyException(Exception):
    "Something went wrong"
    __help__ = __doc__

Having the __help__ attribute would be useful in identifying this exception as implementing this new "protocol".

For custom exceptions, I could imagine then being called with custom arguments, and having the solution depend on the value of these arguments. This is why I would have a preference to use a function by default. With friendly, I found it often useful to query the frame's locals and globals to provide an accurate explanation.

I'm wondering if the value of the arguments might also affect the description.

For the link, an attribute would likely be adequate .

About dunders

I've created my own dunders in the past for some toy projects and got criticisms from people who wrote that dunders were meant to be reserved for Python's own usage. While I like the idea of using dunders, to avoid any pushback, if possible, I'd prefer to have dunder that are split in two words, such as __rich_console__ ;-), or __help_solution__, rather than single words: as far as I know, Python's dunder are all single words.

However, if there's enough support from the community, I think that single word dunders, such as __help__, would be fine.

[willmcgugan]

A single "namespace" of sorts makes sense. If it were __help_*__ collisions are unlikely.

What kind of custom parameters would you want on a __help_solution__ method? A method would make it more difficult to inspect exception objects.

With regards to the language, I'm not so keen on my dict idea now. It would be nice if appeared to be a simple static string. If the author wanted to offer more than one language, then __help__ could be a property that returned the appropriate translation.

So this would be the typical case:

__help__ = """All about this exception"""

But you could do this:

@property
def __help__(self) -> str:
    _locale, encoding = locale.getlocale()
    if _locale.startswith("fr_"):
        return "French help"
    else:
       return "English help"

Other things we might need __help_format__ which would default to "markdown". And __help_link__ for a web link. What do you think?

[aroberge]

• I like the idea of an attribute named __help_format__ which would default to "markdown".
• I like the idea of an attribute named __help_link__ for a web link.
• I like the idea of a simple attribute named __help__ for the default description.

I will address the issue of support for languages other than English separately. But, before that, I will create a custom example to illustrate why I think it might make sense to have __help_solution__ as a method. I will do this as a separate comment.

[aroberge]

Here is a contrived example, which shows the advantage of having __help_solution__ as a function instead of as an attribute.

salaries = {
    "employee": [25_000, 50_000],
    "manager": [50_000, 75_000]
}


class SalaryMismatch(Exception):
    """Indicates that the salary is not in the valid range
       for the stated position.
    """
    __help__ = __doc__
    __help_link__ = "URL_for_employee_compensation_range"

    def __init__(self, position, salary):
        self.position = position
        self.salary = salary
        super().__init__(f"{salary} is not valid for this position: {position}.")

    def __help_solution__(self):
        valid_range = f"${salaries[self.position][0]} to ${salaries[self.position][1]}"
        return (f"{self.salary} is not valid for {self.position}s.\n"
                f"The valid salary range for {self.position}s is {valid_range}.")


def create_position(position, salary):
    if not salaries[position][0] <= salary <= salaries[position][1]:
        raise SalaryMismatch(position, salary)
    print(f"{position} created; everything is good.\n")


create_position("manager", 60000)
try:
    create_position("employee", 60000)
except SalaryMismatch as e:
    print(e)
    print("---")
    print(e.__help_solution__())
    print(f"See {e.__help_link__} for details.")

The output (which I did to make sure that it was all valid code) is as follows:

manager created; everything is good.

60000 is not valid for this position: employee.
---
60000 is not valid for employees.
The valid salary range for employees is $25000 to $50000.
See URL_for_employee_compensation_range for details.

If I think of this in the context of using friendly: friendly replaces the default excepthook (like, I imagine, rich.traceback does).

So, in an interactive session, I might have the following

>>> from exc import create_position
>>> create_position("employee", 60000)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Users\andre\temp\exc.py", line 27, in create_position
    raise SalaryMismatch(position, salary)
exc.SalaryMismatch: 60000 is not valid for this position: employee.

With friendly, I could then query further and use why() to retrieve the information from SalaryMismatch.__help_solution__(). Using www() could be made to open the given URL with the default browser.

Instead of a multi-parameter exception, I could create many different exceptions, for example: one for each position type. However, as the number of arguments increase, one would get a "combinatorial explosion" for the number of custom exceptions to create.

For your project, perhaps there would never be a risk of such combinatorial explosion. However, if a protocol for custom exception is to be adopted, I think it should be flexible enough to accommodate other cases.

[aroberge]

Using the above example, it literally took me less than 10 minutes to implement support for what() and why() in friendly-traceback (the base version that does not use Rich; friendly uses Rich and friendly-traceback).

Friendly-traceback version 0.4.55. [Python version: 3.9.5]
Type 'Friendly' for help on special functions/methods.

[1]: import ignore

[2]: ignore.create_position("manager", 10)

Traceback (most recent call last):
  Code block [2], line 1, in <module>
    ignore.create_position("manager", 10)
  File "ignore.py", line 27, in create_position
    raise SalaryMismatch(position, salary)
SalaryMismatch: 10 is not valid for this position: manager.

[3]: what()

    Indicates that the salary is not in the valid range
           for the stated position.


[4]: why()

    10 is not valid for managers.
    The valid salary range for managers is $50000 to $75000.

(I use ignore.py as a private scratch file in the repo, that is never saved.)

[aroberge]

Note: the changes to friendly-traceback have only been implemented in my local repo.

[aroberge]

Regarding support for languages other than English. As mentioned before, I suspect that the vast majority of people that would decide to include support for this proposed protocole in their own library would only support English (in the foreseeable future). I also suspect that the vast majority of people writing program/tools making use of this as clients would also want to support only English.

The intersection of library writer and users who both want to have support for the same language is likely going to be tiny.

Still, there might be the odd ones (like me) who would like to support multiple languages. When I created friendly/friendly-traceback, my hope was that many people might want to contribute to support languages other than French and English. I've received a few emails and saw a few forks with feeble attempts at supporting other languages ... but nothing significant. One third-party site (https://hackinscience.org) uses friendly-traceback and gives its users the option of selecting English or French.

So ... even though I raise the issue of supporting languages other than English, I don't seen any justification for complicating the API just to support other languages. As I mentioned before, an easy solution is to add custom names following an agreed upon scheme, such as __help__fr, __help_solution__fr, __help_link__fr if and when desired.

Finally: in friendly, I do not set the locale when a user changes the default language used by friendly as it might mess with other parameters (such as how number are displayed in some parts of the application being looked at, etc.).

[aroberge]

On Twitter, (https://twitter.com/pradyunsg/status/1450573310308364294) Pradyun Gedam posted this:

The context is for improved errors from Pip; see pypa/pip#10538

[pradyunsg]

Oh hey, that's me!

In case you're wondering what I'm hoping to do with pip, you'll wanna look at pypa/pip#10421 (comment).

[aroberge]

About __help__.

Python very often uses the same word for a function and an associated dunder, such as __next__ -> next(), __len__ -> len(), etc.

Since there is already a help() function available at the prompt, perhaps we should use something else, like __info__, __info_link__, __info__solution__, etc.

[willmcgugan]

I see why __help_solution__ may be dynamic, but couldn't you capture this use case with a property? If the solution is static text, it could be a simple string attribute. If it needs to inspect the traceback it could be implemented with @Property

I think if we have __help__ as an attribute, it would be surprising if __help_solution__ had to be a method. You may want __help__ to be dynamic as well. And I can see a use case for the __help_link__ being dynamic: it could add a search term based on the exception object.

re Languages, I like your scheme to expose the translations with the two letter codes.

I'm loathed to give up __help__ to be honest, but I see your point. __info__ doesn't appeal, since info could be anything. I can't think of anything better off the top of my head, but I agree in principle maybe we should avoid help.

[aroberge]

@Property would work.

As for __info__: it was the first word that came to mind, and I am not happy with it either.

[aroberge]

See also https://bugs.python.org/issue45607

[aroberge]

Something I forgot to mention before about custom exceptions.

Friendly/Friendly-traceback already supports third-party projects from defining custom exception handling. This is documented on https://friendly-traceback.github.io/docs/custom_errors.html with an example shown, and has been used by a third-party project currently set to be private. (I'm hoping they will make it public in the near future.) However, this approach requires the third-party project to have friendly-traceback as a dependency whreas the discussion here is for a more generic protocole that could be adopted independently of friendly-traceback.

[aroberge]

See also https://bugs.python.org/issue45990

[aroberge]

There is a new PEP (https://www.python.org/dev/peps/pep-0678/) about adding a field (__note__) to tracebacks. This field is meant to contain a string. If this string were to be written using Markdown syntax, perhaps all the information suggested above could be included, to be parsed downstream if needed.