Friday, March 05, 2021

Friendly-traceback will have a new name

tl; dr: I plan to change the name from friendly_traceback to friendly.

 When I started working on Friendly-traceback, I had a simple goal in mind:

Given an error message in a Python traceback, parse it and reformulate it into something easier to understand by beginners and that could be easily translated into languages other than English.

A secondary goal was to help users learn how to decipher a normal Python traceback and use the information provided by Python to understand what went wrong and how to fix it. 

Early on, I quickly realised that this would not be helpful when users are faced with arguably the most frustrating error message of them all: 

SyntaxError: invalid syntax

Encouraged by early adopters, I then began a quest to go much beyond simply interpreting a given error message, and trying to find a more specific cause of a given traceback. As Friendly-traceback was able to provide more and more information to users, I was faced with the realisation that too much information presented all at once could be counter-productive. Thus, it was broken down and could be made available in a console by asking what(), where(), why(), etc. If Friendly-traceback does not recognize a given error message, one can now simply type www() [name subject to change] and an Internet search for that specific message will be done using the default web browser.

By default, Friendly-traceback uses a custom exception hook to replace sys.excepthook: this definitely works with a standard Python interpreter. However, it does not work with IPython, Jupyter notebooks, IDLE (at least, not for Python 3.9 and older), etc.  So, custom modules now exist and users have to write:

  • from friendly_traceback.idle import ...
  • from friendly_traceback.jupyter import ...
  • from friendly_traceback.ipython import ...
  • from import ...
  • from friendly_traceback import ...  # generic case
To run a program from a terminal requires to write:

python -m friendly_traceback [additional options]

All of these are rather long to type ...

In addition to tracebacks, I have been thinking of including Python warnings, and in particular SyntaxWarnings

Along the same lines, when using the "friendly" console, I have added some exprimental warnings, such as those shown below.

I do not know if these warnings will be part of future versions of Friendly-traceback. What I do know, is that I want to consider incorporating things other than traceback that might be useful to beginners and/or to non-English speakers.

Back to the name change.  I have typed "friendly_traceback" many, many times.  It is long and annoying to type. When I work at a console, I often do:

import friendly_traceback as ft

and proceed from there.

I suspect that not too many potential users would be fond of friendly_traceback as a name. Furthermore, I wonder how convenient it is to type a name with an underscore character when using a non-English keyboard. Finally, whenever I write about Friendly-traceback, it is an hyphen that is used between the two names, and not an underscore character: one more possible source of confusion.

For all these reasons, I plan to soon change the name to be simply "friendly". This will almost certainly be done as the version number will increase from 0.2.xy to 0.3.0 ... which is going to happen "soon".

Such a name change will mean a major editing job to the extensive documentation which currently includes 76 screenshots, most of which have "friendly_traceback" in them. This means that they will all have to be redone. Of course, the most important work to be done will be changing the source code itself; however, this should be fairly easy to do with a global search/replace.

No comments: