[TynesideLUG] Fwd: [Better developers] Friendly

Mon Aug 28 10:03:46 UTC 2023

Hi,

I don't know if anyone here is learning Python but this email I'm
forwarding might prove useful...

BW,

Ian

---------- Forwarded message ---------
From: Reuven M. Lerner <reuven at lerner.co.il>
Date: Mon, 28 Aug 2023 at 11:00
Subject: [Better developers] Friendly
To: <ian.bruntlett at gmail.com>

*Was this copy of Better Developers forwarded to you? You can always
subscribe for free at https://BetterDevelopersWeekly.com!*
------------------------------
Let's say that you're new to Python, and you do something like this:

    x = 10
    y = '20'

    print(x+y)

You will, of course, get an exception -- on my computer, running 3.10, I
get:

    TypeError: unsupported operand type(s) for +: 'int' and 'str'

If you're experienced with Python, then you see this exception, and likely
understand that this is what happens when you try to use the + operator on
two types that can't be added. Here, we've specifically tried to add
together an integer and a string, which won't work.

But newcomers to Python see this and are confused: What kind of error is
this? What does it mean? What did I do wrong? And most importantly, how can
I fix it?

This week, I want to introduce you to "friendly," an amazing package (
https://friendly-traceback.github.io/docs/) that I've been using off and on
with my students for the last few years, and which has been improving
rapidly, thanks to the work of André Roberge, a Canadian teacher and
physicist. Friendly (also known as "friendy-traceback") looks at the errors
you encounter in a Python program, and translates them into language that
is easier to understand, and easier to act upon, than Python's defaults.

After installing "friendly" from PyPI, I started up my Python interactive
shell, and wrote the following:

    >>> import friendly
    >>> friendly.start_console()

This starts a new, colorized console within the Python interactive shell,
looking similar to IPython and Jupyter, with its numbered input prompts.
But then the real magic begins:

    >>> x = 10
    >>> y = '20'
    >>> print(x+y)

Once again, I get our exception. But now, immediately following the
exception, I get the following message:

    Did you forget to convert the string y into an integer (int)?

This is the genius behind friendly: It looks at the exception you got,
figures out what the most likely reason is for the error you got, and then
gives you practical, non-judgmental advice. For example:

    >>> t = (10,20, 30)    # define a tuple
    >>> t[0] = '!'

The official Python exception says:

    TypeError: 'tuple' object does not support item assignment

Friendly adds to this: Did you mean to use a list?  And of course, the odds
are good that someone who is trying to assign to a tuple really should be
using a list.  This difference is far from obvious to Python newcomers,
even if it's obvious to old hands. And indeed, that's why it's nice to have
friendly's help.

The most recent versions of Python have included better error messages, so
if you are you using "friendly", you might get a doubled message:

    >>> t = (10, 20, 30)
    >>> t.cout(10)

Python writes:

    AttributeError: 'tuple' object has no attribute 'cout'. Did you
mean: 'count'?

And immediately after, friendly writes:

    Did you mean count?

If you know that you'll want to run the friendly console when you start
your REPL, you can do so via command-line arguments:

    python -im friendly

Not only will this give you all of the benefits we saw before, but it also
installs three useful functions:

   - why, which explains what caused the error, and gives some suggestions
   - where, which shows a nicer traceback than Python normally displays
   - what, which tells you what the exception typically means

You can combine all of these by calling "explain", which produces fuller
output, including the values of all relevant variables.

Of course, most Python problems occur when programs are running, not when
they're being run in the interactive console.  I put the above code into a
file (myprog.py), and then ran it:

    [main ✗ ~/Better Developers]$ python3  myprog.py
    Traceback (most recent call last):
      File "/Users/reuven/Better Developers/myprog.py", line 6, in <module>
        print(x+y)
    TypeError: unsupported operand type(s) for +: 'int' and 'str'

Not surprisingly, I saw our exception again. However, if I load "friendly"
via the "-m" command-line argument, it'll spring into action, printing the
output from "explain":

    TypeError: unsupported operand type(s) for +: 'int' and 'str'

    Did you forget to convert the string `y` into an integer (`int`)?

    A `TypeError` is usually caused by trying
    to combine two incompatible types of objects,
    by calling a function with the wrong type of object,
    or by trying to do an operation not allowed on a given type of object.

    You tried to add two incompatible types of objects:
    an integer (`int`) and a string (`str`).
    Perhaps you forgot to convert the string `y` into an integer (`int`).

    Exception raised on line 6 of file HOME:/Better Developers/myprog.py.

       1: #!/usr/bin/env python3
       3: x = 10
       4: y = '20'
    -->6: print(x+y)
                ^^^

            x:  10
            y:  '20'

My response to this? Wow. It's a great, patient explanation. The first line
is probably enough for most people, but if it isn't, the longer explanation
will help them. I'm not naive enough to think that this is enough for all
people, all of the time, but these sorts of explanations do cover at least
half of the problems newcomers to Python encounter, in my experience.

As you might remember, I'm a big fan of Jupyter, using it when I teach.
Fortunately, friendly has a mode that works with Jupyter! From within a
notebook, you can say:

    from friendly.jupyter import Friendly

This not only loads up friendly, but gives it special Jupyter-specific
functionality: When you encounter an error, you won't see the full output
from "explain" (which we saw earlier). Rather, you'll have three buttons in
the Jupyter page, labeled "why", "where", and "what". Clicking on any of
those buttons reveals the explanatory text that calling those functions
would otherwise have done.

Friendly isn't meant for experienced developers, which means that you (and
I) are probably not the right audience for using it. But if you teach, or
if you're working with someone who is new to Python, then I strongly
recommend you show them "friendly". I think they'll really benefit from it.

Until next time,

Reuven

Did someone forward this newsletter to you? Get your own copy at
https://BetterDevelopersWeekly.com/
<https://t.dripemail2.com/c/eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJkZXRvdXIiLCJpc3MiOiJtb25vbGl0aCIsInN1YiI6ImRldG91cl9saW5rIiwiaWF0IjoxNjkzMTk5MzU4LCJuYmYiOjE2OTMxOTkzNTgsImFjY291bnRfaWQiOiI2MTY4MjE4IiwiZGVsaXZlcnlfaWQiOiJsMmxzYTloZTdzN3I0eTJzMWtiYyIsInVybCI6Imh0dHBzOi8vQmV0dGVyRGV2ZWxvcGVyc1dlZWtseS5jb20vP19fcz10MXdzdHNoaHRwY3lwbWFxYnl0cyJ9.nlCHgh1mnwopxhMYdj8YP-VePSryFJtRf2R64bfeIyk>
.

To make sure that these messages get to your inbox (and aren't tagged as
junk or spam), please add reuven at lerner.co.il to your address book, or
whitelist it.

To select which messages you get from me, or just unsubscribe from all of
my content, click here:
https://www.getdrip.com/subscribers/t1wstshhtpcypmaqbyts/edit

I produce all of this content myself, at my home office: 14 Migdal Oz
Street, Apt. #1, Modi'in 7170334 Israel

-- 
-- ACCU - Professionalism in programming - http://www.accu.org
-- My writing - https://sites.google.com/site/ianbruntlett/
-- Free Software page -
https://github.com/ian-bruntlett/TECH-Manuals/blob/main/tm-free-software.md