Other exceptions in the standard library

[aroberge]

Some modules in the Python standard library have their own exceptions, such as decimal or turtle. After the basic exceptions are included, it might make sense to include such exceptions as these modules might be used by beginners. In particular, the turtle module would like benefit from having translations.

Please add your own examples from the standard library as a comment to this issue.

[aivarannamaa]

I just wanted to let you know that I intended to achieve similar goals in my Thonny IDE:

Currently the results can be considered proof-of-concept. I believe it makes sense to gather community efforts around a more general library (like friendly-traceback or pyta), which could be used by many tools.

Here are my efforts so far:

• https://files.realpython.com/media/Screenshot_2018-10-20_10.18.50.1f3845020f38.png
• https://github.com/thonny/thonny/issues/458
• https://github.com/thonny/thonny/issues/344
• https://github.com/thonny/thonny/blob/master/thonny/plugins/stdlib_error_helpers.py

Are you familiar with PyTA project?

[aroberge]

Thank you very much: I did not know that something like this was already included in Thonny. Parts of my plans included looking at the possibility of including friendly-tracebacks in Thonny - I understood it supported a plugin architecture and thought this to be the way to possibly include friendly-tracebacks, but I never looked closely.

I was not aware of PyTA - I will definitely need to look at what they are doing in more details.

I (obviously!) completely agree with your comment about focusing on a more generic library that could be used in many environments. This is why I started from the ground up with something that worked using a simple REPL, hoping that it would be used eventually by Thonny, Mu, etc.

While I have absolutely no personal need to go beyond providing explanations in English, I am determined to make something that is designed from the start with internationalization in mind, with all explanations available in as many human languages as possible.

Thank you very much for this additional information.
= = = Is there anything that I need to be aware that might prevent friendly-tracebacks from being usable in Thonny? Did you happen to see anything in the existing code that could be problematic and would need to be adjusted?

[aivarannamaa]

Here are some points to consider.

Number of possible causes.

I looked at analyze_syntax.py. If I understood correctly, it only proposes one possible cause of the error (the most likely). This doesn't prevent it from being usable in Thonny, but Thonny's assistant is able to list more causes allowing user to expand any of them to get more details. Thonny's implementation assigns weights for causes and may skip displaying lower weight causes if there exists a cause with big enough weight.

Verbosity

I like the idea of different verbosities. Thonny basically uses two levels of verbosity: initially only heading is displayed for each possible cause, but user can expand it to see detailed information.

Structure of the help content

For maximum flexibility, Thonny would like to receive the help content in structured form. Currently the GUI part gets something like this as input:

{
    'intro' : 'General explanation of the error message itself',
    'possible_causes' : [
        {
            'title' : 'eg. Did you misspell the variable?', 
            'text' : 'longer text, may contain several paragraphs',
            'weight' : 3 // how likely this cause is
        }, 
        { 
            ...
        }
    ]
}

I've created a simple reStructuredText renderer, so Thonny could make use of some simple formatting inside the longer explanation field. Some simple XHTML (eg. with <code>, <b>, etc. would be fine as well).

[aivarannamaa]

I was not aware of PyTA - I will definitely need to look at what they are doing in more details.

It looks like at the moment they only do static code analysis, ie. their goal is complementary to friendly-traceback's.

[aivarannamaa]

BTW, have you considered applying for PSF support for this work? See http://pyfound.blogspot.com/2019/04/update-on-python-in-education-proposal.html

[aroberge]

Yes, I am aware of the potential support from the PSF. I submitted https://github.com/aroberge/avantpy/blob/master/psf/idea.md during the "request for idea phase". Soon after, I decided to actually put together all the little bits of code I had done related to AvantPy and push the project further. After a while, I realized that what is now Friendly-tracebacks should probably be carved out and become a project of its own (to be used later by AvantPy). I do plan to submit something to the PSF - but I am not planning to request any funding for myself.

[aroberge]

Regarding the structure of the help content and weight to likely errors: this is something I will have to think carefully about. I definitely do see the value in having something like this... I am worried however about having something heavily predicated on using "nice/powerful" formatting tools: friendly traceback is currently usable from a standard REPL as can be seen here: https://aroberge.github.io/friendly-traceback-docs/docs/html/design.html#verbosity In this type of setting, where all the information is displayed all at once, with no "+" to click to expand, I think it would be counterproductive to present a "wall of text" with many different possible cause offered - hence the idea of trying to offer a single most likely cause for the error.

One goal I have for Friendly-traceback is to have it designed as a way for students to learn to decipher normal Python tracebacks and not be scared by them. For this to work, I could be wrong but I think it is important to retain some of the "look and feel" of normal Python tracebacks.

However, I am well aware that I am basing my design decisions on "gut feelings" with no feedback from actual students whereas Thonny has certainly benefited greatly from such feedback.

[ntoll]

Hello folks! It's great to see this conversation happening... I love this sort of thing unfolding.

My 2c... ;-)

I'm -1 on formatting and +1 on working as plain text via stdout because this gives maximum flexibility and many tools can then benefit from all the work being done.

I like the idea of suggesting a single most likely error (thus avoiding a wall of text), but I also like the idea of a more nuanced "but it could also be..." approach. I'm not sure what the best way to bring these two approaches together... perhaps there could be a URL at the end of the traceback pointing at more detailed docs for the specific problem? Such more-detailed-docs in and of themselves would be a really useful resource, and if we can get the community on board to help write them, we're almost at a StackOverflow-ish modus-operandi. I believe it's important that folks learn the all-knowing-solitary-genius stereotype of a computer programmer is fake: experienced developers need to look things up all the time (and we'd be helping learners realise this). [NB this is a raw thought requiring refinement].

I love the idea of things looking like Python's own tracebacks. The feedback I've had from teachers about Mu suggests that they like the "it's like the real thing, but simpler/friendlier" approach since it acts as a stepping stone to the eventual goal of Python fluency. Being able to decypher tracebacks is definitely a skill to be learned and one my own teaching experience often bumps up against -- many of the teachers I've worked with admit that they only see something like:

...when presented with a traceback. Furthermore, they also admit they don't want to appear as if they don't know what they're doing when put in a situation where a kid is asking, "my code broke, what should I do now?". The friendly-tracebacks approach is, I believe, a really useful pedagogical tool for both teachers and learners. (As in, the answer to the kid's question is probably, "I don't know, but let's look at what the traceback says...").

As always, the usual caveats about raw thoughts needing refinement apply. All feedback, constructive critique and ideas most welcome too.

Once again, it feels great to see this sort of conversation happening..!

[aroberge]

I've updated the design document (https://aroberge.github.io/friendly-traceback-docs/docs/html/design.html) to incorporate some ideas mentioned here. I'll likely need to revisit this document again soon to incorporate more feedback - including some received previously on what Exceptions should be covered, etc.

Regarding the formatted vs plain text: I think that both can be accommodated. Just like it is currently possible to change the output from sys.stderr used by default to some other custom stream, it might be doable to have the information processed internally in some "structured form" and output, by default, as simple nearly unformatted text as it is currently done. However, some other program could replace the "plain text formatter" by its own.

That being said, I think I need to focus on the short term on adding more cases covered by Friendly traceback so that it could be useful enough to be used by test groups that would provide feedback. That's what I was planning to do today, but the information provided on Thonny (and PyTA) was too good to ignore.

[ntoll]

:+1: :smile:

[aivarannamaa]

First, I definitely agree that stdout is useful medium for presenting such information and I see how it brings along different requirements compared to GUI tools. I was just hoping that the ability to get all possible causes from a lower level API wouldn't complicate the library design too much. This way the GUI-s and CLI-s can present different amount of information. I also agree that presenting single most likely cause in CLI may be the best option (unless two causes are equally probable).

About the structuredness of the help text -- it is not a strong requirement for Thonny. Separate title and body would be convenient, but I don't mind showing the first line of the text initially and rest of the text when the user clicks "+"-mark. Also the formatting markup -- nice to have from Thonny's perspective (and easy to strip in CLI context) but not too important.

About the weights of the causes -- these may be useful even when only single cause is shown to the user. For example, in case of a NameError, the relative likelihood of a misspelling and a missing import can change depending whether the bad name looks like another name in the code or is defined in a widely used module. In other words dynamically calculated weights may give better results than statically ordering possible causes.

I agree that the tool should not hide the real life from the user (although sometimes I'd rather try to change the real life instead of offering help for coping with it). That's why I left the real tracebacks intact in Thonny and presented error interpretation in a separate part of the screen. I'm not sure whether this helps or hinders user's ability and motivation for learning to decypher tracebacks ... Anyway, I think we should not confuse two topics here -- understanding tracebacks in general and being able to see possible causes in the specific error condition. Thonny's Assistant is only (or mostly) concerned with the latter and I'd say the latter is the hard part.

[aivarannamaa]

Another thing to consider -- who are the users we are targetting? "Beginners" is definitely too broad...

• Is Python their first programming language?
• Do they want to or have to learn programming?

My teaching experience comes from university setting and MOOC-s, where people usually want to learn programming and understand the underlying principles, even if it is very hard for them. They wouldn't mind reading through different possible causes for the error and they would find pride in getting rid of the training wheels. At the same time, year by year I see more people who agree to learn programming only as long as it is easy. They are usually more loud than the people who accept hard work :) Therefore I'm worrying about oversimplifying things to please this group.

[ntoll]

@aivarannamaa +1 on teasing out the meaning of "beginner".

For Mu it's definitely more a case of Python as a first (text based) programming language for folks who both want and (sometimes) have to learn (such as kids in UK schools).

I completely agree with you about oversimplification. This is why Mu attempts to ape "the real thing" in two ways: it's simple to facilitate accessibility to learning but without hiding the fact that, you know, coding requires effort and can be hard. :-) Programming isn't easy... we'd be doing learners a disservice if we're hiding this fact. I speak about this in my PyCon talk from last year's education summit, the URL of which I don't have right now.... (easy to Google though).

[aroberge]

@aivarannamaa Please see issue #10

I have implemented a simple dict-based structure for traceback information. This is simply based on what existed previously in friendly-traceback, which means identifying a unique cause for a given exception unlike what is done in Thonny. In theory, it should be possible to extend the information obtained from a traceback and go beyond what I am currently doing.

[aivarannamaa]

For UnboundLocalError this structure seems sufficient. I'm still not sure whether bringing out single possible cause is sufficient in all cases.

Anyway, it's probably too early to expect final data structures and API-s -- we'll see it more clearly when more exception explainers get implemented.

[aivarannamaa]

It occurred to me that even UnboundLocalError may be caused by different mistakes. Let's consider this program:

def sum_numbers(numbers):
    totalSum = 0 # note the spelling!

    for x in numbers:
        total_sum += x

    return total_sum

total_sum = sum_numbers([1,2,3])
print(total_sum)

Suggestion about adding a global to the program probably just confuses the learner.

Even if we could always correctly predict the correct suggestion, it may be useful to present more options so that the user is forced nudged to think about their specific situation and what they want to achieve.

[aroberge]

@aivarannamaa I am torn:

On the one hand, I most definitely see the value of presenting more options and have users think about their specific situation, as you suggest and as is done in Thonny. On the other hand, if the options presented are not leading to the right solution [1] , I think this might confuse the users, most of whom would have difficulty "thinking outside of the box" and only consider the suggestions offered since they most often would be "right".

Perhaps, the way to go forward is as follows: friendly-traceback attempts to identify as many possible cause as it can, like Thonny does, with a relevance factor. In the default mode (e.g. in an REPL), it only suggest the most likely cause of error. However, programs like Thonny that can present the information in better ways could use the full information available from friendly-traceback. So, the idea of considering more than one cause is definitely worth thinking about. However, for now, I think I will focus trying to include as many examples as possible with looking at only including the "most likely cause". Once I have included at least all the examples that can be dealt with by Thonny, I might be in a better position to see how I could incorporate multiple causes in a useful way.

Side note: I put the documentation in a separate repository and have significantly changed the design document, including some information about Thonny, and updated the site just a few minutes ago: https://aroberge.github.io/friendly-traceback-docs/docs/html/design.html

[1] For example, I would never have thought of the example you gave and would definitely not have included it as a choice.

[aivarannamaa]

Perhaps, the way to go forward is as follows: friendly-traceback attempts to identify as many possible cause as it can, like Thonny does, with a relevance factor. In the default mode (e.g. in an REPL), it only suggest the most likely cause of error. However, programs like Thonny that can present the information in better ways could use the full information available from friendly-traceback.

Sounds good!

[jharris1993]

Greetings!

Forgive my putting in my own two cents - I am hoping that a bit of "gut-level" feedback from someone who doesn't necessarily eat, drink, sleep, and breathe programming / Python programming might be useful.

First, though not a professional programmer, I do have at least some familiarity with programming.

Second, my real "hot button" is the user interface and how effectively a software package interacts with its users. During a long and winding career as a Software QA maven, usability and the UI were my main emphasis.

I'm assuming that the target audience for something like this is either rank beginners, or people like me, who - though not raw recruits - may not be God level programmers in the language in question.

Based on these criteria - providing the best, most relevant and effective information possible - my vote goes to the "Thonny Assistant" presentation.

1. It leaves the original error messages intact.
2. It provides a contextual analysis of what the problem might be, and what might have caused it.
3. It provides a range of possibilities based on the error message(s) shown. I like this much better than a simple "do this!" and hope it works.

It's my own humble opinion that a presentation like this provides the maximum amount of useful information in the smallest amount of space and would be the most effective way of guiding the student.

What say ye?

Jim "JR"

[aroberge]

@jharris1993 I agree with you. The issue you are commenting about was created at the very beginning of this project - which, in spite of a fair bit of progress, is still in its enfancy. Since then, a fair bit has happend and now Thonny can make use of friendly-traceback; see https://aroberge.github.io/friendly-traceback-docs/docs/html/thonny.html if you have not seen it already.

Friendly-traceback is intended to be a "low level, UI agnostic" diagnostic tool that provide information (available in many human languages) which can be used by editors such as Thonny and Mu.

[aroberge]

Closing this issue as the discussion has ended many months ago.

Individual items discussed here can be reopened as separate issues whenever needed.