Invent with Python

Fractal Art Maker for Python Turtle.py

2025-09-22T10:00:00-04:00

Fractals are beautiful, self-similar patterns that can be created by a computer from very simple rules. My Fractal Art Maker package makes it easy to use Python's turtle.py package to draw your own. You don't need to know recursion, but you can read my free book, The Recursive Book of Recursion if you're curious. If you want to learn how to draw pictures with Python code, I also have The Simple Turtle Tutorial.

Installation and Quick Start

The package and documentation is hosted on PyPI and the git repo is also available. You can install it by running pip install fractalartmaker on Windows or pip3 install fractalartmaker on macOS/Linux. You can try this code out in the interactive shell:

import fractalartmaker as fam
fam.draw_fractal(my_square_drawing_function, 100, [{'size': 0.96, 'y': 0.5, 'angle': 11}], max_depth=50)

If you run the package as a module by running python3 -m fractalartmaker, you'll see several demo fractals.

How to Draw Fractals with FAM

The main function we'll use in the fam module is fam.draw_fractal(). We'll need to pass it a drawing function, which is a function that takes a size argument and draws a simple shape. Here's the code for square() function that draws a square:

def my_square_drawing_function(size):
    # Move to the top-right corner before drawing:
    turtle.penup()
    turtle.forward(size // 2)
    turtle.left(90)
    turtle.forward(size // 2)
    turtle.left(180)
    turtle.pendown()

    # Draw a square with sides of length `size`:
    for i in range(4):  # Draw four lines.
        turtle.forward(size)
        turtle.right(90)

On its own, this function will just draw a square of a given size. (Note that this function isn't recursive; it just draws one square.) But the fam.draw_fractal() function can use functions like this to create fractals.

To make a fractal, call fam.draw_fractal() and pass it this drawing function, a starting size (let's go with 100), and a list of recursion specification dictionaries. By recursion specification dictionary, I mean a list of dictionaries with (optional) keys 'size', 'x', 'y', and 'angle'. I'll explain what these keys do later, but try calling this:

fam.draw_fractal(my_square_drawing_function, 100, [{'size': 0.96, 'y': 0.5, 'angle': 11}])

This draws a fractal similar to the fam.demo_horn() fractal. The 100 is the initial size for the first square to draw. The list of recursion specification dictionaries [{'size': 0.96, 'y': 0.5, 'angle': 11}] has one dictionary in it. This means for each shape drawn with the drawing function, we will draw one more recursive shape. The new square is drawn at 96% the original size (because the 'size' key is 0.96), located 50% of the size above the square (because the 'y' key is 0.5), after rotating it counterclockwise by 11 degrees (because the 'angle' is set to 11).

By default, fam.draw_fractal() only goes 8 recursive levels deep. You can change this by passing a max_depth argument.

fam.draw_fractal(my_square_drawing_function, 100, [{'size': 0.96, 'y': 0.5, 'angle': 11}], max_depth=50)

Let's make each square draw two squares by putting a second recursion specification dictionary in the list. Because each square will draw two squares (and both of those two squares will draw two squares each, and so on and so on), be sure to set max_depth to something small like it's default 8. Otherwise, the exponentially large amount of drawing will slow your program down to a crawl.

Let's make the second recursion specification dictionary the same as the first, but it's 'angle' key is -11 instead of 11. This will make it veer off clockwise by 11 degrees instead of the normal counterclockwise:

fam.draw_fractal(my_square_drawing_function, 100, [{'size': 0.96, 'y': 0.5, 'angle': 11}, {'size': 0.96, 'y': 0.5, 'angle': -11}], max_depth=8)

As you can see, it doesn't take much to fill up the window with too many shapes. The key to making aesthetically pleasing fractals is to take a light touch and spend a lot of time experimenting. For example, we could pass a list of three recursion specification dictionaries to draw squares in three of the corners of the parent square:

fam.draw_fractal(my_square_drawing_function, 350,
    [{'size': 0.5, 'x': -0.5, 'y': 0.5},
     {'size': 0.5, 'x': 0.5, 'y': 0.5},
     {'size': 0.5, 'x': -0.5, 'y': -0.5}], max_depth=4)

If we increase the max depth to 10, we can see a new pattern emerge:

fam.draw_fractal(my_square_drawing_function, 350,
    [{'size': 0.5, 'x': -0.5, 'y': 0.5},
     {'size': 0.5, 'x': 0.5, 'y': 0.5},
     {'size': 0.5, 'x': -0.5, 'y': -0.5}], max_depth=10)

The fractalartmaker module comes with a fam.square and fam.triangle drawing functions that you can play with. Also take a look at the code for the demo functions inside the __init__.py file for more ideas. Check out the rest of this documentation for advanced tips. Good luck!

NOTE: Calling fam.draw_fractal() automatically calls turtle.reset() to clear the window and move the turtle cursor back to 0, 0. If you don't want this behavior, pass reset=False to fam.draw_fractal()

NOTE: To free you from having to import the turtle module yourself, you can call most turtle functions from the fam module: fam.reset(), fam.update(), and so on.

Gallery of Demo Fractals

def demo_four_corners(size=350, max_depth=5, **kwargs):
    # Four Corners:
    if 'colors' not in kwargs:
        kwargs['colors'] = (('black', 'white'), ('black', 'gray'))
    draw_fractal(square, size,
        [{'size': 0.5, 'x': -0.5, 'y': 0.5},
         {'size': 0.5, 'x': 0.5, 'y': 0.5},
         {'size': 0.5, 'x': -0.5, 'y': -0.5},
         {'size': 0.5, 'x': 0.5, 'y': -0.5}], max_depth=max_depth, **kwargs)

def demo_spiral_squares(size=600, max_depth=50, **kwargs):
    # Spiral Squares:
    if 'colors' not in kwargs:
        kwargs['colors'] = (('black', 'white'), ('black', 'gray'))
    draw_fractal(square, size, [{'size': 0.95,
        'angle': 7}], max_depth=max_depth, **kwargs)

def demo_double_spiral_squares(size=600, **kwargs):
    # Double Spiral Squares:
    if 'colors' not in kwargs:
        kwargs['colors'] = (('black', 'white'), ('black', 'gray'))
    draw_fractal(square, 600,
        [{'size': 0.8, 'y': 0.1, 'angle': -10},
         {'size': 0.8, 'y': -0.1, 'angle': 10}], **kwargs)

def demo_triangle_spiral(size=20, max_depth=80, **kwargs):
    # Triangle Spiral:
    draw_fractal(triangle, size,
        [{'size': 1.05, 'angle': 7}], max_depth=max_depth, **kwargs)

def demo_glider(size=600, **kwargs):
    # Conway's Game of Life Glider:
    if 'colors' not in kwargs:
        kwargs['colors'] = (('black', 'white'), ('black', 'gray'))
    third = 1 / 3
    draw_fractal(square, 600,
        [{'size': third, 'y': third},
         {'size': third, 'x': third},
         {'size': third, 'x': third, 'y': -third},
         {'size': third, 'y': -third},
         {'size': third, 'x': -third, 'y': -third}], **kwargs)

def demo_sierpinski_triangle(size=600, **kwargs):
    # Sierpinski Triangle:
    toMid = math.sqrt(3) / 6
    draw_fractal(triangle, 600,
        [{'size': 0.5, 'y': toMid, 'angle': 0},
         {'size': 0.5, 'y': toMid, 'angle': 120},
         {'size': 0.5, 'y': toMid, 'angle': 240}], **kwargs)

def demo_wave(size=280, **kwargs):
    # Wave:
    draw_fractal(triangle, size,
        [{'size': 0.5, 'x': -0.5, 'y': 0.5},
         {'size': 0.3, 'x': 0.5, 'y': 0.5},
         {'size': 0.5, 'y': -0.7, 'angle': 15}], **kwargs)

def demo_horn(size=100, max_depth=100, **kwargs):
    # Horn:
    if 'colors' not in kwargs:
        kwargs['colors'] = (('black', 'white'), ('black', 'gray'))
    draw_fractal(square, size,
        [{'size': 0.96, 'y': 0.5, 'angle': 11}], max_depth=max_depth, **kwargs)

def demo_snowflake(size=200, **kwargs):
    # Snowflake:
    if 'colors' not in kwargs:
        kwargs['colors'] = (('black', 'white'), ('black', 'gray'))
    draw_fractal(square, size,
        [{'x': math.cos(0 * math.pi / 180),
          'y': math.sin(0 * math.pi / 180), 'size': 0.4},
         {'x': math.cos(72 * math.pi / 180),
          'y': math.sin(72 * math.pi / 180), 'size': 0.4},
         {'x': math.cos(144 * math.pi / 180),
          'y': math.sin(144 * math.pi / 180), 'size': 0.4},
         {'x': math.cos(216 * math.pi / 180),
          'y': math.sin(216 * math.pi / 180), 'size': 0.4},
         {'x': math.cos(288 * math.pi / 180),
          'y': math.sin(288 * math.pi / 180), 'size': 0.4}], **kwargs)

Advanced Features of FAM's Shape-Drawing Functions

All shape-drawing functions are passed a size argument. We can make the white-and-gray alternating colors by adding the optional depth parameter to our drawing function. The draw_fractal() function will pass the recursion depth (1 for the first depth level, 2 for the next, and so on) to the drawing function. In the following square_alternating_white_gray() drawing function, the fill color for the square is set to white or gray depending on the depth argument:

def square_alternating_white_gray(size, depth):
    # Move to the top-right corner before drawing:
    turtle.penup()
    turtle.forward(size // 2)
    turtle.left(90)
    turtle.forward(size // 2)
    turtle.left(180)
    turtle.pendown()

    # Set fill color based on recursion depth level:
    if depth % 2 == 0:
        turtle.fillcolor('white')
    else:
        turtle.fillcolor('gray')

    # Draw a square:
    turtle.begin_fill()
    for i in range(4):  # Draw four lines.
        turtle.forward(size)
        turtle.right(90)
    turtle.end_fill()

draw_fractal(square_alternating_white_gray, 300,
    [{'size': 0.5, 'x': -0.5, 'y': 0.5},
    {'size': 0.5, 'x': 0.5, 'y': 0.5},], max_depth=5)

You can also pass any custom keyword argument to draw_fractal(), and it will be forwarded to the drawing function. For example, I set up square_random_fill() draw function with a custom_fill_colors parameter. If you pass custom_fill_colors=['blue', 'red', 'yellow', 'black', 'white'] to draw_fractal(), this list will be forwarded to the draw function. Note that if you pass a custom argument like custom_fill_colors to draw_fractal(), the drawing function must have a parameter named custom_fill_colors.

import random

def square_random_fill(size, custom_fill_colors):
    # Move to the top-right corner before drawing:
    turtle.penup()
    turtle.forward(size // 2)
    turtle.left(90)
    turtle.forward(size // 2)
    turtle.left(180)
    turtle.pendown()

    # Set fill color randomly:
    turtle.fillcolor(random.choice(custom_fill_colors))

    # Draw a square:
    turtle.begin_fill()
    for i in range(4):  # Draw four lines.
        turtle.forward(size)
        turtle.right(90)
    turtle.end_fill()

draw_fractal(square_random_fill, 300,
    [{'size': 0.5, 'x': -0.5, 'y': 0.5},
    {'size': 0.5, 'x': 0.5, 'y': 0.5},], max_depth=5, custom_fill_colors=['blue', 'red', 'yellow', 'black', 'white'])

Turtle Colors and RGB App

2025-09-18T10:00:00-04:00

I've been working on turtle-related projects and I needed a simple, interactive, single-file Python program to explain RGB color values. I wrote this one up as part of my work writing a Simple Turtle Tutorial written in Wikipedia-style Simple English so it can be translated to non-English languages. You can download the app from PyPI and look at its code on its git repo

The app has three sliders for the amount of red, blue, and green for the window's background color. The RGB values are presented under the sliders for the 0.0 to 1.0 scale, 0 to 255 scale, and hexadecimal 0x00 to 0xFF scale. You can drag the sliders or click on the slider lines directly. There are also 14 preset color buttons along the top to click on.

This is written as a single-file Python program using only the standard library. Unlike similar web apps, it's simple and doesn't have ads. If you have Python installed, you can run this program and learn about RGB values.

Install with python -m pip install turtlecolors on Windows or python3 -m pip install turtlecolors on macOS/Linux.

Run with python -m turtlecolors on Windows or python3 -m turtlecolors on macOS/Linux. Or run the code import turtlecolors;turtlecolors.main()

When the program first runs, it also prints out the color name strings that Python's turtle module uses. I've also compiled a complete list of valid and tested Python tkinter color names.

Automate the Boring Stuff Workbook Now Available for Preorder

2025-09-17T10:00:00-04:00

"This workbook transforms Al Sweigart’s best-selling guide from a reading experience into a coding experience. Following Automate the Boring Stuff with Python chapter by chapter, this workbook will help you turn concepts into muscle memory through carefully designed exercises, projects, and real Python scripts."

Preorder links: Direct From the Publisher (preferred) | Amazon | Barnes and Noble | Bookshop.org | Powell's | Kobo | Thriftbooks | Goodreads

Every concept from Automate is reinforced through carefully sequenced questions, exercises, and projects that help you think like a programmer and prove to yourself that you really get it.

At the end of each chapter, you’ll tackle miniprojects that bring everything together. Whether you’re renaming files, scraping websites, converting text to speech, modifying spreadsheets, or sending emails, you’ll build scripts that do real work. Fun projects like image generators and word games are in the mix too, not just boring stuff.

Before/After Photo Alignment Web App

2025-09-16T10:00:00-04:00

I created a web app for aligning before/after photos. Ony of my hobbies is picking up litter, and I'll post before/after photos to the r/detrashed subreddit:

To get properly aligned photos, you have to take the photo from the same spot and at the same angle. I place a stick or soda can where I stood, and try to put some common object in a corner of the frame for both photos. Make sure the zoom amount is the same as well. Then, upload the before and after photo into the alignment web app:

Drag them over each other so that objects in the picture are more of less on top of each other:

Once they are more or less aligned, click the Crop Both Images button. The web app will crop them so they are more aligned. Here are some more examples from my trash picking:

I created this tool with Claude Sonnet 4, which surprisingly needed only a little editing to get it right. Portability was important, so I made this as a JavaScript web app. I was sure to specify that it needed to be a single-page web app with no dependencies. All processing takes place in the browser and, as a result, you can download the before-after-photo-alignment.html file and run it offline.

List of 87 Programming Ideas for Beginners

2025-09-15T10:20:00-04:00

After you've learned the basic concepts, the best way to improve your coding skills is to work on projects. You may not know enough to contribute to popular open source projects, but you can create small programs on your own. Here's a list of 81 projects suitable for beginners. They're short, can be done in any language, and don't require additional software library installation. These projects are drawn from my free books, The Big Book of Small Python Projects, Cracking Codes with Python, and Invent Your Own Computer Games with Python. Each program has a link to a sample Python implementation, but I encourage you to make it from scratch.

What you don't want to do is start on a large, ambitious project: it's frustrating to spend weeks on something that you never actually finish. You can learn a lot by instead working on several small, simple programs. There are plenty of terrible "1001 Programming Ideas" blog posts that copy/paste every idea from "flip a coin" programs to "make your own ChatGPT". My list is carefully curated to be achievable by beginners.

More importantly, these projects can all be done with just printing text to the screen and taking keyboard input. There are no graphics, GUIs, or web servers you need to set up. This list has games, simulations, puzzles, and digital art programs. These programs can be written in a few dozen or few hundred lines of code. I suggest trying to write them yourself from scratch, but you can also follow the links to working Python source code for each project.

I also produce a trailer video for the projects in The Big Book of Small Python Projects if you want a quick preview tour.

Bagels

Bagels is a deductive logic game where you must guess a 3-digit number. After each guess you are given clues: "Pico" means one digit is correct but in the wrong position, "Fermi" means one digit is correct and in the right position, and "Bagels" means no digit is correct.

For example, game play could look like this:

Guess #1:
> 123
Pico
Guess #2:
> 456
Bagels
Guess #3:
> 178
Pico Pico

--snip--

Guess #7:
> 791
Fermi Fermi
Guess #8:
> 701
You got it!

Birthday Paradox

The Birthday Paradox is the surprisingly high probability that two people will have the same birthday even in a small group of people. Even in a group as small as 23 people, there’s a 50 percent chance of a matching birthday. This program performs several probability experiments to determine the percentages for groups of different sizes.

You can find out more about the Birthday Paradox at https://en.wikipedia.org/wiki/Birthday_problem.

For example, when the program runs it could look like this:

How many birthdays shall I generate? (Max 100)
> 23
Here are 23 birthdays:
Oct 9, Sep 1, May 28, Jul 29, Feb 17, Jan 8, Aug 18, Feb 19, Dec 1, Jan 22,
May 16, Sep 25, Oct 6, May 6, May 26, Oct 11, Dec 19, Jun 28, Jul 29, Dec 6,
Nov 26, Aug 18, Mar 18
In this simulation, multiple people have a birthday on Jul 29
Generating 23 random birthdays 100,000 times...
Press Enter to begin...
Let's run another 100,000 simulations.
0 simulations run...
10000 simulations run...

--snip--

90000 simulations run...
100000 simulations run.
Out of 100,000 simulations of 23 people, there was a
matching birthday in that group 50955 times. This means
that 23 people have a 50.95 % chance of
having a matching birthday in their group.
That's probably more than you would think!

Bitmap Message

The Bitmap Message replaces the non-space characters in a multiline string with your own text message. For example, this multiline string:

   **************   *  *** **  *      ******************************
  ********************* ** ** *  * ****************************** *
 **      *****************       ******************************
          *************          **  * **** ** ************** *
           *********            *******   **************** * *
            ********           ***************************  *
   *        * **** ***         *************** ******  ** *
               ****  *         ***************   *** ***  *
                 ******         *************    **   **  *
                 ********        *************    *  ** ***
                   ********         ********          * *** ****
                   *********         ******  *        **** ** * **
                   *********         ****** * *           *** *   *
                     ******          ***** **             *****   *
                     *****            **** *            ********
                    *****             ****              *********
                    ****              **                 *******   *
                    ***                                       *    *
                    **     *                    *
....................................................................

...could be combined with the "message" string Hello! to produce this string:

Hello!Hello!Hello!Hello!Hello!Hello!Hello!Hello!Hello!Hello!Hello!He
   lo!Hello!Hello   l  !He lo  e      llo!Hello!Hello!Hello!Hello!He
  llo!Hello!Hello!Hello He lo H  l !Hello!Hello!Hello!Hello!Hello H
 el      lo!Hello!Hello!He       lo!Hello!Hello!Hello!Hello!Hel
          o!Hello!Hello          lo  e lo!H ll !Hello!Hello!H l
           !Hello!He            llo!Hel   Hello!Hello!Hell ! e
            Hello!He           ello!Hello!Hello!Hello!Hell  H
   l        H llo! ell         ello!Hello!Hell !Hello  el o
               lo!H  l         ello!Hello!Hell   ell !He  o
                 !Hello         llo!Hello!Hel    el   He  o
                 !Hello!H        lo!Hello!Hell    l  !H llo
                   ello!Hel         Hello!He          H llo Hell
                   ello!Hell         ello!H  l        Hell !H l o!
                   ello!Hell         ello!H l o           o!H l   H
                     lo!Hel          ello! el             o!Hel   H
                     lo!He            llo! e            llo!Hell
                    llo!H             llo!              llo!Hello
                    llo!              ll                 lo!Hell   e
                    llo                                       l    e
                    ll     l                    H
Hello!Hello!Hello!Hello!Hello!Hello!Hello!Hello!Hello!Hello!Hello!He

Blackjack

Blackjack, also known as 21, is a card game where players try to get as close to 21 points as possible without going over. The user plays against an AI blackjack dealer. (Email me if you are a VC who wants to invest in my blackjack AI. I'm in between banks right now, so make the checks out to "cash".)

For example, when the program runs it could look like this:

Money: 5000
How much do you bet? (1-5000, or QUIT)
> 400
Bet: 400

DEALER: ???
 ___   ___
|## | |2  |
|###| | ♥ |
|_##| |__2|

PLAYER: 17
 ___   ___
|K  | |7  |
| ♠ | | ♦ |
|__K| |__7|


(H)it, (S)tand, (D)ouble down
> h
You drew a 4 of ♦.

--snip--

DEALER: 18
 ___   ___   ___
|K  | |2  | |6  |
| ♦ | | ♥ | | ♠ |
|__K| |__2| |__6|

PLAYER: 21
 ___   ___   ___
|K  | |7  | |4  |
| ♠ | | ♦ | | ♦ |
|__K| |__7| |__4|

You won $400!

--snip--

Bouncing DVD Logo

The bouncing DVD logo! If you are of a certain age, you’ll remember those ancient technological devices called DVD players. When not playing DVDs, they would display a diagonally traveling DVD logo that bounced off the edges of the screen. This program simulates this colorful DVD logo by making it change direction each time it hits an edge. We’ll also keep track of how many times a logo hits a corner of the screen. This creates an interesting visual animation to look at, especially for the magical moment when a logo lines up perfectly with a corner.

The Bext package can print directly to XY coordinates on the screen. Bext also lets you print in different colors. Otherwise, you could do the trick of printing fifty or so \n newline characters to "clear" the screen before printing an updated screen of DVD logos.

For example, when the program runs it could look like this:

Caesar Cipher

The Caesar cipher is an ancient encryption algorithm that encrypts letters by shifting them over by a certain number of places in the alphabet. We call the length of shift the key. For example, if the key is 3, then A becomes D, B becomes E, C becomes F, and so on. To decrypt the message, you must shift the encrypted letters in the opposite direction. This program lets the user encrypt and decrypt messages according to this algorithm.

For example, when the program runs it could look like this:

Do you want to (e)ncrypt or (d)ecrypt?
> e
Please enter the key (0 to 25) to use.
> 4
Enter the message to encrypt.
> Meet me by the rose bushes tonight.
QIIX QI FC XLI VSWI FYWLIW XSRMKLX.

--snip--

Do you want to (e)ncrypt or (d)ecrypt?
> d
Please enter the key (0 to 26) to use.
> 4
Enter the message to decrypt.
> QIIX QI FC XLI VSWI FYWLIW XSRMKLX.
MEET ME BY THE ROSE BUSHES TONIGHT.

If you’d like to learn about ciphers and code breaking in general, you can read my book Cracking Codes with Python.

Caesar Hacker

This Caesar cipher hacking program can hack messages encrypted with the Caesar cipher even if you don’t know the key. There are only 26 possible keys for the Caesar cipher, so a computer can easily try all possible decryptions and display the results to the user. In cryptography, we call this technique a brute-force attack. You'll be able to reuse some of the code you wrote for the Caesar cipher program.

For example, when the program runs it could look like this:

Enter the encrypted Caesar cipher message to hack.
> QIIX QI FC XLI VSWI FYWLIW XSRMKLX.
Key #0: QIIX QI FC XLI VSWI FYWLIW XSRMKLX.
Key #1: PHHW PH EB WKH URVH EXVKHV WRQLJKW.
Key #2: OGGV OG DA VJG TQUG DWUJGU VQPKIJV.
Key #3: NFFU NF CZ UIF SPTF CVTIFT UPOJHIU.
Key #4: MEET ME BY THE ROSE BUSHES TONIGHT.
Key #5: LDDS LD AX SGD QNRD ATRGDR SNMHFGS.
Key #6: KCCR KC ZW RFC PMQC ZSQFCQ RMLGEFR.
--snip--

If you’d like to learn about ciphers and code breaking in general, you can read my book Cracking Codes with Python.

Calendar Maker

This calendar maker program generates printable text files of monthly calendars for the month and year you enter. Dates and calendars are a tricky topic in programming because there are so many different rules for determining the number of days in a month, which years are leap years, and which day of the week a particular date falls on. Fortunately, Python’s datetime module handles these details for you. This program focuses on generating the multiline string for the monthly calendar page. Other languages also have datetime and calendar packages. Consult the documentation for your language.

Enter the year for the calendar:
> 2029
Enter the month for the calendar, 1-12:
> 12
                                  December 2029
...Sunday.....Monday....Tuesday...Wednesday...Thursday....Friday....Saturday..
+----------+----------+----------+----------+----------+----------+----------+
|25        |26        |27        |28        |29        |30        | 1        |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
+----------+----------+----------+----------+----------+----------+----------+
| 2        | 3        | 4        | 5        | 6        | 7        | 8        |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
+----------+----------+----------+----------+----------+----------+----------+
| 9        |10        |11        |12        |13        |14        |15        |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
+----------+----------+----------+----------+----------+----------+----------+
|16        |17        |18        |19        |20        |21        |22        |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
+----------+----------+----------+----------+----------+----------+----------+
|23        |24        |25        |26        |27        |28        |29        |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
+----------+----------+----------+----------+----------+----------+----------+
|30        |31        | 1        | 2        | 3        | 4        | 5        |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
|          |          |          |          |          |          |          |
+----------+----------+----------+----------+----------+----------+----------+

Saved to calendar_2029_12.txt

Carrot in a Box

Carrot in a box is a simple and silly bluffing game for two human players. Each player has a box. One box has a carrot in it, and each player wants to have the carrot. The first player looks in their box and then tells the second player they either do or don’t have the carrot. The second player gets to decide whether to swap boxes or not.

I got the idea for this from a comedy sketch by 8 Out Of 10 Cats.

You can draw boxes and carrots using text characters:

   ___VV____
  |   VV    |
  |   VV    |
  |___||____|    __________
 /    ||   /|   /         /|
+---------+ |  +---------+ |
|   RED   | |  |   GOLD  | |
|   BOX   | /  |   BOX   | /
+---------+/   +---------+/

Your program should:

Ask the players for their names.
Explain the rules and show the two closed boxes to the players.
Ask the second player to close their eyes while the first player presses Enter to view the contents of their box, and then press Enter again to clear the screen.
Ask the second player if they want to swap boxes or not. The second player can ask the first player any question they want.
Reveal who has the box with the carrot in it.

For example, when the program runs it could look like this:

Human player 1, enter your name: Alice
Human player 2, enter your name: Bob
HERE ARE TWO BOXES:
  __________     __________
 /         /|   /         /|
+---------+ |  +---------+ |
|   RED   | |  |   GOLD  | |
|   BOX   | /  |   BOX   | /
+---------+/   +---------+/
   Alice           Bob

Alice, you have a RED box in front of you.
Bob, you have a GOLD box in front of you.
Press Enter to continue...
--snip--
When Bob has closed their eyes, press Enter...
Alice here is the inside of your box:

   ___VV____
  |   VV    |
  |   VV    |
  |___||____|    __________
 /    ||   /|   /         /|
+---------+ |  +---------+ |
|   RED   | |  |   GOLD  | |
|   BOX   | /  |   BOX   | /
+---------+/   +---------+/
 (carrot!)
   Alice           Bob
Press Enter to continue...
--snip--

Cho-Han

Cho-han is a dice game played in gambling houses of feudal Japan. Two six-sided dice are rolled in a cup, and gamblers must guess if the sum is even (cho) or odd (han). The house takes a small cut of all winnings. The simple random number generation and basic math used to determine odd or even sums make this project especially suitable for beginners.

For example, when the program runs it could look like this:

You have 5000 mon. How much do you bet? (or QUIT)
> 400
The dealer swirls the cup and you hear the rattle of dice.
The dealer slams the cup on the floor, still covering the
dice and asks for your bet.

    CHO (even) or HAN (odd)?
> cho
The dealer lifts the cup to reveal:
   GO - GO
     5 - 5
You won! You take 800 mon.
The house collects a 40 mon fee.
--snip--

You can find more details and a sample Python implementation on the book website.

Clickbait Headline Generator

Our website needs to trick people into looking at advertisements! But coming up with creative, original content is too hard. Luckily, with the clickbait headline generator, we can make a computer come up with millions of outrageous fake headlines. They’re all low quality, but readers don’t seem to mind. This program generates as many headlines as you need from a Mad Libs–style template.

For example, when the program runs it could look like this:

Our website needs to trick people into looking at ads!
Enter the number of clickbait headlines to generate:
> 1000
Big Companies Hate Him! See How This New York Cat Invented a Cheaper Robot
What Telephone Psychics Don't Want You To Know About Avocados
You Won't Believe What This North Carolina Shovel Found in Her Workplace
--snip--
14 Reasons Why Parents Are More Interesting Than You Think (Number 1 Will Surprise You!)
What Robots Don't Want You To Know About Cats
This Florida Telephone Psychic Didn't Think Robots Would Take Her Job. She Was Wrong.

Collatz Sequence

The Collatz sequence, also called the 3n + 1 problem, is the simplest impossible math problem. (But don’t worry, the program itself is easy enough for beginners.) From a starting number, n, follow three rules to get the next number in the sequence:

If n is even, the next number n is n / 2.
If n is odd, the next number n is n * 3 + 1.
If n is 1, stop. Otherwise, repeat.

It is generally thought, but so far not mathematically proven, that every starting number eventually terminates at 1. Write a program that takes a starting number from the user and prints the Collatz sequence from it.

For example, when the program runs it could look like this:

Enter a starting number (greater than 0) or QUIT:
> 26
26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1

--snip--

Enter a starting number (greater than 0) or QUIT:
> 27
27, 82, 41, 124, 62, 31, 94, 47, 142, 71, 214, 107, 322, 161, 484, 242, 121, 364, 182, 91, 274, 137, 412, 206, 103, 310, 155, 466, 233, 700, 350, 175, 526, 263, 790, 395, 1186, 593, 1780, 890, 445, 1336, 668, 334, 167, 502, 251, 754, 377, 1132, 566, 283, 850, 425, 1276, 638, 319, 958, 479, 1438, 719, 2158, 1079, 3238, 1619, 4858, 2429, 7288, 3644, 1822, 911, 2734, 1367, 4102, 2051, 6154, 3077, 9232, 4616, 2308, 1154, 577, 1732, 866, 433, 1300, 650, 325, 976, 488, 244, 122, 61, 184, 92, 46, 23, 70, 35, 106, 53, 160, 80, 40, 20, 10, 5, 16, 8, 4, 2, 1

Conway's Game of Life

Conway’s Game of Life is a cellular automata simulation that follows simple rules to create interesting patterns. It was invented by mathematician John Conway in 1970 and popularized by Martin Gardner’s “Mathematical Games” column in Scientific American. Today, it’s a favorite among programmers and computer scientists, though it’s more an interesting visualization than a true “game.” The two-dimensional board has a grid of “cells,” each of which follows three simple rules:

Living cells with two or three neighbors stay alive in the next step of the simulation.
Dead cells with exactly three neighbors become alive in the next step of the simulation.
Any other cell dies or stays dead in the next step of the simulation.

Tragically, Professor Conway passed away of complications from COVID-19 in April 2020. More information about Conway’s Game of Life can be found at https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life, and more information about Martin Gardner at https://en.wikipedia.org/wiki/Martin_Gardner.

For example, when the program runs it could look like this:

Countdown

Create a digital display that counts down, using the following "font" of digits made out of underscores and pipe characters:

   __         __    __          __    __   __    __    __
  |  |    |   __|   __|  |__|  |__   |__     |  |__|  |__|
  |__|    |  |__    __|     |   __|  |__|    |  |__|   __|

For example, when the program runs it could look like this:

 __   __       __   __       __   __
|  | |  |  *  |  | |  |  *   __| |__|
|__| |__|  *  |__| |__|  *  |__   __|

Press Ctrl-C to quit.

Deep Cave / Winding River

This program is a text animation of a deep cave that descends forever into the earth, or a top-down view of a winding river. Although short, this program takes advantage of the scrolling nature of the computer screen to produce an interesting and unending visualization, proof that it doesn’t take much code to produce something fun to watch.

Your program should:

Track how wide the left bank of the "river" is, along with the width of the "river" itself.
Randomly increase or decrease the width of the left bank and river.
Print the left bank using '#' characters and print the river using ' ' space characters.
Calculate the width of the right bank and print it with '#' characters.
Repeat endlessly.

For example, when the program runs it could look like this:

####################          ########################################
####################         #########################################
####################          ########################################
####################          ########################################
#####################          #######################################
######################          ######################################
#####################          #######################################
####################          ########################################
###################          #########################################

If you find this kind of animation interesting, you can find more examples of "scrolling ASCII art" on my other website, The Scroll Art Museum.

Diamonds

This program features a small algorithm for drawing ASCII-art diamonds of various sizes. It contains functions for drawing either an outline or filled-in-style diamond of the size you dictate. These functions are good practice for a beginner; try to understand the pattern behind the diamond drawings as they increase in size.

For example, when the program runs it could look like this:

/\
\/

/\
\/

 /\
/  \
\  /
 \/

 /\
//\\
\\//
 \/

  /\
 /  \
/    \
\    /
 \  /
  \/

  /\
 //\\
///\\\
\\\///
 \\//
  \/

Dice Math

This math quiz program rolls two to six dice whose sides you must add up as quickly as possible. But this program operates as more than just automated flash cards; it draws the faces of the dice to random places on the screen. The ASCII-art aspect adds a fun twist while you practice arithmetic.

For example, when the program runs it could look like this:

Add up the sides of all the dice displayed on the screen. You have
30 seconds to answer as many as possible. You get 4 points for each
correct answer and lose 1 point for each incorrect answer.

Press Enter to begin...
                                     +-------+
                                     | O   O |
                                     |   O   |
                                     | O   O |
                                     +-------+


                                  +-------+
            +-------+             | O   O |  +-------+
            |     O |             |       |  | O     |
            |       |             | O   O |  |       |
            | O     |             +-------+  |     O |
            +-------+                        +-------+
Enter the sum: 13

Dice Roller

Dungeons & Dragons and other tabletop role-playing games use special dice that can have 4, 8, 10, 12, or even 20 sides. These games also have a specific notation for indicating which dice to roll. For example, 3d6 means rolling three six-sided dice, while 1d10+2 means rolling one ten-sided die and adding a two-point bonus to the roll. This program simulates this dice rolling, in case you forgot to bring your own. It can also simulate rolling dice that don’t physically exist, such as a 38-sided die.

For example, when the program runs it could look like this:

> 3d6
7 (3, 2, 2)
> 1d10+2
9 (7, +2)
> 2d38-1
32 (20, 13, -1)
> 100d6
364 (3, 3, 2, 4, 2, 1, 4, 2, 4, 6, 4, 5, 4, 3, 3, 3, 2, 5, 1, 5, 6, 6, 6, 4, 5, 5, 1, 5, 2, 2, 2, 5, 1, 1, 2, 1, 4, 5, 6, 2, 4, 3, 4, 3, 5, 2, 2, 1, 1, 5, 1, 3, 6, 6, 6, 6, 5, 2, 6, 5, 4, 4, 5, 1, 6, 6, 6, 4, 2, 6, 2, 6, 2, 2, 4, 3, 6, 4, 6, 4, 2, 4, 3, 3, 1, 6, 3, 3, 4, 4, 5, 5, 5, 6, 2, 3, 6, 1, 1, 1)

Digital Clock

Create a digital clock with the current time, using the following "font" of digits made out of underscores and pipe characters:

   __         __    __          __    __   __    __    __
  |  |    |   __|   __|  |__|  |__   |__     |  |__|  |__|
  |__|    |  |__    __|     |   __|  |__|    |  |__|   __|

For example, when the program runs it could look like this:

 __   __       __   __       __   __
|  | |__|  *   __|  __|  *   __| |__
|__|  __|  *   __|  __|  *   __| |__|

Press Ctrl-C to quit.

Digital Stream / Matrix Screensaver

This program mimics the “digital stream” visualization from the science fiction movie The Matrix. Random beads of binary “rain” stream up from the bottom of the screen, creating a cool, hacker-like visualization.

For example, when the program runs it could look like this:

                     0                      0
                     0                      0
   1            0    0    1               1 0                             1
   0            0    0    1         0     0 0        0                    0
   0            1    0    0         0     1 0 0      1               0    1
   0            1    0    0         1     011 1      1               0    1 0
   0            1    0    0         0     000 11     0               0  1 1 0
   1     1      0 1  0    1         1     110 10  1  0               1  0 1 0
         1    101 0       0         1     000 11  1  1               11 1 1 1
         0    100 1       0               11  00  0  1               01     0
      1  1    001 1       1               0   1  10  0               10     0
      0  0    010 0       1                   1  11  11              0      0
--snip--

DNA Visualization

Let's create a DNA animation program. Deoxyribonucleic acid is a tiny molecule that exists in every cell of our bodies and contains the blueprint for how our bodies grow. It looks like a double helix (a sort of twisted ladder) of pairs of nucleotide molecules: guanine, cytosine, adenine, and thymine. These are represented by the letters G, C, A, and T. DNA is a long molecule; it’s microscopic, but if it were stretched out, its 3 billion base pairs would be 2 meters long! This program is a simple animation of DNA.

For example, when the program runs it could look like this:

        #G-C#
       #C---G#
      #T-----A#
     #T------A#
    #A------T#
    #G-----C#
     #G---C#
     #C-G#
      ##
     #T-A#
     #C---G#
    #G-----C#
    #G------C#
     #T------A#
      #A-----T#
       #C---G#
        #G-C#
         ##
        #T-A#
       #T---A#
      #A-----T#
--snip--

Ducklings

This program creates a scrolling field of ducklings. Each duckling has slight variations: they can face left or right and have two different body sizes, four types of eyes, two types of mouths, and three positions for their wings. This gives us 96 different possible variations, which the Ducklings program produces endlessly:

>" )   =^^)    (``=   ("=  >")    ("=
(  >)  (  ^)  (v  )  (^ )  ( >)  (v )
 ^ ^    ^ ^    ^ ^    ^^    ^^    ^^

For example, when the program runs it could look like this:

                                             =" )
=")                                          (  v)=")
( ^)                                          ^ ^ ( v) >'')
 ^^                                                ^^  (  ^)
                              >")                       ^ ^
                              ( v)      =^^)
 ("<  ("<                >")   ^^       (  >)
(^ ) (< )                ( ^)            ^ ^
 ^^   ^^             ("<  ^^                       (``<>^^)
 (^^=               (^ )                          (<  )(  ^)
(v  ) ( "<           ^^                            ^ ^  ^ ^
--snip--

Etching Drawer

When you move a pen point around the screen with the WASD keys, the etching drawer forms a picture by tracing a continuous line, like the Etch A Sketch toy. Let your artistic side break out and see what images you can create! This program also lets you save your drawings to a text file so you can print them out later. Plus, you can copy and paste the WASD movements of other drawings into this program, like the WASD commands for the Hilbert Curve fractal presented on lines 6 to 14 of the source code.

For example, when the program runs it could look like this:

WASD keys to move, H for help, C to clear, F to save, or QUIT.
> DDSAASSDDWDDSDDWWAAWDDDDSDDWDDDDSAASDDSAAAAWAASSSDDWDDDDSAASDDSAAAAWA
──┐ ┌───┐ ┌───┐
┌─┘ └─┐ └─┘ ┌─┘
│ ┌─┐ │ ┌─┐ └─┐
└─┘ └─┘ │ └───┘
        │ ┌───┐
        └─┘ ┌─┘
         #┐ └─┐
          └───┘

Factor Finder

A number’s factors are any two other numbers that, when multiplied with each other, produce the number. For example, 2 × 13 = 26, so 2 and 13 are factors of 26. Also, 1 × 26 = 26, so 1 and 26 are also factors of 26. Therefore, we say that 26 has four factors: 1, 2, 13, and 26.

If a number only has two factors (1 and itself), we call that a prime number. Otherwise, we call it a composite number. Use the factor finder to discover some new prime numbers! (Hint: Prime numbers always end with an odd number that isn’t 5.) You can also have the computer calculate them with Project 56, “Prime Numbers.”

The math for this program isn’t too heavy, making it an ideal project for beginners.

For example, when the program runs it could look like this:

Enter a number to factor (or "QUIT" to quit):
> 26
1, 2, 13, 26
Enter a number to factor (or "QUIT" to quit):
> 4352784
1, 2, 3, 4, 6, 8, 12, 16, 24, 29, 48, 53, 58, 59, 87, 106, 116, 118, 159, 174, 177, 212, 232, 236, 318, 348, 354, 424, 464, 472, 636, 696, 708, 848, 944, 1272, 1392, 1416, 1537, 1711, 2544, 2832, 3074, 3127, 3422, 4611, 5133, 6148, 6254, 6844, 9222, 9381, 10266, 12296, 12508, 13688, 18444, 18762, 20532, 24592, 25016, 27376, 36888, 37524, 41064, 50032, 73776, 75048, 82128, 90683, 150096, 181366, 272049, 362732, 544098, 725464, 1088196, 1450928, 2176392, 4352784
Enter a number to factor (or "QUIT" to quit):
> 9787
1, 9787

Fast Draw

This program tests your reaction speed: press Enter as soon as you see the word DRAW. But careful, though. Press it before DRAW appears, and you lose. Are you the fastest keyboard in the west?

This program works because pressing Enter during time.sleep() will cause the next input() call to return in less than a millisecond or two, which would be impossibly fast for a human. This is how you can tell if the player pressed Enter too early.

For example, when the program runs it could look like this:

Time to test your reflexes and see if you are the fastest
draw in the west!
When you see "DRAW", you have 0.3 seconds to press Enter.
But you lose if you press Enter before "DRAW" appears.

Press Enter to begin...

It is high noon...
DRAW!

You took 0.3485 seconds to draw. Too slow!
Enter QUIT to stop, or press Enter to play again.
> quit

Fibonacci

The Fibonacci sequence is a famous mathematical pattern credited to Italian mathematician Fibonacci in the 13th century (though others had discovered it even earlier). The sequence begins with 0 and 1, and the next number is always the sum of the previous two numbers. The sequence continues forever:

0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987 . . .

The Fibonacci sequence has applications in music composition, stock market prediction, the pattern of florets in the head of sunflowers, and many other areas. This program lets you calculate the sequence as high as you are willing to go. More information about the Fibonacci sequence can be found at https://en.wikipedia.org/wiki/Fibonacci_number.

For example, when the program runs it could look like this:

Enter the Nth Fibonacci number you wish to
calculate (such as 5, 50, 1000, 9999), or QUIT to quit:
> 50

0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377, 610, 987, 1597, 2584, 4181, 6765, 10946, 17711, 28657, 46368, 75025, 121393, 196418, 317811, 514229, 832040, 1346269, 2178309, 3524578, 5702887, 9227465, 14930352, 24157817, 39088169, 63245986, 102334155, 165580141, 267914296, 433494437, 701408733, 1134903170, 1836311903, 2971215073, 4807526976, 7778742049

Fish Tank

Watch your own virtual fish in a virtual fish tank, complete with air bubblers and kelp plants. Each time you run the program, it randomly generates the fish using different fish types and colors. Take a break and enjoy the calm serenity of this software aquarium, or try programming in some virtual sharks to terrorize its inhabitants! You can’t run this program from your IDE or editor. This program uses the bext module and must be run from the Command Prompt or Terminal in order to display correctly. More information about the bext module can be found at https://pypi.org/project/bext/.

For example, when the program runs it could look like this:

                     o          (       (
                                 )       )
                      o         (        )             }-[[[*>
                                 )       )
 <==-<               o          (o[[<    )
                                (        )            <//<
                    <=^_.-._.-  (       (
                                 )       )
                                 )      (                      <//<
                                 )      (
                                (        )
                                 )      (
                                (        )
                                 )       )
                                 )       )
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░

Flooder

Flooder is a colorful game where a player tries to fill the board with a single color by changing the color of the tile in the upper-left corner. This new color spreads to all neighboring tiles that matched the original color. It’s similar to the Flood It mobile game. This program also has a colorblind mode, which uses shapes instead of flat colored tiles. It relies on the recursive flood fill algorithm to paint the board and works similarly to the “paint bucket” or “fill” tool in many painting applications.

For example, when the program runs it could look like this:

┌────────────────┐
>♥♥♥♥♥♥♥♥♥♥♥♥♥♥▲▲│
│♥♥♥♥♥♥♥♥♥♦♦♥♥♦♦♦│
│♥♥♥♥♥♥♥♥♥♥♥♦♦♦♦♦│
│♥♥♥♥♥♥♥♥♥♥♥♦♦▲♦♦│
│♥♥♥♥♥♥♥♥♥♣♣♣♣♣♠●│
│♥♥♥♥♦♦♥♥♥♥♠♣♣♣♣♠│
│▲▲▲♥♥♥♥♥♥♥♥♥♦♠♥♠│
│▲▲♣♣●●●♠♥♥●♣♣♣♦♦│
│♣♣♣♠♠♠♠♦♠▲▲▲♠♠▲▲│
│●●♥●●●●●♣▲♠♠♠♥♣♣│
│♥♥♣♣♣♣♣♣▲♥♥♣♦♦♥♥│
│♣♣♦♠♥♥♦♦▲▲♠♠♠♠♠♥│
│▲▲♠●♥♥♥♥♠♠♣●●▲♠♠│
│♥♥●●♣♣♦♣♣♣♥♥♥♥▲▲│
└────────────────┘
Moves left: 12
Choose one of (H)eart, (T)riangle, (D)iamond, (B)all, (C)lub, (S)pade, or QUIT:
>

Forest Fire Sim

This simulation shows a forest whose trees are constantly growing and then being burned down. On each step of the simulation, there is a 1 percent chance that a blank space grows into a tree and a 1 percent chance that a tree is struck by lightning and burns. Fires will spread to adjacent trees, so a densely packed forest is more likely to suffer a larger fire than a sparsely packed one. This simulation was inspired by Nicky Case’s Emoji Sim at https://ncase.me/simulating/model/.

For example, when the program runs it could look like this:

        AA A  A   A   A    A   WA     AA    A      A               A      AA AA
A   A        A   A A           A       AA AAA    A     A   A  A               A
                    A       A  A    A   A  A A    A   WA      AA A    A      A
                A A      A        AAA          A     WW  A A   A   A A    W  A
   A                  AA   A          A        A  A              A   A
  A    A                            A          A A   A   A         A    W    A
     A      A  A  A      A    A           A    A A  A  AA  A WAA A           A
    A  A             A           A    A   A   A           AAAA     W    A
A   A            A                    A      A             A A      A   A A   A
       A          A   AA      A      A  A  A   A     AA  AA    AA
           AA      A AA           A     A A A        W       A A      A A A A
A          A  A     AA A    W  AA AA    A                 A   AA  A  A     A
          A  A  A AAA  A     W  A  A                 WA A     AA A     A  A
 A               A  AA        A    AA  A       A       A A  AA A   A        A A
 A   A            A    AA        A    A  A     A     A    A      A        A
          A    AA      A A       A    A  A             A     A    A     A   A
      AAA    A   A     AA   A             A  A           A        A    AA  A  A
         A        A    A    A                A        A              W   A    A
                        A A             A                                  A
          A  A    AA  A        A A     A A A       A   A          A
                              A  A             A      A A             A    A AA
    A      A     A      A      A A      A A    AA       A
Grow chance: 1.0%  Lightning chance: 1.0%  Press Ctrl-C to quit.

Four in a Row

In this classic tile-dropping board game for two players, you must try to get four of your tiles in a row horizontally, vertically, or diagonally, while preventing your opponent from doing the same. This program is similar to Connect Four.

For example, when the program runs it could look like this:

Player X, enter a column or QUIT:
> 3

     1234567
    +-------+
    |.......|
    |.......|
    |.......|
    |.......|
    |.......|
    |..X....|
    +-------+
Player O, enter a column or QUIT:
> 5
--snip--
Player O, enter a column or QUIT:
> 4

     1234567
    +-------+
    |.......|
    |.......|
    |XXX.XO.|
    |OOOOXO.|
    |OOOXOX.|
    |OXXXOXX|
    +-------+
Player O has won!

Guess the Number

Guess the Number is a game for beginners to practice basic programming techniques. In this game, the computer thinks of a random number between 1 and 100. The player has 10 chances to guess the number. After each guess, the computer tells the player if it was too high or too low.

For example, when the program runs it could look like this:

I am thinking of a number between 1 and 100.
You have 10 guesses left. Take a guess.
> 50
Your guess is too high.
You have 9 guesses left. Take a guess.
> 25
Your guess is too low.
--snip--
You have 5 guesses left. Take a guess.
> 42
Yay! You guessed my number!

Gullible

In this short and simple program, you can learn the secret and subtle art of keeping a gullible person busy for hours. I won’t spoil the punch line here. Copy the code and run it for yourself. This project is great for beginners, whether you’re smart or... not so smart.

For example, when the program runs it could look like this:

Do you want to know how to keep a gullible person busy for hours? Y/N
> y
Do you want to know how to keep a gullible person busy for hours? Y/N
> y
Do you want to know how to keep a gullible person busy for hours? Y/N
> yes
Do you want to know how to keep a gullible person busy for hours? Y/N
> YES
Do you want to know how to keep a gullible person busy for hours? Y/N
> TELL ME HOW TO KEEP A GULLIBLE PERSON BUSY FOR HOURS
"TELL ME HOW TO KEEP A GULLIBLE PERSON BUSY FOR HOURS" is not a valid yes/no response.
Do you want to know how to keep a gullible person busy for hours? Y/N
> y
Do you want to know how to keep a gullible person busy for hours? Y/N
> y
Do you want to know how to keep a gullible person busy for hours? Y/N
> n
Thank you. Have a nice day!

Hacking Minigame

In this game, the player must hack a computer by guessing a seven-letter word used as the secret password. The computer’s memory banks display the possible words, and the player is given hints as to how close each guess was. For example, if the secret password is MONITOR but the player guessed CONTAIN, they are given the hint that two out of seven letters were correct, because both MONITOR and CONTAIN have the letter O and N as their second and third letter. This game is similar to Project 1, “Bagels,” and the hacking minigame in the Fallout series of video games.

Here is a text file of seven letter words.

For example, when the program runs it could look like this:

Hacking Minigame, by Al Sweigart al@inventwithpython.com
Find the password in the computer's memory:
0x1150  $],>@|~~RESOLVE^    0x1250  {>+)<!?CHICKEN,%
0x1160  }@%_-:;/$^(|<|!(    0x1260  .][})?#@#ADDRESS
0x1170  _;)][#?<&~$~+&}}    0x1270  ,#=)>{-;/DESPITE
0x1180  %[!]{REFUGEE@?~,    0x1280  }/.}!-DISPLAY%%/
0x1190  _[^%[@}^<_+{_@$~    0x1290  =>>,:*%?_?@+{%#.
0x11a0  )?~/)+PENALTY?-=    0x12a0  >[,?*#IMPROVE@$/
--snip--
Enter password: (4 tries remaining)
> resolve
Access Denied (2/7 correct)
Enter password: (3 tries remaining)
> improve
A C C E S S   G R A N T E D

Hangman & Guillotine

This classic word game has the player guess the letters to a secret word. For each incorrect letter, another part of the hangman is drawn. Try to guess the complete word before the hangman completes. The secret words in this version are all animals like RABBIT and PIGEON, but you can replace these with your own set of words.

The HANGMAN_PICS variable contains ASCII-art strings of each step of the hangman’s noose:

 +--+     +--+     +--+     +--+     +--+     +--+     +--+
 |  |     |  |     |  |     |  |     |  |     |  |     |  |
    |     O  |     O  |     O  |     O  |     O  |     O  |
    |        |     |  |    /|  |    /|\ |    /|\ |    /|\ |
    |        |        |        |        |    /   |    / \ |
    |        |        |        |        |        |        |
=====    =====    =====    =====    =====    =====    =====

For a French twist on the game, you can replace the strings in the HANGMAN_PICS variable with the following strings depicting a guillotine:

|        |   |    |===|    |===|    |===|    |===|    |===|
|        |   |    |   |    |   |    |   |    || /|    || /|
|        |   |    |   |    |   |    |   |    ||/ |    ||/ |
|        |   |    |   |    |   |    |   |    |   |    |   |
|        |   |    |   |    |   |    |   |    |   |    |   |
|        |   |    |   |    |   |    |/-\|    |/-\|    |/-\|
|        |   |    |   |    |\ /|    |\ /|    |\ /|    |\O/|
|===     |===|    |===|    |===|    |===|    |===|    |===|

For example, when the program runs it could look like this:

 +--+
 |  |
 O  |
/|  |
    |
    |
=====
The category is: Animals

Missed letters: A I S
O T T E _
Guess a letter.
> r
Yes! The secret word is: OTTER
You have won!

Hex Grid

This short program produces a tessellated image of a hexagonal grid, similar to chicken wire. It shows that you don’t need a lot of code to make something interesting. A slightly more complicated variation of this program is Project 65, “Shining Carpet.”

For example, when the program runs it could look like this:

/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_
\_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/
/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_
\_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/
/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_
\_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/
/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_
\_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/
/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_
\_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/
/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_/ \_

For practice, try re-creating this program with larger hexagon grids, such as the following patterns:

 /   \     /   \     /   \     /   \     /   \     /   \     /   \
/     \___/     \___/     \___/     \___/     \___/     \___/     \
\     /   \     /   \     /   \     /   \     /   \     /   \     /
 \___/     \___/     \___/     \___/     \___/     \___/     \___/
 /   \     /   \     /   \     /   \     /   \     /   \     /   \
/     \___/     \___/     \___/     \___/     \___/     \___/     \

  /     \         /     \         /     \         /     \
 /       \       /       \       /       \       /       \
/         \_____/         \_____/         \_____/         \_____
\         /     \         /     \         /     \         /
 \       /       \       /       \       /       \       /
  \_____/         \_____/         \_____/         \_____/
  /     \         /     \         /     \         /     \
 /       \       /       \       /       \       /       \
/         \_____/         \_____/         \_____/         \_____

Hourglass

This visualization program has a rough physics engine that simulates sand falling through the small aperture of an hourglass. The sand piles up in the bottom half of the hourglass; then the hourglass is turned over so the process repeats.

Each piece of sand moves down (and to the left or right) if the space underneath it is empty.

For example, when the program runs it could look like this:

                  ███████████████████
                  █                 █
                  █                 █
                  █░░           ░░░░█
                   █░░        ░░░░░█
                    █░░░     ░░░░░█
                     █░░░ ░░░░░░░█
                      █░░░░░░░░░█
                       █░░ ░░░░█
                        █░░░░░█
                         █░░░█
                          █░█
                         █ ░ █
                        █     █
                       █   ░   █
                      █         █
                     █     ░     █
                    █             █
                   █     ░ ░       █
                  █      ░░░░       █
                  █      ░░░░░░     █
                  █    ░░░░░░░░░ ░  █
                  ███████████████████

Hungry Robots

You are trapped in a maze with hungry robots! You don’t know why robots need to eat, but you don’t want to find out. The robots are badly programmed and will move directly toward you, even if blocked by walls. You must trick the robots into crashing into each other (or dead robots) without being caught.

You are represented by an @ while the robots are R. Destroyed robots are X. For example, when the program runs it could look like this:

░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░   ░ R             R ░  ░             ░
░ ░    ░░░   R░                    ░░  ░
░     ░ ░    ░ ░  ░         ░  ░░░     ░
░    R░   ░    ░      ░░   ░░     ░    ░
░ ░░  ░     ░ ░░░    ░           ░     ░
░ ░░    ░   RX░░░  ░  ░  ░      ░      ░
░          ░ R     R        R ░      ░ ░
░    ░   ░            ░        ░   R ░ ░
░ ░ R       R     ░   R ░   R          ░
░   ░  ░     ░       ░  ░       ░   ░  ░
░  @            ░          ░    R░░░ ░ ░
░   ░  ░░      ░░                 ░    ░
░  ░   ░░  ░            ░     R       ░░
░░X          ░  ░        ░ R ░░RR  ░ R ░
░RR R       R ░    ░          ░       R░
░   ░░  RRR   R                        ░
░           ░░R     ░                  ░
░      R  ░ ░                     ░    ░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
(T)eleports remaining: 2
                    (Q) (W) ( )
                    (A) (S) (D)
Enter move or QUIT: (Z) (X) ( )

J'Accuse!

You are the world-famous detective Mathilde Camus. Zophie the cat has gone missing, and you must sift through the clues. Suspects either always tell lies or always tell the truth. Will you find Zophie the cat in time and accuse the guilty party?

In this game, you take a taxi to different locations around the city. At each location is a suspect and an item. You can ask suspects about other suspects and items, compare their answers with your own exploration notes, and determine if they are lying or telling the truth. Some will know who has catnapped Zophie (or where she is, or what item is found at the location of the kidnapper), but you must determine if you can believe them. You have five minutes to find the criminal but will lose if you make three wrong accusations. This game is inspired by Homestar Runner’s “Where’s an Egg?” game.

For example, when the program runs it could look like this:

Time left: 5 min, 0 sec
  You are in your TAXI. Where do you want to go?
(A)LBINO ALLIGATOR PIT
(B)OWLING ALLEY
(C)ITY HALL
(D)UCK POND
(H)IPSTER CAFE
(O)LD BARN
(U)NIVERSITY LIBRARY
(V)IDEO GAME MUSEUM
(Z)OO
> a

Time left: 4 min, 48 sec
  You are at the ALBINO ALLIGATOR PIT.
  ESPRESSA TOFFEEPOT with the ONE COWBOY BOOT is here.

(J) "J'ACCUSE!" (3 accusations left)
(Z) Ask if they know where ZOPHIE THE CAT is.
(T) Go back to the TAXI.
(1) Ask about ESPRESSA TOFFEEPOT
(2) Ask about ONE COWBOY BOOT
> z
  They give you this clue: "DUKE HAUTDOG"
Press Enter to continue...

Langton's Ant

Langton’s Ant is a cellular automata simulation on a two-dimensional grid, similar to Project 13, “Conway’s Game of Life.” In the simulation, an “ant” begins on a square that is one of two colors. If the space is the first color, the ant switches it to the second color, turns 90 degrees to the right, and moves forward one space. If the space is the second color, the ant switches it to the first color, turns 90 degrees to the left, and moves forward one space. Despite the very simple set of rules, the simulation displays complex emergent behavior. Simulations can feature multiple ants in the same space, causing interesting interactions when they cross paths with each other. Langton’s Ant was invented by computer scientist Chris Langton in 1986. More information about Langton’s Ant can be found at https://en.wikipedia.org/wiki/Langton%27s_ant.

Leetspeak

There’s no better way to demonstrate your mad hacker skills than by replacing letters in your text with numbers: m4d h4x0r 5k1llz!!! This word program automatically converts plain English into leetspeak, the coolest way to talk online. Or at least it was in 1993.

It takes a while to get used to, but with some practice, you’ll eventually be able to read leetspeak fluently. For example, 1t +@]<3s 4 w|-|1le +o g37 ||s3|) 70, b||+ y0u (an 3\/3nt||/-\lly r3a|) l33t$peak phl||3n+ly. Leetspeak may be hard to read at first, but the program itself is simple and good for beginners. More information about leetspeak can be found at https://en.wikipedia.org/wiki/Leet.

For example, when the program runs it could look like this:

Enter your leet message:
> I am a leet hacker. Fear my mad skills. The 90s were over two decades ago.

! @m a l33t h@(]<er. ph3@r my m4|) $k|ll$. +h3 90s w3r3 0ver tw0 d3(ad3$ 4g0.
(Copied leetspeak to clipboard.)

Lucky Stars

In this push-your-luck game, you roll dice to collect stars. The more you roll, the more stars you can get, but if you get three skulls you lose everything! This quick multiplayer game can support as many players as you want, making it ideal for parties. Inspired by the Zombie Dice game from Steve Jackson Games.

On your turn, you pull three random dice from the dice cup and roll them. You can roll Stars, Skulls, and Question Marks. If you end your turn, you get one point per Star. If you choose to roll again, you keep the Question Marks and pull new dice to replace the Stars and Skulls. If you collect three Skulls, you lose all your Stars and end your turn.

When a player gets 13 points, everyone else gets one more turn before the game ends. Whoever has the most points wins.

There are six gold dice, four silver dice, and three bronze dice in the cup. Gold dice have more Stars, bronze dice have more Skulls, and silver is even.

For example, when the program runs it could look like this:

SCORES: Alice=0, Bob=0
It is Alice's turn.

+-----------+ +-----------+ +-----------+
|           | |     .     | |           |
|           | |    ,O,    | |           |
|     ?     | | 'ooOOOoo' | |     ?     |
|           | |   `OOO`   | |           |
|           | |   O' 'O   | |           |
+-----------+ +-----------+ +-----------+
     GOLD          GOLD         BRONZE
Stars collected: 1   Skulls collected: 0
Do you want to roll again? Y/N
> y

+-----------+ +-----------+ +-----------+
|     .     | |    ___    | |           |
|    ,O,    | |   /   \   | |           |
| 'ooOOOoo' | |  |() ()|  | |     ?     |
|   `OOO`   | |   \ ^ /   | |           |
|   O' 'O   | |    VVV    | |           |
+-----------+ +-----------+ +-----------+
     GOLD         BRONZE        BRONZE
Stars collected: 2   Skulls collected: 1
Do you want to roll again? Y/N
--snip--

Magic Fortune Ball

The Magic Fortune Ball can predict the future and answer your yes/no questions with 100 percent accuracy using the power of Python’s random number module. This program is similar to a Magic 8 Ball toy, except you don’t have to shake it. It also features a function for slowly printing text strings with spaces in between each character, giving the messages a spooky, mysterious effect.

Most of the code is dedicated to setting the eerie atmosphere. The program itself simply selects a message to display in response to a random number.

For example, when the program runs it could look like this:

M A G i C   F O R T U N E   B A L L ,   B Y   A L   S W E i G A R T

A S K   M E   Y O U R   Y E S / N O   Q U E S T i O N .

> Isn't fortune telling just a scam to trick money out of gullible people?
L E T   M E   T H i N K   O N   T H i S . . .

. . . . . . . .

i   H A V E   A N   A N S W E R . . .

A F F i R M A T i V E

Mancala

The board game Mancala is at least 2,000 years old, making it almost as old as Project 63, “Royal Game of Ur.” It is a “seed-sowing” game in which two players select pockets of seeds to spread across the other pockets on the board while trying to collect as many in their store as possible. There are several variants of this game across different cultures. The name comes from the Arab word naqala, meaning “to move.”

To play, grab the seeds from a pit on your side of the board and place one in each subsequent pit, going counterclockwise and skipping your opponent’s store. If your last seed lands in an empty pit of yours, move the opposite pit’s seeds into that pit. If the last placed seed is in your store, you get a free turn.

The game ends when all of one player’s pits are empty. The other player claims the remaining seeds for their store, and the winner is the one with the most seeds. More information about Mancala and its variants can be found at https://en.wikipedia.org/wiki/Mancala.

For example, when the program runs it could look like this:

+------+------+--<<<<<-Player 2----+------+------+------+
2      |G     |H     |I     |J     |K     |L     |      1
       |   4  |   4  |   4  |   4  |   4  |   4  |
S      |      |      |      |      |      |      |      S
T   0  +------+------+------+------+------+------+   0  T
O      |A     |B     |C     |D     |E     |F     |      O
R      |   4  |   4  |   4  |   4  |   4  |   4  |      R
E      |      |      |      |      |      |      |      E
+------+------+------+-Player 1->>>>>-----+------+------+


Player 1, choose move: A-F (or QUIT)
> f

+------+------+--<<<<<-Player 2----+------+------+------+
2      |G     |H     |I     |J     |K     |L     |      1
       |   4  |   4  |   4  |   5  |   5  |   5  |
S      |      |      |      |      |      |      |      S
T   0  +------+------+------+------+------+------+   1  T
O      |A     |B     |C     |D     |E     |F     |      O
R      |   4  |   4  |   4  |   4  |   4  |   0  |      R
E      |      |      |      |      |      |      |      E
+------+------+------+-Player 1->>>>>-----+------+------+
Player 2, choose move: G-L (or QUIT)

Maze Runner 2D

This two-dimensional maze runner shows the player a top-down, bird’s-eye view of a maze file you create in a text editor, such as the IDE you use to write your .py files. Using the WASD keys, the player can move up, left, down, and right, respectively, to navigate the @ symbol toward the exit marked by the X character.

To make a maze file, open a text editor and create the following pattern. Don’t type the numbers along the top and left side; they are only there for reference:

 123456789
1#########
2#S# # # #
3#########
4# # # # #
5#########
6# # # # #
7#########
8# # # #E#
9#########

The # characters represent walls, the S marks the start, and the E marks the exit. The # characters in bold represent walls that you can remove to form your maze. Don’t remove the walls at odd-numbered columns and odd-numbered rows, and don’t remove the borders of the maze. When you’re done, save the maze as a .txt (text) file. It could look something like this:

#########
#S    # #
# ### # #
# #   # #
# ##### #
<a id="#-#-#" />
#   #   #
### # # #
#     #E#
#########

Of course, this is a simple maze. You can make maze files of any size as long as they have an odd number of rows and columns. Be sure it’ll still fit on the screen, though! You can also download maze files from https://invpy.com/mazes/.

For example, when the program runs it could look like this:

Enter the filename of the maze (or LIST or QUIT):
> maze65x11s1.txt
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
░@░     ░       ░               ░                       ░   ░   ░
░ ░░░░░ ░ ░░░ ░ ░ ░░░░░░░ ░░░░░ ░░░░░░░░░░░░░░░░░░░░░ ░░░ ░ ░ ░ ░
░ ░   ░     ░ ░ ░   ░   ░     ░   ░           ░     ░   ░ ░   ░ ░
░ ░ ░ ░░░░░ ░ ░ ░░░░░ ░ ░░░░░ ░░░ ░ ░░░░░░░░░ ░ ░░░ ░░░ ░ ░░░░░ ░
░   ░     ░ ░ ░   ░   ░       ░ ░   ░       ░ ░ ░ ░   ░   ░     ░
░░░░░░░░░ ░░░ ░░░ ░ ░░░░░░░░░░░ ░░░░░ ░ ░░░░░ ░ ░ ░░░ ░░░░░ ░░░░░
░ ░     ░ ░   ░ ░ ░ ░           ░     ░       ░ ░     ░   ░     ░
░ ░ ░ ░░░ ░ ░░░ ░ ░ ░ ░░░░░░░░░░░ ░░░░░░░░░░░░░ ░ ░░░░░ ░ ░░░░░ ░
░   ░       ░       ░                           ░       ░      X░
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
                           W
Enter direction, or QUIT: ASD

Maze Runner 3D

This three-dimensional maze runner provides the player with a first-person view from inside a maze. Try to find your way out! You can generate maze files by following the instructions in Project 44, “Maze Runner 2D,” or by downloading maze files from https://invpy.com/mazes/.

For example, when the program runs it could look like this:

Enter the filename of the maze (or LIST or QUIT):
> maze75x11s1.txt
░░░░░░░░░░░░░░░░░░░
░  \           /  ░
░   \_________/   ░
░    |       |    ░
░    |       |    ░
░    |       |    ░
░    |       |    ░
░    |       |    ░
░    |       |    ░
░    |       |    ░
░    |       |    ░
░    |_______|    ░
░   /         \   ░
░  /           \  ░
░░░░░░░░░░░░░░░░░░░
Location (1, 1)  Direction: NORTH
                   (W)
Enter direction: (A) (D)  or QUIT.
> d
░░░░░░░░░░░░░░░░░░░
░  \              ░
░   \_____________░
░    |            ░
░    |            ░
░    |            ░
░    |            ░
░    |            ░
░    |            ░
░    |            ░
░    |            ░
░    |____________░
░   /             ░
░  /              ░
░░░░░░░░░░░░░░░░░░░
Location (1, 1)  Direction: EAST

Million Dice Statistics

When you roll two six-sided dice, there’s a 17 percent chance you’ll roll a 7. That’s much better than the odds of rolling a 2: just 3 percent. That’s because there’s only one combination of dice rolls that gives you 2 (the one that occurs when both dice roll a 1), but many combinations add up to seven: 1 and 6, 2 and 5, 3 and 4, and so on.

But what about when you roll three dice? Or four? Or 1,000? You could mathematically calculate the theoretical probabilities, or you can have the computer roll a number of dice one million times to empirically figure them out. This program takes that latter approach. In this program, you tell the computer to roll N dice one million times and remember the results. It then displays the percentage chance of each sum.

For example, when the program runs it could look like this:

Enter how many six-sided dice you want to roll:
> 2
Simulating 1,000,000 rolls of 2 dice...
36.2% done...
73.4% done...
TOTAL - ROLLS - PERCENTAGE
  2 - 27590 rolls - 2.8%
  3 - 55730 rolls - 5.6%
  4 - 83517 rolls - 8.4%
  5 - 111526 rolls - 11.2%
  6 - 139015 rolls - 13.9%
  7 - 166327 rolls - 16.6%
  8 - 139477 rolls - 13.9%
  9 - 110268 rolls - 11.0%
  10 - 83272 rolls - 8.3%
  11 - 55255 rolls - 5.5%
  12 - 28023 rolls - 2.8%

Mondrian Art Generator

Piet Mondrian was a 20th-century Dutch painter and one of the founders of neoplasticism, an abstract art movement. His most iconic paintings relied on blocks of primary colors (blue, yellow, red), black, and white. Using a minimalist approach, he separated these colors with horizontal and vertical elements.

This program generates random paintings that follow Mondrian’s style. You can find out more about Piet Mondrian at https://en.wikipedia.org/wiki/Piet_Mondrian. An implementation of this algorithm with examples is in this git repo.

Monty Hall

The Monty Hall Problem illustrates a surprising fact of probability. The problem is loosely based on the old game show Let’s Make a Deal and its host, Monty Hall. In the Monty Hall Problem, you can pick one of three doors. Behind one door is a prize: a new car. Each of the other two doors opens onto a worthless goat. Say you pick Door #1. Before the door you choose is opened, the host opens another door (either #2 or #3), which leads to a goat. You can choose to either open the door you originally picked or switch to the other unopened door.

It may seem like it doesn’t matter if you switch or not, but your odds do improve if you switch doors! This program demonstrates the Monty Hall problem by letting you do repeated experiments.

For example, when the program runs it could look like this:

+------+  +------+  +------+
|      |  |      |  |      |
|   1  |  |   2  |  |   3  |
|      |  |      |  |      |
|      |  |      |  |      |
|      |  |      |  |      |
+------+  +------+  +------+
Pick a door 1, 2, or 3 (or "quit" to stop):
> 1

+------+  +------+  +------+
|      |  |      |  |  ((  |
|   1  |  |   2  |  |  oo  |
|      |  |      |  | /_/|_|
|      |  |      |  |    | |
|      |  |      |  |GOAT|||
+------+  +------+  +------+
Door 3 contains a goat!
Do you want to swap doors? Y/N
> y

+------+  +------+  +------+
|  ((  |  | CAR! |  |  ((  |
|  oo  |  |    __|  |  oo  |
| /_/|_|  |  _/  |  | /_/|_|
|    | |  | /_ __|  |    | |
|GOAT|||  |   O  |  |GOAT|||
+------+  +------+  +------+
Door 2 has the car!
You won!

Swapping:     1 wins, 0 losses, success rate 100.0%
Not swapping: 0 wins, 0 losses, success rate 0.0%

Press Enter to repeat the experiment...

Multiplication Table

This program generates a multiplication table from 0 × 0 to 12 × 12. While simple, it provides a useful demonstration of nested loops.

For example, when the program runs it could look like this:

  |  0   1   2   3   4   5   6   7   8   9  10  11  12
--+---------------------------------------------------
 0|  0   0   0   0   0   0   0   0   0   0   0   0   0
 1|  0   1   2   3   4   5   6   7   8   9  10  11  12
 2|  0   2   4   6   8  10  12  14  16  18  20  22  24
 3|  0   3   6   9  12  15  18  21  24  27  30  33  36
 4|  0   4   8  12  16  20  24  28  32  36  40  44  48
 5|  0   5  10  15  20  25  30  35  40  45  50  55  60
 6|  0   6  12  18  24  30  36  42  48  54  60  66  72
 7|  0   7  14  21  28  35  42  49  56  63  70  77  84
 8|  0   8  16  24  32  40  48  56  64  72  80  88  96
 9|  0   9  18  27  36  45  54  63  72  81  90  99 108
10|  0  10  20  30  40  50  60  70  80  90 100 110 120
11|  0  11  22  33  44  55  66  77  88  99 110 121 132
12|  0  12  24  36  48  60  72  84  96 108 120 132 144

Ninety Nine Bottles

“Ninety-Nine Bottles” is a folk song of undetermined origin known for its length and repetitiveness. The lyrics go, “Ninety-nine bottles of milk on the wall, ninety-nine bottles of milk. Take one down, pass it around, ninety-eight bottles of milk on the wall.” As the lyrics repeat, the number of bottles falls from ninety-eight to ninety-seven, then from ninety-seven to ninety-six, until it reaches zero: “One bottle of milk on the wall, one bottle of milk. Take it down, pass it around, no more bottles of milk on the wall!”

For example, when the program runs it could look like this:

99 bottles of milk on the wall,
99 bottles of milk,
Take one down, pass it around,
98 bottles of milk on the wall!

98 bottles of milk on the wall,
98 bottles of milk,
Take one down, pass it around,
97 bottles of milk on the wall!
--snip--

niNety nniinE BoOttels

In this version of the song “Ninety-Nine Bottles,” the program introduces small imperfections in each stanza by either removing a letter, swapping the casing of a letter, transposing two letters, or doubling a letter. As the song continues to play, these mutations add up, resulting in a very silly song.

For example, when the program runs it could look like this:

99 bottles of milk on the wall,
99 bottles of milk,
Take one down, pass it around,
98 bottles of milk on the wall!

98 bottles of milk on the wall,
98 bottles of milk,
Take one d wn, pass it around,
97 bottles of milk on the wall!

97 bottles of milk on the wall,
97 bottels of milk,
Take one d wn,  pass it around,
96 bottles of milk on the wall!
--snip--
75b otlte  of mIl  on teh wall,
75   ottels  f miLk,
Take one d wn,  pass it ar und,
74 bbOttles of milk on t e wall!
--snip--
1  otlE t of iml  oo nteh  lall,
1   o  Tle   FF FmMLIIkk,
Taake on  d wn,  pAasSs itt au nn d,
No more bottles of milk on the wall!

Numeral Systems

This program displays numbers in decimal, hexadecimal, and binary.

We’re used to counting in the decimal numeral system, which uses 10 digits: 0 through 9. This system likely developed because humans counted on their fingers, and most people have 10 fingers. But other number systems exist. Computers make use of binary, a numeral system with only two digits, 0 and 1. Programmers also sometimes use hexadecimal, which is a base-16 numeral system that uses the digits 0 to 9 but also extends into the letters A to F.

For example, when the program runs it could look like this:

Enter the starting number (e.g. 0) > 0
Enter how many numbers to display (e.g. 1000) > 20
DEC: 0    HEX: 0    BIN: 0
DEC: 1    HEX: 1    BIN: 1
DEC: 2    HEX: 2    BIN: 10
DEC: 3    HEX: 3    BIN: 11
DEC: 4    HEX: 4    BIN: 100
DEC: 5    HEX: 5    BIN: 101
DEC: 6    HEX: 6    BIN: 110
DEC: 7    HEX: 7    BIN: 111
DEC: 8    HEX: 8    BIN: 1000
DEC: 9    HEX: 9    BIN: 1001
DEC: 10    HEX: A    BIN: 1010
DEC: 11    HEX: B    BIN: 1011
DEC: 12    HEX: C    BIN: 1100
DEC: 13    HEX: D    BIN: 1101
DEC: 14    HEX: E    BIN: 1110
DEC: 15    HEX: F    BIN: 1111
DEC: 16    HEX: 10    BIN: 10000
DEC: 17    HEX: 11    BIN: 10001
DEC: 18    HEX: 12    BIN: 10010
DEC: 19    HEX: 13    BIN: 10011

Periodic Table of the Elements

The periodic table of the elements organizes all known chemical elements into a single table. This program presents this table and lets the player access additional information about each element, such as its atomic number, symbol, melting point, and so on. I compiled this information from Wikipedia and stored it in a file called periodictable.csv that you can download from https://inventwithpython.com/periodictable.csv.

For example, when the program runs it could look like this:

            Periodic Table of Elements
      1  2  3  4  5  6  7  8  9  10 11 12 13 14 15 16 17 18
    1 H                                                  He
    2 Li Be                               B  C  N  O  F  Ne
    3 Na Mg                               Al Si P  S  Cl Ar
    4 K  Ca Sc Ti V  Cr Mn Fe Co Ni Cu Zn Ga Ge As Se Br Kr
    5 Rb Sr Y  Zr Nb Mo Tc Ru Rh Pd Ag Cd In Sn Sb Te I  Xe
    6 Cs Ba La Hf Ta W  Re Os Ir Pt Au Hg Tl Pb Bi Po At Rn
    7 Fr Ra Ac Rf Db Sg Bh Hs Mt Ds Rg Cn Nh Fl Mc Lv Ts Og

            Ce Pr Nd Pm Sm Eu Gd Tb Dy Ho Er Tm Yb Lu
            Th Pa U  Np Pu Am Cm Bk Cf Es Fm Md No Lr
Enter a symbol or atomic number to examine, or QUIT to quit.
> 42
             Atomic Number: 42
                    Symbol: Mo
                   Element: Molybdenum
            Origin of name: Greek molýbdaina, 'piece of lead', from mólybdos, 'lead'
                     Group: 6
                    Period: 5
             Atomic weight: 95.95(1) u
                   Density: 10.22 g/cm^3
             Melting point: 2896 K
             Boiling point: 4912 K
    Specific heat capacity: 0.251 J/(g*K)
         Electronegativity: 2.16
Abundance in earth's crust: 1.2 mg/kg
Press Enter to continue...
--snip--

Pig Latin

Pig Latin is a word game that transforms English words into a parody of Latin. In Pig Latin, if a word begins with a consonant, the speaker removes this letter and puts it at the end, followed by “ay.” For example, “pig” becomes “igpay” and “latin” becomes “atinlay.” Otherwise, if the word begins with a vowel, the speaker simply adds “yay” to the end of it. For example, “elephant” becomes “elephantyay” and “umbrella” becomes “umbrellayay.”

For example, when the program runs it could look like this:

Enter your message:
> This is a very serious message.
Isthay isyay ayay eryvay erioussay essagemay.
(Copied pig latin to clipboard.)

Powerball Lottery

The Powerball Lottery is an exciting way to lose small amounts of money. If you purchase a $2 ticket, you can pick six numbers: five drawn from 1 to 69, and a sixth “Powerball” number drawn from 1 to 26. The order of the numbers doesn’t matter. If the lottery selects your six numbers, you win $1.586 billion dollars! Except you won’t win, because your odds are 1 in 292,201,338. But if you spent $200 on 100 tickets, your odds would be . . . 1 in 2,922,013. You won’t win that either, but at least you’ll lose 100 times as much money. The more you like losing money, the more fun the lottery is!

For example, when the program runs it could look like this:

Enter 5 different numbers from 1 to 69, with spaces between
each number. (For example: 5 17 23 42 50 51)
> 1 2 3 4 5
Enter the powerball number from 1 to 26.
> 6
How many times do you want to play? (Max: 1000000)
> 1000000
It costs $2000000 to play 1000000 times, but don't
worry. I'm sure you'll win it all back.
Press Enter to start...
The winning numbers are: 12 29 48 11 4 and 13  You lost.
The winning numbers are: 54 39 3 42 16 and 12  You lost.
The winning numbers are: 56 4 63 23 38 and 24  You lost.
--snip--
The winning numbers are: 46 29 10 62 17 and 21 You lost.
The winning numbers are: 5 20 18 65 30 and 10  You lost.
The winning numbers are: 54 30 58 10 1 and 18  You lost.
You have wasted $2000000
Thanks for playing!

Prime Numbers

A prime number is a number that is evenly divisible only by one and itself. Prime numbers have a variety of practical applications, but no algorithm can predict them; we must calculate them one at a time. However, we do know that there is an infinite number of prime numbers to be discovered.

This program finds prime numbers through brute-force calculation. Its code is similar to Project 24, “Factor Finder.” (Another way to describe a prime number is that one and the number itself are its only factors.) You can find out more about prime numbers from https://en.wikipedia.org/wiki/Prime_number.

For example, when the program runs it could look like this:

Enter a number to start searching for primes from:
(Try 0 or 1000000000000 (12 zeros) or another number.)
> 0
Press Ctrl-C at any time to quit. Press Enter to begin...
2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71, 73, 79, 83, 89, 97, 101, 103, 107, 109, 113, 127, 131, 137, 139, 149, 151, 157, 163, 167, 173, 179, 181, 191, 193, 197, 199, 211, 223, 227, 229, 233, 239, 241, 251, 257, 263, 269, 271, 277, 281, 283, 293, 307, 311, 313, 317, 331, 337, 347, 349, 353, 359, 367, 373, 379, 383, 389, 397, 401, 409, 419, 421, 431, 433, 439, 443, 449, 457, 461, 463, 467, 479, 487, 491, 499, 503, 509, 521, 523, 541, 547, 557, 563, 569, 571, 577, 587, 593, 599, 601, 607, 613, 617, 619, 631, 641, 643, 647, --snip--

Progress Bar

A progress bar is a visual element that shows how much of a task has been completed. Progress bars are often used alongside downloading files or software installations. This project creates a getProgressBar() function that returns a progress bar string based on the arguments passed to it. It simulates a downloading file, but you can reuse the progress bar code in your own projects.

You can animate the text by printing \b backspace characters to erase text you've already printed and then print a new progress bar.

For example, when the program runs it could look like this:

Progress Bar Simulation, by Al Sweigart
[█████████                               ] 24.6% 1007/4098

Rainbow

Rainbow is a simple program that shows a colorful rainbow traveling back and forth across the screen. The program makes use of the fact that when new lines of text appear, the existing text scrolls up, causing it to look like it’s moving.

If you find this kind of animation interesting, you can find more examples of "scrolling ASCII art" on my other website, The Scroll Art Museum.

Rock Paper Scissors

In this version of the two-player hand game also known as Rochambeau or jan-ken-pon, the player faces off against the computer. You can pick either rock, paper, or scissors. Rock beats scissors, scissors beats paper, and paper beats rock. This program adds some brief pauses for suspense.

For example, when the program runs it could look like this:

Enter your move: (R)ock (P)aper (S)cissors or (Q)uit
> r
ROCK versus...
1...
2...
3...
SCISSORS
You win!
1 Wins, 0 Losses, 0 Ties
Enter your move: (R)ock (P)aper (S)cissors or (Q)uit
--snip--

Rock Paper Scissors (Always-Win Version)

This variant of Rock Paper Scissors is identical to “Rock Paper Scissors,” except the player will always win. The code selecting the computer’s move is set so that it always chooses the losing move. You can offer this game to your friends, who may be excited when they win... at first. See how long it takes before they catch on to the fact that the game is rigged in their favor.

For example, when the program runs it could look like this:

0 Wins, 0 Losses, 0 Ties
Enter your move: (R)ock (P)aper (S)cissors or (Q)uit
> p
PAPER versus...
1...
2...
3...
ROCK
You win!
1 Wins, 0 Losses, 0 Ties
Enter your move: (R)ock (P)aper (S)cissors or (Q)uit
> s
SCISSORS versus...
1...
2...
3...
PAPER
You win!
2 Wins, 0 Losses, 0 Ties
--snip--
SCISSORS versus...
1...
2...
3...
PAPER
You win!
413 Wins, 0 Losses, 0 Ties
Enter your move: (R)ock (P)aper (S)cissors or (Q)uit
--snip--

ROT 13 Cipher

The ROT13 cipher, one of the simplest encryption algorithms, stands for “rotate 13 spaces.” The cypher represents the letters A to Z as the numbers 0 to 25 in such a way that the encrypted letter is 13 spaces from the plaintext letter: A becomes N, B becomes O, and so on. The encryption process is identical to the decryption process, making it trivial to program. However, the encryption is also trivial to break. Because of this, you’ll most often find ROT13 used to conceal non-sensitive information, such as spoilers or trivia answers, so it’s not read unintentionally. More information about the ROT13 cipher can be found at https://en.wikipedia.org/wiki/ROT13. If you’d like to learn about ciphers and code breaking more generally, you can read my book Cracking Codes with Python (No Starch Press, 2018; https://nostarch.com/crackingcodes/).

For example, when the program runs it could look like this:

Enter a message to encrypt/decrypt (or QUIT):
> Meet me by the rose bushes tonight.
The translated message is:
Zrrg zr ol gur ebfr ohfurf gbavtug.

(Copied to clipboard.)

Rotating Cube

This project features an animation of a 3D cube rotating using trigonometric functions. You can adapt the 3D point rotation math and the line() function in your own animation programs.

Although the block text characters we’ll use to draw the cube don’t look like thin, straight lines, this kind of drawing is called a wireframe model because it renders only the edges of an object’s surfaces.

For example, when the program runs it could look like this:

                     ██
                    █ ███
                   █   █ ██
                  █    █   ██
                 █      █    ██
                █        █     ██
               █          █      ██
              █            █       █
             █              █     █ █
            █               █    █  █
           █                 █  █    █
          █                   ██      █
         █                    ██       █
        █                    █  █      █
       █                    █    █      █
      █                    █     █       █
     █                    █       █       █
    █                    █         █      █
   █                    █           █      █
  █                    █           █ ██     █
   ██                 █           █    ██    █
   █ ██              █           █       █   █
    █  █            █           █         ██  █
     █  ██         █           █            █  █
      █   ██      █           █              ███
      █     █    █           █                 ██
       █     ██ █           █                    █
        █      █           █                    █
         █      █         █                    █
         █       █       █                    █
          █      █      █                    █
           █      █    █                    █
            █      █  █                    █
            █       ██                    █
             █      ██                   █
              █    █  █                 █
               █  █   █                █
               █ █     █              █
                ██      █            █
                  ██     █          █
                    ██    █        █
                      ██   █      █
                        ██ █     █
                          ███   █
                            ██ █
                              █

Royal Game of Ur

The Royal Game of Ur is a 5,000-year-old game from Mesopotamia. Archeologists rediscovered the game in the Royal Cemetery at Ur, in modern-day southern Iraq, during excavations between 1922 and 1934. The rules were reconstructed from the game board and a Babylonian clay tablet, and they’re similar to Parcheesi. You’ll need both luck and skill to win.

A video featuring YouTuber Tom Scott and British Museum curator Irving Finkel discussing the Royal Game of Ur can be found at https://www.youtube.com/watch?v=WZskjLq040I.

For example, when the program runs it could look like this:

--snip--
                   XXXXXXX           .......
                   Home              Goal
                     v                 ^
+-----+-----+-----+--v--+           +--^--+-----+
|*****|     |     |     |           |*****|     |
|*   *<     <     <     |           |*   *<     |
|****h|    g|    f|    e|           |****t|    s|
+--v--+-----+-----+-----+-----+-----+-----+--^--+
|     |     |     |*****|     |     |     |     |
|     >     >     >*   *>     >     >     >     |
|    i|    j|    k|****l|    m|    n|    o|    p|
+--^--+-----+-----+-----+-----+-----+-----+--v--+
|*****|     |     |     |           |*****|     |
|*   *<     <     <     |           |*   *<     |
|****d|    c|    b|    a|           |****r|    q|
+-----+-----+-----+--^--+           +--v--+-----+
                     ^                 v
                   Home              Goal
                   OOOOOOO           .......

It is O's turn. Press Enter to flip...
Flips: H-H-H-H  Select token to move 4 spaces: home quit
> home
O landed on a flower space and gets to go again.
Press Enter to continue...
--snip--

Shining Carpet

The Shining, a 1980 psychological horror film directed by Stanley Kubrick, takes place at the haunted Overlook Hotel. The hotel carpet’s hexagonal design became an iconic part of this famous movie. The carpet features alternating and interlocking hexagons whose mesmerizing effect is well-suited for such an unnerving film. The short program in this project, similar to Project 35, “Hex Grid,” prints this repetitive pattern on the screen.

For example, when the program runs it could look like this:

_ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ __
 \ \ \___/ _ \ \ \___/ _ \ \ \___/ _ \ \ \___/ _ \ \ \___/ _ \ \ \___/ _
\ \ \_____/ \ \ \_____/ \ \ \_____/ \ \ \_____/ \ \ \_____/ \ \ \_____/
/ / / ___ \_/ / / ___ \_/ / / ___ \_/ / / ___ \_/ / / ___ \_/ / / ___ \_
_/ / / _ \___/ / / _ \___/ / / _ \___/ / / _ \___/ / / _ \___/ / / _ \__
__/ / / \_____/ / / \_____/ / / \_____/ / / \_____/ / / \_____/ / / \___
_ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ __
 \ \ \___/ _ \ \ \___/ _ \ \ \___/ _ \ \ \___/ _ \ \ \___/ _ \ \ \___/ _
\ \ \_____/ \ \ \_____/ \ \ \_____/ \ \ \_____/ \ \ \_____/ \ \ \_____/
/ / / ___ \_/ / / ___ \_/ / / ___ \_/ / / ___ \_/ / / ___ \_/ / / ___ \_
_/ / / _ \___/ / / _ \___/ / / _ \___/ / / _ \___/ / / _ \___/ / / _ \__
__/ / / \_____/ / / \_____/ / / \_____/ / / \_____/ / / \_____/ / / \___
_ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ ___ \ \ \_/ __
 \ \ \___/ _ \ \ \___/ _ \ \ \___/ _ \ \ \___/ _ \ \ \___/ _ \ \ \___/ _
\ \ \_____/ \ \ \_____/ \ \ \_____/ \ \ \_____/ \ \ \_____/ \ \ \_____/
/ / / ___ \_/ / / ___ \_/ / / ___ \_/ / / ___ \_/ / / ___ \_/ / / ___ \_
_/ / / _ \___/ / / _ \___/ / / _ \___/ / / _ \___/ / / _ \___/ / / _ \__
__/ / / \_____/ / / \_____/ / / \_____/ / / \_____/ / / \_____/ / / \___

If you find this kind of animation interesting, you can find more examples of "scrolling ASCII art" on my other website, The Scroll Art Museum.

Simple Substitution Cipher

The Simple Substitution Cipher substitutes one letter for another. Since there are 26 possible substitutions for the letter A, 25 possible substitutions for B, 24 for C, and so on, the total number of possible keys is 26 × 25 × 24 × 23 × . . . × 1, or 403,291,461,126,605,635,584,000,000 keys! That’s far too many keys for even a supercomputer to brute force, so the code-breaking method used in Project 7, “Caesar Hacker,” can’t be used against the simple cipher. Unfortunately, devious attackers can take advantage of known weakness to break the code. If you’d like to learn more about ciphers and code breaking, you can read my book Cracking Codes with Python (No Starch Press, 2018; https://nostarch.com/crackingcodes/).

For example, when the program runs it could look like this:

Do you want to (e)ncrypt or (d)ecrypt?
> e
Please specify the key to use.
Or enter RANDOM to have one generated for you.
> random
The key is WNOMTRCEHDXBFVSLKAGZIPYJQU. KEEP THIS SECRET!
Enter the message to encrypt.
> Meet me by the rose bushes tonight.
The encrypted message is:
Fttz ft nq zet asgt nigetg zsvhcez.
Full encrypted text copied to clipboard.

--snip--

Do you want to (e)ncrypt or (d)ecrypt?
> d
Please specify the key to use.
> WNOMTRCEHDXBFVSLKAGZIPYJQU
Enter the message to decrypt.
> Fttz ft nq zet asgt nigetg zsvhcez.
The decrypted message is:
Meet me by the rose bushes tonight.
Full decrypted text copied to clipboard.

Sine Message

This program displays a message of the user’s choice in a wavy pattern as the text scrolls up. It accomplishes this effect with math.sin(), which implements the trigonometric sine wave function. But even if you don’t understand the math, this program is rather short and easy to copy.

For example, when the program runs it could look like this:

What message do you want to display? (Max 39 chars.)
> I <3 Programming!
                                 I <3 Programming!
                                         I <3 Programming!
                                                I <3 Programming!
                                                       I <3 Programming!
                                                            I <3 Programming!
                                                                I <3 Programming!
                                                                 I <3 Programming!
                                                                 I <3 Programming!
                                                               I <3 Programming!
                                                          I <3 Programming!
                                                    I <3 Programming!
                                             I <3 Programming!
                                     I <3 Programming!
                             I <3 Programming!
                     I <3 Programming!
              I <3 Programming!
        I <3 Programming!
   I <3 Programming!
I <3 Programming!
I <3 Programming!
 I <3 Programming!
    I <3 Programming!
         I <3 Programming!
--snip--

Sliding Tile Puzzle

This classic puzzle relies on a 4 × 4 board with 15 numbered tiles and one free space. The objective is to slide the tiles until the numbers are in the correct order, going left to right and top to bottom. Tiles can only slide; you’re not allowed to directly pick them up and rearrange them. Some versions of this puzzle toy feature scrambled images that form a complete picture once solved.

For example, when the program runs it could look like this:

+------+------+------+------+
|      |      |      |      |
|  5   |  10  |      |  11  |
|      |      |      |      |
+------+------+------+------+
|      |      |      |      |
|  6   |  3   |  7   |  2   |
|      |      |      |      |
+------+------+------+------+
|      |      |      |      |
|  14  |  1   |  15  |  8   |
|      |      |      |      |
+------+------+------+------+
|      |      |      |      |
|  9   |  13  |  4   |  12  |
|      |      |      |      |
+------+------+------+------+

                          (W)
Enter WASD (or QUIT): (A) ( ) (D)
> w

+------+------+------+------+
|      |      |      |      |
|  5   |  10  |  7   |  11  |
|      |      |      |      |
+------+------+------+------+
|      |      |      |      |
|  6   |  3   |      |  2   |
|      |      |      |      |
+------+------+------+------+
|      |      |      |      |
|  14  |  1   |  15  |  8   |
|      |      |      |      |
+------+------+------+------+
|      |      |      |      |
|  9   |  13  |  4   |  12  |
|      |      |      |      |
+------+------+------+------+

                          (W)
Enter WASD (or QUIT): (A) (S) (D)
--snip--

Snail Race

You won’t be able to handle the fast-paced excitement of these racing... snails. But what they lack in speed they make up for in ASCII-art cuteness. Each snail (represented by an @ character for the shell and v for the two eyestalks) moves slowly but surely toward the finish line. Up to eight snails, each with a custom name, can race each other, leaving a slime trail in their wake. This program is good for beginners.

For example, when the program runs it could look like this:

Snail Race

    @v <-- snail

How many snails will race? Max: 8
> 3
Enter snail #1's name:
> Alice
Enter snail #2's name:
> Bob
Enter snail #3's name:
> Carol
START                                   FINISH
|                                       |
      Alice
......@v
     Bob
.....@v
       Carol
.......@v
--snip--

Soroban Japanese Abacus

An abacus, also called a counting frame, is a calculating tool used in many cultures long before electronic calculators were invented. The Japanese form of the abacus is called a soroban. Each wire represents a place in a positional numeral system, and the beads on the wire represent the digit at that place. For example, a soroban with two beads moved over on the rightmost wire and three beads moved over on the second-to-rightmost wire would represent the number 32. This program simulates a soroban. (The irony of using a computer to simulate a pre-computer computing tool is not lost on me.)

Each column in the soroban represents a different digit. The rightmost column is the ones place, the column to its left is the tens place, the column to the left of that is the hundreds place, and so on. The Q, W, E, R, T, Y, U, I, O, and P keys along the top of your keyboard can increase the digit at their respective positions, while the A, S, D, F, G, H, J, K, L, and ; keys will decrease them. The beads on the virtual soroban will slide to reflect the current number. You can also enter numbers directly.

The four beads below the horizontal divider are “earth” beads, and lifting them up against the divider counts as 1 for that digit. The bead above the horizontal divider is a “heaven” bead, and pulling it down against the divider counts as 5 for that digit, so pulling down one heaven bead and pulling up three earth beads in the tens column represents the number 80. More information about abacuses and how to use them can be found at https://en.wikipedia.org/wiki/Abacus.

For example, when the program runs it could look like this:

+================================+
I  O  O  O  O  O  O  O  O  O  O  I
I  |  |  |  |  |  |  |  |  |  |  I
I  |  |  |  |  |  |  |  |  |  |  I
+================================+
I  |  |  |  |  |  |  |  |  |  |  I
I  |  |  |  |  |  |  |  |  |  |  I
I  O  O  O  O  O  O  O  O  O  O  I
I  O  O  O  O  O  O  O  O  O  O  I
I  O  O  O  O  O  O  O  O  O  O  I
I  O  O  O  O  O  O  O  O  O  O  I
+==0==0==0==0==0==0==0==0==0==0==+
  +q  w  e  r  t  y  u  i  o  p
  -a  s  d  f  g  h  j  k  l  ;
(Enter a number, "quit", or a stream of up/down letters.)
> pppiiiii

+================================+
I  O  O  O  O  O  O  O  |  O  O  I
I  |  |  |  |  |  |  |  |  |  |  I
I  |  |  |  |  |  |  |  O  |  |  I
+================================+
I  |  |  |  |  |  |  |  |  |  O  I
I  |  |  |  |  |  |  |  |  |  O  I
I  O  O  O  O  O  O  O  O  O  O  I
I  O  O  O  O  O  O  O  O  O  |  I
I  O  O  O  O  O  O  O  O  O  |  I
I  O  O  O  O  O  O  O  O  O  O  I
+==0==0==0==0==0==0==0==5==0==3==+
  +q  w  e  r  t  y  u  i  o  p
  -a  s  d  f  g  h  j  k  l  ;
(Enter a number, "quit", or a stream of up/down letters.)
--snip--

Sound Mimic

Similar to the Simon electronic toy, this memorization game uses the third-party playsound module to play four different sounds, which correspond to the A, S, D, and F keys on the keyboard. As you successfully repeat the pattern the game gives you, the patterns get longer and longer. How many sounds can you hold in your short-term memory?

If you look at the code, you’ll see that the playsound.playsound() function is passed the filename of the sound to play. You can download the sound files from these URLs:

https://inventwithpython.com/soundA.wav

https://inventwithpython.com/soundS.wav

https://inventwithpython.com/soundD.wav

https://inventwithpython.com/soundF.wav

For example, when the program runs it could look like this:

Try to memorize a pattern of A S D F letters (each with its own sound)
as it gets longer and longer.
Press Enter to begin...

<screen clears>

Pattern: S

<screen clears>

Enter the pattern:
> s
Correct!

<screen clears>

Pattern: S F

<screen clears>

Enter the pattern:
> sf
Correct!

<screen clears>

Pattern: S F F

<screen clears>

Enter the pattern:
> sff
Correct!

<screen clears>

Pattern: S F F D
--snip--

sPoNgEcAsE

You’ve probably seen the “Mocking SpongeBob” meme: a picture of SpongeBob SquarePants, with a caption whose text alternates between upper- and lowercase letters to indicate sarcasm, like this: uSiNg SpOnGeBoB MeMeS dOeS NoT mAkE YoU wItTy. For some randomness, the text sometimes doesn’t alternate capitalization.

For example, when the program runs it could look like this:

eNtEr YoUr MeSsAgE:
> Using SpongeBob memes does not make you witty.

uSiNg SpOnGeBoB MeMeS dOeS NoT mAkE YoU wItTy.
(cOpIed SpOnGeTexT to ClIpbOaRd.)

Sudoku Puzzle

Sudoku is a popular puzzle game in newspapers and mobile apps. The Sudoku board is a 9 × 9 grid in which the player must place the digits 1 to 9 once, and only once, in each row, column, and 3 × 3 subgrid. The game begins with a few spaces already filled in with digits, called givens. A well-formed Sudoku puzzle will have only one possible valid solution.

For example, when the program runs it could look like this:

--snip--
   A B C   D E F   G H I
1  . . . | . . . | . . .
2  . 7 9 | . 5 . | 1 8 .
3  8 . . | . . . | . . 7
   ------+-------+------
4  . . 7 | 3 . 6 | 8 . .
5  4 5 . | 7 . 8 | . 9 6
6  . . 3 | 5 . 2 | 7 . .
   ------+-------+------
7  7 . . | . . . | . . 5
8  . 1 6 | . 3 . | 4 2 .
9  . . . | . . . | . . .

Enter a move, or RESET, NEW, UNDO, ORIGINAL, or QUIT:
(For example, a move looks like "B4 9".)
--snip--

Text To Speech Talker

This program demonstrates the use of the pyttsx3 third-party module. Any message you enter will be spoken out loud by your operating system’s text-to-speech capabilities. Although computer-generated speech is an incredibly complex branch of computer science, the pyttsx3 module provides an easy interface for it, making this small program suitable for beginners. Once you’ve learned how to use the module, you can add generated speech to your own programs.

More information about the pyttsx3 module can be found at https://pypi.org/project/pyttsx3/.

For example, when the program runs it could look like this:

Text-to-speech using the pyttsx3 module, which in turn uses
the NSSpeechSynthesizer (on macOS), SAPI5 (on Windows), or
eSpeak (on Linux) speech engines.

Enter the text to speak, or QUIT to quit.
> Hello. My name is Guido van Robot.

<computer speaks text out loud>

> quit
Thanks for playing!

Three-Card Monte

Three-card monte is a common scam played on gullible tourists and other easy marks. Three playing cards, one of which is the “red lady” Queen of Hearts, are put facedown on a cardboard box. The dealer quickly rearranges the cards and then asks the mark to pick the Queen of Hearts. But the dealer can use all sorts of tricks to hide the card or otherwise cheat, guaranteeing that the victim never wins. It’s also common for the dealer to have shills in the crowd who secretly work with the dealer but pretend to win the game (to make the victim think they too could win) or purposefully lose badly (to make the victim think they could do much better).

This program shows the three cards and then quickly describes a series of swaps. At the end, it clears the screen, and the player must pick a card. Can you keep up with the “red lady”? For the authentic three-card monte experience, you can enable the cheat feature, which causes the player to always lose, even if they select the correct card.

For example, when the program runs it could look like this:

Find the red lady (the Queen of Hearts)! Keep an eye on how
the cards move.

Here are the cards:
 ___   ___   ___
|J  | |Q  | |8  |
| ♦ | | ♥ | | ♣ |
|__J| |__Q| |__8|
Press Enter when you are ready to begin...
swapping left and middle...
swapping right and middle...
swapping middle and left...
swapping right and left...
swapping left and middle...
--snip--

<screen clears>

Which card has the Queen of Hearts? (LEFT MIDDLE RIGHT)
> middle
 ___   ___   ___
|Q  | |8  | |J  |
| ♥ | | ♣ | | ♦ |
|__Q| |__8| |__J|
You lost!
Thanks for playing, sucker!

Tic-Tac-Toe

Tic-tac-toe is a classic pencil-and-paper game played on a 3 × 3 grid. Players take turns placing their X or O marks, trying to get three in a row. Most games of tic-tac-toe end in a tie, but it is possible to outsmart your opponent if they’re not careful.

For example, when the program runs it could look like this:

Welcome to Tic-Tac-Toe!

       | |   1 2 3
      -+-+-
       | |   4 5 6
      -+-+-
       | |   7 8 9
What is X's move? (1-9)
> 1

      X| |   1 2 3
      -+-+-
       | |   4 5 6
      -+-+-
       | |   7 8 9
What is O's move? (1-9)
--snip--
      X|O|X  1 2 3
      -+-+-
      X|O|O  4 5 6
      -+-+-
      O|X|X  7 8 9
The game is a tie!
Thanks for playing!

Tower of Hanoi Puzzle

The Tower of Hanoi is a stack-moving puzzle game that features three poles on which you can stack various-sized disks. The object of the game is to move one tower of disks to another pole. However, only one disk can be moved at a time, and larger disks cannot be placed on top of smaller ones. Figuring out a certain pattern will help you solve this puzzle. Can you discover it? (Hint: Try setting the TOTAL_DISKS variable to 3 or 4 to solve an easier version first.)

For example, when the program runs it could look like this:

The Tower of Hanoi

Move the tower of disks, one disk at a time, to another tower. Larger
disks cannot rest on top of a smaller disk.

More info at https://en.wikipedia.org/wiki/Tower_of_Hanoi

     ||          ||          ||
    @_1@         ||          ||
   @@_2@@        ||          ||
  @@@_3@@@       ||          ||
 @@@@_4@@@@      ||          ||
@@@@@_5@@@@@     ||          ||
      A           B           C

Enter the letters of "from" and "to" towers, or QUIT.
(e.g. AB to moves a disk from tower A to tower B.)
> ab
     ||          ||          ||
     ||          ||          ||
   @@_2@@        ||          ||
  @@@_3@@@       ||          ||
 @@@@_4@@@@      ||          ||
@@@@@_5@@@@@    @_1@         ||
      A           B           C

Enter the letters of "from" and "to" towers, or QUIT.
(e.g. AB to moves a disk from tower A to tower B.)

--snip--

Twenty Forty Eight

Gabriele Cirulli, a web developer, invented the game 2048 in one weekend. It was inspired by Veewo Studios’ 1024 game, which in turn was inspired by Threes!, a game by the development team Sirvo. In 2048, you must merge numbers on a 4 × 4 board to clear them from the screen. Two 2s merge into a 4, two 4s merge into an 8, and so on. The game adds a new 2 to the board on each merging. The objective is to reach 2048 before the entire board fills up.

For example, when the program runs it could look like this:

--snip--
+-----+-----+-----+-----+
|     |     |     |     |
|     |     |  2  |  16 |
|     |     |     |     |
+-----+-----+-----+-----+
|     |     |     |     |
|     |  16 |  4  |  2  |
|     |     |     |     |
+-----+-----+-----+-----+
|     |     |     |     |
|  2  |     |  4  |  32 |
|     |     |     |     |
+-----+-----+-----+-----+
|     |     |     |     |
|     |     |     |  2  |
|     |     |     |     |
+-----+-----+-----+-----+

Score: 80
Enter move: (WASD or Q to quit)
--snip--

Vigenère Cipher

The Vigenère cipher, misattributed to 19th-century cryptographer Blaise de Vigenère (others had independently invented it earlier), was impossible to crack for hundreds of years. It is essentially the Caesar cipher, except it makes use of a multipart key. The so-called Vigenère key is a word, or even a random series of letters. Each letter represents a number by which to shift the letter in the message: A represents shifting a letter in the message by 0, B represents 1, C represents 2, and so on.

For example, if a Vigenère key is the word “CAT,” the C represents a shift of 2, the A represents 0, and the T represents 19. The first letter of the message gets shifted by 2, the second letter by 0, and the third letter by 19. For the fourth letter, we repeat the key of 2.

For example, when the program runs it could look like this:

The Vigenère cipher is a polyalphabetic substitution cipher that was
powerful enough to remain unbroken for centuries.
Do you want to (e)ncrypt or (d)ecrypt?

> e

Please specify the key to use.
It can be a word or any combination of letters:

> PIZZA

Enter the message to encrypt.

> Meet me by the rose bushes tonight.

Encrypted message:
Bmds mt jx sht znre qcrgeh bnmivps.
Full encrypted text copied to clipboard.

If you’d like to learn more about ciphers and code breaking, you can read my book Cracking Codes with Python (No Starch Press, 2018; https://nostarch.com/crackingcodes/).

Water Bucket Puzzle

In this solitaire puzzle game, you must use three buckets (three-liter, five-liter, and eight-liter buckets) to collect exactly four liters of water in one of the buckets. Buckets can only be emptied, completely filled, or poured into another bucket. For example, you can fill the five-liter bucket and then pour its contents into the three-liter bucket, leaving you with a full three-liter bucket and two liters of water in the five-liter bucket.

With some effort, you should be able to solve the puzzle. But can you figure out how to solve it with the minimal number of moves?

For example, when the program runs it could look like this:

Try to get 4L of water into one of these
buckets:

8|      |
7|      |
6|      |
5|      |  5|      |
4|      |  4|      |
3|      |  3|      |  3|      |
2|      |  2|      |  2|      |
1|      |  1|      |  1|      |
 +------+   +------+   +------+
    8L         5L         3L

You can:
  (F)ill the bucket
  (E)mpty the bucket
  (P)our one bucket into another
  (Q)uit
> f
Select a bucket 8, 5, 3, or QUIT:
> 5

Try to get 4L of water into one of these
buckets:

8|      |
7|      |
6|      |
5|      |  5|WWWWWW|
4|      |  4|WWWWWW|
3|      |  3|WWWWWW|  3|      |
2|      |  2|WWWWWW|  2|      |
1|      |  1|WWWWWW|  1|      |
 +------+   +------+   +------+
    8L         5L         3L
--snip--

Sonar Treasure Hunt

In Sonar Treasure Hunt, the player tries to discover the position of 3 treasure chests in the sea, and the player has only 20 sonar devices to use to find them. When placed, they give the distance to the closest chest.

For example, when the program runs it could look like this:

             1         2         3         4         5
   012345678901234567890123456789012345678901234567890123456789

 0 ~`~``~``~``~`~`~```~`~``````~```~`~~~`~~```~~`~~~~~`~~`~~~~` 0
 1 ~~~~~`~~~~~````~``~~```~``~`~`~`~``~~```~~~`~`~```~~~~`~`~~` 1
 2 ```~````~``~`~`~~~``~~`````~~``~``~``~~```~~``~~`~~~````~~`~ 2
 3 `````~~``````~`~~~~~```~~``~~~`~`~~~~~~`````~`~```~~~``~``~` 3
 4 ~~~`~~~`~`~~~``~~~`~`~``~~~~``~~~~``~~~~`~`~``~~```~``~~`~`~ 4
 5 `~``~````~`~`~~``~~~~``````~```~~~~````````~``~~~`~~``~~```` 5
 6 ~`~```~~`~~```~````````~~```~```~~~~``~~~`~`~~`~``~~~`~~`~`` 6
 7 ~`~~~```~``~```~`~```~~~~~~~`~~`~`~~~~``~```~~~`~```~``~``~` 7
 8 `~``~~`~`~~`~~`~~``~```~````~`~```~``~````~~~````~~``~~``~~` 8
 9 ~`~``~~````~~```~`~~```~~`~``~`~~``~`~`~~~~`~`~~`~`~```~~``` 9
10 `~~~~~~`~``~``~~~``~``~~~~`~``~```~`~~``~~~~~~``````~~`~``~~ 10
11 ~``~~~````~`~~`~~~`~~~``~``````~`~``~~~~`````~~~``````~`~`~~ 11
12 ~~~~~``~`~````~```~`~`~`~~`~~`~``~~~~~~~`~~```~~``~~`~~~~``` 12
13 `~~```~~````````~~~`~~~```~~~~~~~~`~~``~~`~```~`~~````~~~``~ 13
14 ```~``~`~`~``~```~`~``~`~``~~```~`~~~``~~``~```~`~~`~``````~ 14

   012345678901234567890123456789012345678901234567890123456789
             1         2         3         4         5
You have 20 sonar device(s) left. 3 treasure chest(s) remaining.
Where do you want to drop the next sonar device? (0-59 0-14) (or type quit)
25 5
             1         2         3         4         5
   012345678901234567890123456789012345678901234567890123456789

 0 ~`~``~``~``~`~`~```~`~``````~```~`~~~`~~```~~`~~~~~`~~`~~~~` 0
 1 ~~~~~`~~~~~````~``~~```~``~`~`~`~``~~```~~~`~`~```~~~~`~`~~` 1
 2 ```~````~``~`~`~~~``~~`````~~``~``~``~~```~~``~~`~~~````~~`~ 2
 3 `````~~``````~`~~~~~```~~``~~~`~`~~~~~~`````~`~```~~~``~``~` 3
 4 ~~~`~~~`~`~~~``~~~`~`~``~~~~``~~~~``~~~~`~`~``~~```~``~~`~`~ 4
 5 `~``~````~`~`~~``~~~~````5`~```~~~~````````~``~~~`~~``~~```` 5
 6 ~`~```~~`~~```~````````~~```~```~~~~``~~~`~`~~`~``~~~`~~`~`` 6
 7 ~`~~~```~``~```~`~```~~~~~~~`~~`~`~~~~``~```~~~`~```~``~``~` 7
 8 `~``~~`~`~~`~~`~~``~```~````~`~```~``~````~~~````~~``~~``~~` 8
 9 ~`~``~~````~~```~`~~```~~`~``~`~~``~`~`~~~~`~`~~`~`~```~~``` 9
10 `~~~~~~`~``~``~~~``~``~~~~`~``~```~`~~``~~~~~~``````~~`~``~~ 10
11 ~``~~~````~`~~`~~~`~~~``~``````~`~``~~~~`````~~~``````~`~`~~ 11
12 ~~~~~``~`~````~```~`~`~`~~`~~`~``~~~~~~~`~~```~~``~~`~~~~``` 12
13 `~~```~~````````~~~`~~~```~~~~~~~~`~~``~~`~```~`~~````~~~``~ 13
14 ```~``~`~`~``~```~`~``~`~``~~```~`~~~``~~``~```~`~~`~``````~ 14

This program is from Invent Your Own Computer Games with Python.

Reversegam / Reversi / Othello

Reversegam, also known as Reversi or Othello. This two-player board game is played on a grid, so we’ll use a Cartesian coordinate system with x- and y-coordinates. This AI is so good that it will probably beat you almost every time you play. (I lose whenever I play against it!)

For example, when the program runs it could look like this:

Do you want to be X or O?
x
The player will go first.
  12345678
 +--------+
1|        |1
2|        |2
3|        |3
4|   XO   |4
5|   OX   |5
6|        |6
7|        |7
8|        |8
 +--------+
  12345678
You: 2 points. Computer: 2 points.
Enter your move, "quit" to end the game, or "hints" to toggle hints.
53
  12345678
 +--------+
1|        |1
2|        |2
3|    X   |3
4|   XX   |4
5|   OX   |5
6|        |6
7|        |7
8|        |8
 +--------+
  12345678
You: 4 points. Computer: 1 points.
Press Enter to see the computer's move.

--snip--

This program is from Invent Your Own Computer Games with Python.

Transposition Cipher

The transposition cipher is more difficult to brute-force because the number of possible keys depends on the message’s length. There are many different types of transposition ciphers, including the rail fence cipher, route cipher, Myszkowski transposition cipher, and disrupted transposition cipher. This program is the columnar transposition cipher.

The transposition cipher doesn't replace characters when it encrypts them, but rather scrambles their order in such a way that can only be decrypted if you have the right key.

This program is from Cracking Codes with Python.

Transposition Cipher Hacker / English Detection

Hacking the transposition cipher is a matter of running through the many keys and finding the key that decrypts to detectable English. You'll need a program that uses a dictionary file (which you can download from the No Starch Press page for my book)

This program is from Cracking Codes with Python.

Affine Cipher

Once you learned the basics of modular arithmetic, you can create an affine cipher program. The affine cipher is similar to the Caesar cipher, but it's more complicated key generation makes it more secure. Still, it is possible to hack the affine cipher

This program is from Cracking Codes with Python.

Frequency Analysis / Vigenere Cipher Hacker

Writing programs that can determine the letter frequencies in messages is the first step towards hacking the Vigenere cipher. This approach was used by 19th-century mathematician Charles Babbage to break the previously-thought unbreakable Vigenere cipher.

This program is from Cracking Codes with Python.

Public Key Cryptography / Large Prime Number Generation

Public-key cryptography uses pairs of encryption keys. Each key pair consists of a public key and a corresponding private key. Security of public-key cryptography depends on keeping the private key secret; the public key can be openly distributed without compromising security.

You'll need to generate large prime numbers to use during key generation. While the math is a little tricky, this is how real-world cryptography works. (Though the programs you make are not suitable for actual use; they're great for a learning exercise though.)

For example, running the public key encryption keys could look like this:

Making key files...
Generating p prime...
Generating q prime...
Generating e that is relatively prime to (p-1)*(q-1)...
Calculating d that is mod inverse of e...
Public key: (210902406316700502401968491406579417405090396754616926135810621
2161161913380865678407459875355468897928072386270510720443827324671435893274
8583937496850624116776147241821152026946322876869404394483922202407821672864
2424789208131826990008473526711744296548563866768454251404951960805224682425
498975230488955908086491852116348777849536270685085446970952915640050522212
204221803744494065881010331486468305317449607027884787770315729959789994713
265311327663776167710077018340036668306612665759417207845823479903440572724
068125211002329298338718615859542093721097258263595617482450199200740185492
04468791300114315056117093, 17460230769175161021731845459236833553832403910869
129054954200373678580935247606622265764388235752176654737805849023006544732896
308685513669509917451195822611398098951306676600958889189564599581456460070270
393693277683404354811575681605990659145317074127084557233537504102479937142530
0216777273298110097435989)
Private key: (21090240631670050240196849140657941740509039675461692613581062
1216116191338086567840745987535546889792807238627051072044382732467143589327
4858393749685062411677614724182115202694632287686940439448392220240782167286
4242478920813182699000847352671174429654856386676845425140495196080522468242
5498975230488955908086491852116348777849536270685085446970952915640050522212
204221803744494065881010331486468305317449607027884787770315729959789994713
265311327663776167710077018340036668306612665759417207845823479903440572724
068125211002329298338718615859542093721097258263595617482450199200740185492
04468791300114315056117093, 47676735798137710412166884916983765043173120289416
904341295971552286870991874666099933371008075948549008551224760695942666962465
968168995404993934508399014283053710676760835948902312888639938402686187075052
360773062364162664276144965652558545331166681735980981384493349313058750259417
68372702963348445191139635826000818122373486213256488077192893119257248107794
25681884603640028673273135292831170178614206817165802812291528319562200625082
55726168047084560706359601833919317974375031636011432177696164717000025430368
26990539739057474642785416933878499897014777481407371328053001838085314443545
845219087249544663398589)
The public key is a 617 and a 309 digit number.
Writing public key to file al_sweigart_pubkey.txt...
The private key is a 617 and a 309 digit number.
Writing private key to file al_sweigart_privkey.txt...

This program is from Cracking Codes with Python.

Web version of the 1985 'Maze' book by Christopher Manson, an inspiration for Blue Prince

2025-09-11T10:00:00-04:00

I wrote some Python scripts to help me create the HTML web pages for an online version of Maze, a 1985 visual puzzle book by Christopher Manson that was a large inspiration for Blue Prince (my personal game of the year for 2025). I'm hosting it at https://inventwithpython.com/mazewebsite/

Recursive Fract-Al

2025-09-10T10:00:00-04:00

For Halloween 2024, I made a Recursive Fract-Al costume. It was literally an exponential amount of work! The idea came to me when I was writing The Recursive Book of Recursion

A Complete List of Python Tkinter Colors, Valid and Tested

2025-09-09T10:57:00-04:00

I needed a complete list of valid color names for Python's Tkinter package as part of my ButtonPad GUI framework development. The lists I found on the internet were either incomplete, buried under ads, and often just plain wrong. Here's a list of all 760 color names (valid and personally tested) for Python Tkinter.

The color names are case insensitive, meaning that 'aliceblue' and 'ALICEBLUE' both work fine. Some color names also have spaces, such as 'alice blue' but the spaces are significant: 'a lice bl ue' is not a valid color string.

Eventually, I was able to find the full list of colors in the Tcl/Tk documentation. However, even the official docs aren't perfect: there's a typo and "agua" and "crymson" are listed as colors instead of "aqua" and "crimson".

This Wellesley College CS page has a nice compact chart of all the colors.

If you want all this data as a Python list of tuples, it's available in this text box:

(
('alice blue', '#f0f8ff', (240, 248, 255)),
('AliceBlue', '#f0f8ff', (240, 248, 255)),
('antique white', '#faebd7', (250, 235, 215)),
('AntiqueWhite', '#faebd7', (250, 235, 215)),
('AntiqueWhite1', '#ffefdb', (255, 239, 219)),
('AntiqueWhite2', '#eedfcc', (238, 223, 204)),
('AntiqueWhite3', '#cdc0b0', (205, 192, 176)),
('AntiqueWhite4', '#8b8378', (139, 131, 120)),
('aqua', '#00ffff', (0, 255, 255)),
('aquamarine', '#7fffd4', (127, 255, 212)),
('aquamarine1', '#7fffd4', (127, 255, 212)),
('aquamarine2', '#76eec6', (118, 238, 198)),
('aquamarine3', '#66cdaa', (102, 205, 170)),
('aquamarine4', '#458b74', (69, 139, 116)),
('azure', '#f0ffff', (240, 255, 255)),
('azure1', '#f0ffff', (240, 255, 255)),
('azure2', '#e0eeee', (224, 238, 238)),
('azure3', '#c1cdcd', (193, 205, 205)),
('azure4', '#838b8b', (131, 139, 139)),
('beige', '#f5f5dc', (245, 245, 220)),
('bisque', '#ffe4c4', (255, 228, 196)),
('bisque1', '#ffe4c4', (255, 228, 196)),
('bisque2', '#eed5b7', (238, 213, 183)),
('bisque3', '#cdb79e', (205, 183, 158)),
('bisque4', '#8b7d6b', (139, 125, 107)),
('black', '#000000', (0, 0, 0)),
('blanched almond', '#ffebcd', (255, 235, 205)),
('BlanchedAlmond', '#ffebcd', (255, 235, 205)),
('blue', '#0000ff', (0, 0, 255)),
('blue violet', '#8a2be2', (138, 43, 226)),
('blue1', '#0000ff', (0, 0, 255)),
('blue2', '#0000ee', (0, 0, 238)),
('blue3', '#0000cd', (0, 0, 205)),
('blue4', '#00008b', (0, 0, 139)),
('BlueViolet', '#8a2be2', (138, 43, 226)),
('brown', '#a52a2a', (165, 42, 42)),
('brown1', '#ff4040', (255, 64, 64)),
('brown2', '#ee3b3b', (238, 59, 59)),
('brown3', '#cd3333', (205, 51, 51)),
('brown4', '#8b2323', (139, 35, 35)),
('burlywood', '#deb887', (222, 184, 135)),
('burlywood1', '#ffd39b', (255, 211, 155)),
('burlywood2', '#eec591', (238, 197, 145)),
('burlywood3', '#cdaa7d', (205, 170, 125)),
('burlywood4', '#8b7355', (139, 115, 85)),
('cadet blue', '#5f9ea0', (95, 158, 160)),
('CadetBlue', '#5f9ea0', (95, 158, 160)),
('CadetBlue1', '#98f5ff', (152, 245, 255)),
('CadetBlue2', '#8ee5ee', (142, 229, 238)),
('CadetBlue3', '#7ac5cd', (122, 197, 205)),
('CadetBlue4', '#53868b', (83, 134, 139)),
('chartreuse', '#7fff00', (127, 255, 0)),
('chartreuse1', '#7fff00', (127, 255, 0)),
('chartreuse2', '#76ee00', (118, 238, 0)),
('chartreuse3', '#66cd00', (102, 205, 0)),
('chartreuse4', '#458b00', (69, 139, 0)),
('chocolate', '#d2691e', (210, 105, 30)),
('chocolate1', '#ff7f24', (255, 127, 36)),
('chocolate2', '#ee7621', (238, 118, 33)),
('chocolate3', '#cd661d', (205, 102, 29)),
('chocolate4', '#8b4513', (139, 69, 19)),
('coral', '#ff7f50', (255, 127, 80)),
('coral1', '#ff7256', (255, 114, 86)),
('coral2', '#ee6a50', (238, 106, 80)),
('coral3', '#cd5b45', (205, 91, 69)),
('coral4', '#8b3e2f', (139, 62, 47)),
('cornflower blue', '#6495ed', (100, 149, 237)),
('CornflowerBlue', '#6495ed', (100, 149, 237)),
('cornsilk', '#fff8dc', (255, 248, 220)),
('cornsilk1', '#fff8dc', (255, 248, 220)),
('cornsilk2', '#eee8cd', (238, 232, 205)),
('cornsilk3', '#cdc8b1', (205, 200, 177)),
('cornsilk4', '#8b8878', (139, 136, 120)),
('crimson', '#dc143c', (220, 20, 60)),
('cyan', '#00ffff', (0, 255, 255)),
('cyan1', '#00ffff', (0, 255, 255)),
('cyan2', '#00eeee', (0, 238, 238)),
('cyan3', '#00cdcd', (0, 205, 205)),
('cyan4', '#008b8b', (0, 139, 139)),
('dark blue', '#00008b', (0, 0, 139)),
('dark cyan', '#008b8b', (0, 139, 139)),
('dark goldenrod', '#b8860b', (184, 134, 11)),
('dark gray', '#a9a9a9', (169, 169, 169)),
('dark green', '#006400', (0, 100, 0)),
('dark grey', '#a9a9a9', (169, 169, 169)),
('dark khaki', '#bdb76b', (189, 183, 107)),
('dark magenta', '#8b008b', (139, 0, 139)),
('dark olive green', '#556b2f', (85, 107, 47)),
('dark orange', '#ff8c00', (255, 140, 0)),
('dark orchid', '#9932cc', (153, 50, 204)),
('dark red', '#8b0000', (139, 0, 0)),
('dark salmon', '#e9967a', (233, 150, 122)),
('dark sea green', '#8fbc8f', (143, 188, 143)),
('dark slate blue', '#483d8b', (72, 61, 139)),
('dark slate gray', '#2f4f4f', (47, 79, 79)),
('dark slate grey', '#2f4f4f', (47, 79, 79)),
('dark turquoise', '#00ced1', (0, 206, 209)),
('dark violet', '#9400d3', (148, 0, 211)),
('DarkBlue', '#00008b', (0, 0, 139)),
('DarkCyan', '#008b8b', (0, 139, 139)),
('DarkGoldenrod', '#b8860b', (184, 134, 11)),
('DarkGoldenrod1', '#ffb90f', (255, 185, 15)),
('DarkGoldenrod2', '#eead0e', (238, 173, 14)),
('DarkGoldenrod3', '#cd950c', (205, 149, 12)),
('DarkGoldenrod4', '#8b6508', (139, 101, 8)),
('DarkGray', '#a9a9a9', (169, 169, 169)),
('DarkGreen', '#006400', (0, 100, 0)),
('DarkGrey', '#a9a9a9', (169, 169, 169)),
('DarkKhaki', '#bdb76b', (189, 183, 107)),
('DarkMagenta', '#8b008b', (139, 0, 139)),
('DarkOliveGreen', '#556b2f', (85, 107, 47)),
('DarkOliveGreen1', '#caff70', (202, 255, 112)),
('DarkOliveGreen2', '#bcee68', (188, 238, 104)),
('DarkOliveGreen3', '#a2cd5a', (162, 205, 90)),
('DarkOliveGreen4', '#6e8b3d', (110, 139, 61)),
('DarkOrange', '#ff8c00', (255, 140, 0)),
('DarkOrange1', '#ff7f00', (255, 127, 0)),
('DarkOrange2', '#ee7600', (238, 118, 0)),
('DarkOrange3', '#cd6600', (205, 102, 0)),
('DarkOrange4', '#8b4500', (139, 69, 0)),
('DarkOrchid', '#9932cc', (153, 50, 204)),
('DarkOrchid1', '#bf3eff', (191, 62, 255)),
('DarkOrchid2', '#b23aee', (178, 58, 238)),
('DarkOrchid3', '#9a32cd', (154, 50, 205)),
('DarkOrchid4', '#68228b', (104, 34, 139)),
('DarkRed', '#8b0000', (139, 0, 0)),
('DarkSalmon', '#e9967a', (233, 150, 122)),
('DarkSeaGreen', '#8fbc8f', (143, 188, 143)),
('DarkSeaGreen1', '#c1ffc1', (193, 255, 193)),
('DarkSeaGreen2', '#b4eeb4', (180, 238, 180)),
('DarkSeaGreen3', '#9bcd9b', (155, 205, 155)),
('DarkSeaGreen4', '#698b69', (105, 139, 105)),
('DarkSlateBlue', '#483d8b', (72, 61, 139)),
('DarkSlateGray', '#2f4f4f', (47, 79, 79)),
('DarkSlateGray1', '#97ffff', (151, 255, 255)),
('DarkSlateGray2', '#8deeee', (141, 238, 238)),
('DarkSlateGray3', '#79cdcd', (121, 205, 205)),
('DarkSlateGray4', '#528b8b', (82, 139, 139)),
('DarkSlateGrey', '#2f4f4f', (47, 79, 79)),
('DarkTurquoise', '#00ced1', (0, 206, 209)),
('DarkViolet', '#9400d3', (148, 0, 211)),
('deep pink', '#ff1493', (255, 20, 147)),
('deep sky blue', '#00bfff', (0, 191, 255)),
('DeepPink', '#ff1493', (255, 20, 147)),
('DeepPink1', '#ff1493', (255, 20, 147)),
('DeepPink2', '#ee1289', (238, 18, 137)),
('DeepPink3', '#cd1076', (205, 16, 118)),
('DeepPink4', '#8b0a50', (139, 10, 80)),
('DeepSkyBlue', '#00bfff', (0, 191, 255)),
('DeepSkyBlue1', '#00bfff', (0, 191, 255)),
('DeepSkyBlue2', '#00b2ee', (0, 178, 238)),
('DeepSkyBlue3', '#009acd', (0, 154, 205)),
('DeepSkyBlue4', '#00688b', (0, 104, 139)),
('dim gray', '#696969', (105, 105, 105)),
('dim grey', '#696969', (105, 105, 105)),
('DimGray', '#696969', (105, 105, 105)),
('DimGrey', '#696969', (105, 105, 105)),
('dodger blue', '#1e90ff', (30, 144, 255)),
('DodgerBlue', '#1e90ff', (30, 144, 255)),
('DodgerBlue1', '#1e90ff', (30, 144, 255)),
('DodgerBlue2', '#1c86ee', (28, 134, 238)),
('DodgerBlue3', '#1874cd', (24, 116, 205)),
('DodgerBlue4', '#104e8b', (16, 78, 139)),
('firebrick', '#b22222', (178, 34, 34)),
('firebrick1', '#ff3030', (255, 48, 48)),
('firebrick2', '#ee2c2c', (238, 44, 44)),
('firebrick3', '#cd2626', (205, 38, 38)),
('firebrick4', '#8b1a1a', (139, 26, 26)),
('floral white', '#fffaf0', (255, 250, 240)),
('FloralWhite', '#fffaf0', (255, 250, 240)),
('forest green', '#228b22', (34, 139, 34)),
('ForestGreen', '#228b22', (34, 139, 34)),
('fuchsia', '#ff00ff', (255, 0, 255)),
('gainsboro', '#dcdcdc', (220, 220, 220)),
('ghost white', '#f8f8ff', (248, 248, 255)),
('GhostWhite', '#f8f8ff', (248, 248, 255)),
('gold', '#ffd700', (255, 215, 0)),
('gold1', '#ffd700', (255, 215, 0)),
('gold2', '#eec900', (238, 201, 0)),
('gold3', '#cdad00', (205, 173, 0)),
('gold4', '#8b7500', (139, 117, 0)),
('goldenrod', '#daa520', (218, 165, 32)),
('goldenrod1', '#ffc125', (255, 193, 37)),
('goldenrod2', '#eeb422', (238, 180, 34)),
('goldenrod3', '#cd9b1d', (205, 155, 29)),
('goldenrod4', '#8b6914', (139, 105, 20)),
('gray', '#808080', (128, 128, 128)),
('gray0', '#000000', (0, 0, 0)),
('gray1', '#030303', (3, 3, 3)),
('gray2', '#050505', (5, 5, 5)),
('gray3', '#080808', (8, 8, 8)),
('gray4', '#0a0a0a', (10, 10, 10)),
('gray5', '#0d0d0d', (13, 13, 13)),
('gray6', '#0f0f0f', (15, 15, 15)),
('gray7', '#121212', (18, 18, 18)),
('gray8', '#141414', (20, 20, 20)),
('gray9', '#171717', (23, 23, 23)),
('gray10', '#1a1a1a', (26, 26, 26)),
('gray11', '#1c1c1c', (28, 28, 28)),
('gray12', '#1f1f1f', (31, 31, 31)),
('gray13', '#212121', (33, 33, 33)),
('gray14', '#242424', (36, 36, 36)),
('gray15', '#262626', (38, 38, 38)),
('gray16', '#292929', (41, 41, 41)),
('gray17', '#2b2b2b', (43, 43, 43)),
('gray18', '#2e2e2e', (46, 46, 46)),
('gray19', '#303030', (48, 48, 48)),
('gray20', '#333333', (51, 51, 51)),
('gray21', '#363636', (54, 54, 54)),
('gray22', '#383838', (56, 56, 56)),
('gray23', '#3b3b3b', (59, 59, 59)),
('gray24', '#3d3d3d', (61, 61, 61)),
('gray25', '#404040', (64, 64, 64)),
('gray26', '#424242', (66, 66, 66)),
('gray27', '#454545', (69, 69, 69)),
('gray28', '#474747', (71, 71, 71)),
('gray29', '#4a4a4a', (74, 74, 74)),
('gray30', '#4d4d4d', (77, 77, 77)),
('gray31', '#4f4f4f', (79, 79, 79)),
('gray32', '#525252', (82, 82, 82)),
('gray33', '#545454', (84, 84, 84)),
('gray34', '#575757', (87, 87, 87)),
('gray35', '#595959', (89, 89, 89)),
('gray36', '#5c5c5c', (92, 92, 92)),
('gray37', '#5e5e5e', (94, 94, 94)),
('gray38', '#616161', (97, 97, 97)),
('gray39', '#636363', (99, 99, 99)),
('gray40', '#666666', (102, 102, 102)),
('gray41', '#696969', (105, 105, 105)),
('gray42', '#6b6b6b', (107, 107, 107)),
('gray43', '#6e6e6e', (110, 110, 110)),
('gray44', '#707070', (112, 112, 112)),
('gray45', '#737373', (115, 115, 115)),
('gray46', '#757575', (117, 117, 117)),
('gray47', '#787878', (120, 120, 120)),
('gray48', '#7a7a7a', (122, 122, 122)),
('gray49', '#7d7d7d', (125, 125, 125)),
('gray50', '#7f7f7f', (127, 127, 127)),
('gray51', '#828282', (130, 130, 130)),
('gray52', '#858585', (133, 133, 133)),
('gray53', '#878787', (135, 135, 135)),
('gray54', '#8a8a8a', (138, 138, 138)),
('gray55', '#8c8c8c', (140, 140, 140)),
('gray56', '#8f8f8f', (143, 143, 143)),
('gray57', '#919191', (145, 145, 145)),
('gray58', '#949494', (148, 148, 148)),
('gray59', '#969696', (150, 150, 150)),
('gray60', '#999999', (153, 153, 153)),
('gray61', '#9c9c9c', (156, 156, 156)),
('gray62', '#9e9e9e', (158, 158, 158)),
('gray63', '#a1a1a1', (161, 161, 161)),
('gray64', '#a3a3a3', (163, 163, 163)),
('gray65', '#a6a6a6', (166, 166, 166)),
('gray66', '#a8a8a8', (168, 168, 168)),
('gray67', '#ababab', (171, 171, 171)),
('gray68', '#adadad', (173, 173, 173)),
('gray69', '#b0b0b0', (176, 176, 176)),
('gray70', '#b3b3b3', (179, 179, 179)),
('gray71', '#b5b5b5', (181, 181, 181)),
('gray72', '#b8b8b8', (184, 184, 184)),
('gray73', '#bababa', (186, 186, 186)),
('gray74', '#bdbdbd', (189, 189, 189)),
('gray75', '#bfbfbf', (191, 191, 191)),
('gray76', '#c2c2c2', (194, 194, 194)),
('gray77', '#c4c4c4', (196, 196, 196)),
('gray78', '#c7c7c7', (199, 199, 199)),
('gray79', '#c9c9c9', (201, 201, 201)),
('gray80', '#cccccc', (204, 204, 204)),
('gray81', '#cfcfcf', (207, 207, 207)),
('gray82', '#d1d1d1', (209, 209, 209)),
('gray83', '#d4d4d4', (212, 212, 212)),
('gray84', '#d6d6d6', (214, 214, 214)),
('gray85', '#d9d9d9', (217, 217, 217)),
('gray86', '#dbdbdb', (219, 219, 219)),
('gray87', '#dedede', (222, 222, 222)),
('gray88', '#e0e0e0', (224, 224, 224)),
('gray89', '#e3e3e3', (227, 227, 227)),
('gray90', '#e5e5e5', (229, 229, 229)),
('gray91', '#e8e8e8', (232, 232, 232)),
('gray92', '#ebebeb', (235, 235, 235)),
('gray93', '#ededed', (237, 237, 237)),
('gray94', '#f0f0f0', (240, 240, 240)),
('gray95', '#f2f2f2', (242, 242, 242)),
('gray96', '#f5f5f5', (245, 245, 245)),
('gray97', '#f7f7f7', (247, 247, 247)),
('gray98', '#fafafa', (250, 250, 250)),
('gray99', '#fcfcfc', (252, 252, 252)),
('gray100', '#ffffff', (255, 255, 255)),
('green', '#008000', (0, 128, 0)),
('green yellow', '#adff2f', (173, 255, 47)),
('green1', '#00ff00', (0, 255, 0)),
('green2', '#00ee00', (0, 238, 0)),
('green3', '#00cd00', (0, 205, 0)),
('green4', '#008b00', (0, 139, 0)),
('GreenYellow', '#adff2f', (173, 255, 47)),
('grey', '#808080', (128, 128, 128)),
('grey0', '#000000', (0, 0, 0)),
('grey1', '#030303', (3, 3, 3)),
('grey2', '#050505', (5, 5, 5)),
('grey3', '#080808', (8, 8, 8)),
('grey4', '#0a0a0a', (10, 10, 10)),
('grey5', '#0d0d0d', (13, 13, 13)),
('grey6', '#0f0f0f', (15, 15, 15)),
('grey7', '#121212', (18, 18, 18)),
('grey8', '#141414', (20, 20, 20)),
('grey9', '#171717', (23, 23, 23)),
('grey10', '#1a1a1a', (26, 26, 26)),
('grey11', '#1c1c1c', (28, 28, 28)),
('grey12', '#1f1f1f', (31, 31, 31)),
('grey13', '#212121', (33, 33, 33)),
('grey14', '#242424', (36, 36, 36)),
('grey15', '#262626', (38, 38, 38)),
('grey16', '#292929', (41, 41, 41)),
('grey17', '#2b2b2b', (43, 43, 43)),
('grey18', '#2e2e2e', (46, 46, 46)),
('grey19', '#303030', (48, 48, 48)),
('grey20', '#333333', (51, 51, 51)),
('grey21', '#363636', (54, 54, 54)),
('grey22', '#383838', (56, 56, 56)),
('grey23', '#3b3b3b', (59, 59, 59)),
('grey24', '#3d3d3d', (61, 61, 61)),
('grey25', '#404040', (64, 64, 64)),
('grey26', '#424242', (66, 66, 66)),
('grey27', '#454545', (69, 69, 69)),
('grey28', '#474747', (71, 71, 71)),
('grey29', '#4a4a4a', (74, 74, 74)),
('grey30', '#4d4d4d', (77, 77, 77)),
('grey31', '#4f4f4f', (79, 79, 79)),
('grey32', '#525252', (82, 82, 82)),
('grey33', '#545454', (84, 84, 84)),
('grey34', '#575757', (87, 87, 87)),
('grey35', '#595959', (89, 89, 89)),
('grey36', '#5c5c5c', (92, 92, 92)),
('grey37', '#5e5e5e', (94, 94, 94)),
('grey38', '#616161', (97, 97, 97)),
('grey39', '#636363', (99, 99, 99)),
('grey40', '#666666', (102, 102, 102)),
('grey41', '#696969', (105, 105, 105)),
('grey42', '#6b6b6b', (107, 107, 107)),
('grey43', '#6e6e6e', (110, 110, 110)),
('grey44', '#707070', (112, 112, 112)),
('grey45', '#737373', (115, 115, 115)),
('grey46', '#757575', (117, 117, 117)),
('grey47', '#787878', (120, 120, 120)),
('grey48', '#7a7a7a', (122, 122, 122)),
('grey49', '#7d7d7d', (125, 125, 125)),
('grey50', '#7f7f7f', (127, 127, 127)),
('grey51', '#828282', (130, 130, 130)),
('grey52', '#858585', (133, 133, 133)),
('grey53', '#878787', (135, 135, 135)),
('grey54', '#8a8a8a', (138, 138, 138)),
('grey55', '#8c8c8c', (140, 140, 140)),
('grey56', '#8f8f8f', (143, 143, 143)),
('grey57', '#919191', (145, 145, 145)),
('grey58', '#949494', (148, 148, 148)),
('grey59', '#969696', (150, 150, 150)),
('grey60', '#999999', (153, 153, 153)),
('grey61', '#9c9c9c', (156, 156, 156)),
('grey62', '#9e9e9e', (158, 158, 158)),
('grey63', '#a1a1a1', (161, 161, 161)),
('grey64', '#a3a3a3', (163, 163, 163)),
('grey65', '#a6a6a6', (166, 166, 166)),
('grey66', '#a8a8a8', (168, 168, 168)),
('grey67', '#ababab', (171, 171, 171)),
('grey68', '#adadad', (173, 173, 173)),
('grey69', '#b0b0b0', (176, 176, 176)),
('grey70', '#b3b3b3', (179, 179, 179)),
('grey71', '#b5b5b5', (181, 181, 181)),
('grey72', '#b8b8b8', (184, 184, 184)),
('grey73', '#bababa', (186, 186, 186)),
('grey74', '#bdbdbd', (189, 189, 189)),
('grey75', '#bfbfbf', (191, 191, 191)),
('grey76', '#c2c2c2', (194, 194, 194)),
('grey77', '#c4c4c4', (196, 196, 196)),
('grey78', '#c7c7c7', (199, 199, 199)),
('grey79', '#c9c9c9', (201, 201, 201)),
('grey80', '#cccccc', (204, 204, 204)),
('grey81', '#cfcfcf', (207, 207, 207)),
('grey82', '#d1d1d1', (209, 209, 209)),
('grey83', '#d4d4d4', (212, 212, 212)),
('grey84', '#d6d6d6', (214, 214, 214)),
('grey85', '#d9d9d9', (217, 217, 217)),
('grey86', '#dbdbdb', (219, 219, 219)),
('grey87', '#dedede', (222, 222, 222)),
('grey88', '#e0e0e0', (224, 224, 224)),
('grey89', '#e3e3e3', (227, 227, 227)),
('grey90', '#e5e5e5', (229, 229, 229)),
('grey91', '#e8e8e8', (232, 232, 232)),
('grey92', '#ebebeb', (235, 235, 235)),
('grey93', '#ededed', (237, 237, 237)),
('grey94', '#f0f0f0', (240, 240, 240)),
('grey95', '#f2f2f2', (242, 242, 242)),
('grey96', '#f5f5f5', (245, 245, 245)),
('grey97', '#f7f7f7', (247, 247, 247)),
('grey98', '#fafafa', (250, 250, 250)),
('grey99', '#fcfcfc', (252, 252, 252)),
('grey100', '#ffffff', (255, 255, 255)),
('honeydew', '#f0fff0', (240, 255, 240)),
('honeydew1', '#f0fff0', (240, 255, 240)),
('honeydew2', '#e0eee0', (224, 238, 224)),
('honeydew3', '#c1cdc1', (193, 205, 193)),
('honeydew4', '#838b83', (131, 139, 131)),
('hot pink', '#ff69b4', (255, 105, 180)),
('HotPink', '#ff69b4', (255, 105, 180)),
('HotPink1', '#ff6eb4', (255, 110, 180)),
('HotPink2', '#ee6aa7', (238, 106, 167)),
('HotPink3', '#cd6090', (205, 96, 144)),
('HotPink4', '#8b3a62', (139, 58, 98)),
('indian red', '#cd5c5c', (205, 92, 92)),
('IndianRed', '#cd5c5c', (205, 92, 92)),
('IndianRed1', '#ff6a6a', (255, 106, 106)),
('IndianRed2', '#ee6363', (238, 99, 99)),
('IndianRed3', '#cd5555', (205, 85, 85)),
('IndianRed4', '#8b3a3a', (139, 58, 58)),
('indigo', '#4b0082', (75, 0, 130)),
('ivory', '#fffff0', (255, 255, 240)),
('ivory1', '#fffff0', (255, 255, 240)),
('ivory2', '#eeeee0', (238, 238, 224)),
('ivory3', '#cdcdc1', (205, 205, 193)),
('ivory4', '#8b8b83', (139, 139, 131)),
('khaki', '#f0e68c', (240, 230, 140)),
('khaki1', '#fff68f', (255, 246, 143)),
('khaki2', '#eee685', (238, 230, 133)),
('khaki3', '#cdc673', (205, 198, 115)),
('khaki4', '#8b864e', (139, 134, 78)),
('lavender', '#e6e6fa', (230, 230, 250)),
('lavender blush', '#fff0f5', (255, 240, 245)),
('LavenderBlush', '#fff0f5', (255, 240, 245)),
('LavenderBlush1', '#fff0f5', (255, 240, 245)),
('LavenderBlush2', '#eee0e5', (238, 224, 229)),
('LavenderBlush3', '#cdc1c5', (205, 193, 197)),
('LavenderBlush4', '#8b8386', (139, 131, 134)),
('lawn green', '#7cfc00', (124, 252, 0)),
('LawnGreen', '#7cfc00', (124, 252, 0)),
('lemon chiffon', '#fffacd', (255, 250, 205)),
('LemonChiffon', '#fffacd', (255, 250, 205)),
('LemonChiffon1', '#fffacd', (255, 250, 205)),
('LemonChiffon2', '#eee9bf', (238, 233, 191)),
('LemonChiffon3', '#cdc9a5', (205, 201, 165)),
('LemonChiffon4', '#8b8970', (139, 137, 112)),
('light blue', '#add8e6', (173, 216, 230)),
('light coral', '#f08080', (240, 128, 128)),
('light cyan', '#e0ffff', (224, 255, 255)),
('light goldenrod', '#eedd82', (238, 221, 130)),
('light goldenrod yellow', '#fafad2', (250, 250, 210)),
('light gray', '#d3d3d3', (211, 211, 211)),
('light green', '#90ee90', (144, 238, 144)),
('light grey', '#d3d3d3', (211, 211, 211)),
('light pink', '#ffb6c1', (255, 182, 193)),
('light salmon', '#ffa07a', (255, 160, 122)),
('light sea green', '#20b2aa', (32, 178, 170)),
('light sky blue', '#87cefa', (135, 206, 250)),
('light slate blue', '#8470ff', (132, 112, 255)),
('light slate gray', '#778899', (119, 136, 153)),
('light slate grey', '#778899', (119, 136, 153)),
('light steel blue', '#b0c4de', (176, 196, 222)),
('light yellow', '#ffffe0', (255, 255, 224)),
('LightBlue', '#add8e6', (173, 216, 230)),
('LightBlue1', '#bfefff', (191, 239, 255)),
('LightBlue2', '#b2dfee', (178, 223, 238)),
('LightBlue3', '#9ac0cd', (154, 192, 205)),
('LightBlue4', '#68838b', (104, 131, 139)),
('LightCoral', '#f08080', (240, 128, 128)),
('LightCyan', '#e0ffff', (224, 255, 255)),
('LightCyan1', '#e0ffff', (224, 255, 255)),
('LightCyan2', '#d1eeee', (209, 238, 238)),
('LightCyan3', '#b4cdcd', (180, 205, 205)),
('LightCyan4', '#7a8b8b', (122, 139, 139)),
('LightGoldenrod', '#eedd82', (238, 221, 130)),
('LightGoldenrod1', '#ffec8b', (255, 236, 139)),
('LightGoldenrod2', '#eedc82', (238, 220, 130)),
('LightGoldenrod3', '#cdbe70', (205, 190, 112)),
('LightGoldenrod4', '#8b814c', (139, 129, 76)),
('LightGoldenrodYellow', '#fafad2', (250, 250, 210)),
('LightGray', '#d3d3d3', (211, 211, 211)),
('LightGreen', '#90ee90', (144, 238, 144)),
('LightGrey', '#d3d3d3', (211, 211, 211)),
('LightPink', '#ffb6c1', (255, 182, 193)),
('LightPink1', '#ffaeb9', (255, 174, 185)),
('LightPink2', '#eea2ad', (238, 162, 173)),
('LightPink3', '#cd8c95', (205, 140, 149)),
('LightPink4', '#8b5f65', (139, 95, 101)),
('LightSalmon', '#ffa07a', (255, 160, 122)),
('LightSalmon1', '#ffa07a', (255, 160, 122)),
('LightSalmon2', '#ee9572', (238, 149, 114)),
('LightSalmon3', '#cd8162', (205, 129, 98)),
('LightSalmon4', '#8b5742', (139, 87, 66)),
('LightSeaGreen', '#20b2aa', (32, 178, 170)),
('LightSkyBlue', '#87cefa', (135, 206, 250)),
('LightSkyBlue1', '#b0e2ff', (176, 226, 255)),
('LightSkyBlue2', '#a4d3ee', (164, 211, 238)),
('LightSkyBlue3', '#8db6cd', (141, 182, 205)),
('LightSkyBlue4', '#607b8b', (96, 123, 139)),
('LightSlateBlue', '#8470ff', (132, 112, 255)),
('LightSlateGray', '#778899', (119, 136, 153)),
('LightSlateGrey', '#778899', (119, 136, 153)),
('LightSteelBlue', '#b0c4de', (176, 196, 222)),
('LightSteelBlue1', '#cae1ff', (202, 225, 255)),
('LightSteelBlue2', '#bcd2ee', (188, 210, 238)),
('LightSteelBlue3', '#a2b5cd', (162, 181, 205)),
('LightSteelBlue4', '#6e7b8b', (110, 123, 139)),
('LightYellow', '#ffffe0', (255, 255, 224)),
('LightYellow1', '#ffffe0', (255, 255, 224)),
('LightYellow2', '#eeeed1', (238, 238, 209)),
('LightYellow3', '#cdcdb4', (205, 205, 180)),
('LightYellow4', '#8b8b7a', (139, 139, 122)),
('lime', '#00ff00', (0, 255, 0)),
('lime green', '#32cd32', (50, 205, 50)),
('LimeGreen', '#32cd32', (50, 205, 50)),
('linen', '#faf0e6', (250, 240, 230)),
('magenta', '#ff00ff', (255, 0, 255)),
('magenta1', '#ff00ff', (255, 0, 255)),
('magenta2', '#ee00ee', (238, 0, 238)),
('magenta3', '#cd00cd', (205, 0, 205)),
('magenta4', '#8b008b', (139, 0, 139)),
('maroon', '#800000', (128, 0, 0)),
('maroon1', '#ff34b3', (255, 52, 179)),
('maroon2', '#ee30a7', (238, 48, 167)),
('maroon3', '#cd2990', (205, 41, 144)),
('maroon4', '#8b1c62', (139, 28, 98)),
('medium aquamarine', '#66cdaa', (102, 205, 170)),
('medium blue', '#0000cd', (0, 0, 205)),
('medium orchid', '#ba55d3', (186, 85, 211)),
('medium purple', '#9370db', (147, 112, 219)),
('medium sea green', '#3cb371', (60, 179, 113)),
('medium slate blue', '#7b68ee', (123, 104, 238)),
('medium spring green', '#00fa9a', (0, 250, 154)),
('medium turquoise', '#48d1cc', (72, 209, 204)),
('medium violet red', '#c71585', (199, 21, 133)),
('MediumAquamarine', '#66cdaa', (102, 205, 170)),
('MediumBlue', '#0000cd', (0, 0, 205)),
('MediumOrchid', '#ba55d3', (186, 85, 211)),
('MediumOrchid1', '#e066ff', (224, 102, 255)),
('MediumOrchid2', '#d15fee', (209, 95, 238)),
('MediumOrchid3', '#b452cd', (180, 82, 205)),
('MediumOrchid4', '#7a378b', (122, 55, 139)),
('MediumPurple', '#9370db', (147, 112, 219)),
('MediumPurple1', '#ab82ff', (171, 130, 255)),
('MediumPurple2', '#9f79ee', (159, 121, 238)),
('MediumPurple3', '#8968cd', (137, 104, 205)),
('MediumPurple4', '#5d478b', (93, 71, 139)),
('MediumSeaGreen', '#3cb371', (60, 179, 113)),
('MediumSlateBlue', '#7b68ee', (123, 104, 238)),
('MediumSpringGreen', '#00fa9a', (0, 250, 154)),
('MediumTurquoise', '#48d1cc', (72, 209, 204)),
('MediumVioletRed', '#c71585', (199, 21, 133)),
('midnight blue', '#191970', (25, 25, 112)),
('MidnightBlue', '#191970', (25, 25, 112)),
('mint cream', '#f5fffa', (245, 255, 250)),
('MintCream', '#f5fffa', (245, 255, 250)),
('misty rose', '#ffe4e1', (255, 228, 225)),
('MistyRose', '#ffe4e1', (255, 228, 225)),
('MistyRose1', '#ffe4e1', (255, 228, 225)),
('MistyRose2', '#eed5d2', (238, 213, 210)),
('MistyRose3', '#cdb7b5', (205, 183, 181)),
('MistyRose4', '#8b7d7b', (139, 125, 123)),
('moccasin', '#ffe4b5', (255, 228, 181)),
('navajo white', '#ffdead', (255, 222, 173)),
('NavajoWhite', '#ffdead', (255, 222, 173)),
('NavajoWhite1', '#ffdead', (255, 222, 173)),
('NavajoWhite2', '#eecfa1', (238, 207, 161)),
('NavajoWhite3', '#cdb38b', (205, 179, 139)),
('NavajoWhite4', '#8b795e', (139, 121, 94)),
('navy', '#000080', (0, 0, 128)),
('navy blue', '#000080', (0, 0, 128)),
('NavyBlue', '#000080', (0, 0, 128)),
('old lace', '#fdf5e6', (253, 245, 230)),
('OldLace', '#fdf5e6', (253, 245, 230)),
('olive', '#808000', (128, 128, 0)),
('olive drab', '#6b8e23', (107, 142, 35)),
('OliveDrab', '#6b8e23', (107, 142, 35)),
('OliveDrab1', '#c0ff3e', (192, 255, 62)),
('OliveDrab2', '#b3ee3a', (179, 238, 58)),
('OliveDrab3', '#9acd32', (154, 205, 50)),
('OliveDrab4', '#698b22', (105, 139, 34)),
('orange', '#ffa500', (255, 165, 0)),
('orange red', '#ff4500', (255, 69, 0)),
('orange1', '#ffa500', (255, 165, 0)),
('orange2', '#ee9a00', (238, 154, 0)),
('orange3', '#cd8500', (205, 133, 0)),
('orange4', '#8b5a00', (139, 90, 0)),
('OrangeRed', '#ff4500', (255, 69, 0)),
('OrangeRed1', '#ff4500', (255, 69, 0)),
('OrangeRed2', '#ee4000', (238, 64, 0)),
('OrangeRed3', '#cd3700', (205, 55, 0)),
('OrangeRed4', '#8b2500', (139, 37, 0)),
('orchid', '#da70d6', (218, 112, 214)),
('orchid1', '#ff83fa', (255, 131, 250)),
('orchid2', '#ee7ae9', (238, 122, 233)),
('orchid3', '#cd69c9', (205, 105, 201)),
('orchid4', '#8b4789', (139, 71, 137)),
('pale goldenrod', '#eee8aa', (238, 232, 170)),
('pale green', '#98fb98', (152, 251, 152)),
('pale turquoise', '#afeeee', (175, 238, 238)),
('pale violet red', '#db7093', (219, 112, 147)),
('PaleGoldenrod', '#eee8aa', (238, 232, 170)),
('PaleGreen', '#98fb98', (152, 251, 152)),
('PaleGreen1', '#9aff9a', (154, 255, 154)),
('PaleGreen2', '#90ee90', (144, 238, 144)),
('PaleGreen3', '#7ccd7c', (124, 205, 124)),
('PaleGreen4', '#548b54', (84, 139, 84)),
('PaleTurquoise', '#afeeee', (175, 238, 238)),
('PaleTurquoise1', '#bbffff', (187, 255, 255)),
('PaleTurquoise2', '#aeeeee', (174, 238, 238)),
('PaleTurquoise3', '#96cdcd', (150, 205, 205)),
('PaleTurquoise4', '#668b8b', (102, 139, 139)),
('PaleVioletRed', '#db7093', (219, 112, 147)),
('PaleVioletRed1', '#ff82ab', (255, 130, 171)),
('PaleVioletRed2', '#ee799f', (238, 121, 159)),
('PaleVioletRed3', '#cd6889', (205, 104, 137)),
('PaleVioletRed4', '#8b475d', (139, 71, 93)),
('papaya whip', '#ffefd5', (255, 239, 213)),
('PapayaWhip', '#ffefd5', (255, 239, 213)),
('peach puff', '#ffdab9', (255, 218, 185)),
('PeachPuff', '#ffdab9', (255, 218, 185)),
('PeachPuff1', '#ffdab9', (255, 218, 185)),
('PeachPuff2', '#eecbad', (238, 203, 173)),
('PeachPuff3', '#cdaf95', (205, 175, 149)),
('PeachPuff4', '#8b7765', (139, 119, 101)),
('peru', '#cd853f', (205, 133, 63)),
('pink', '#ffc0cb', (255, 192, 203)),
('pink1', '#ffb5c5', (255, 181, 197)),
('pink2', '#eea9b8', (238, 169, 184)),
('pink3', '#cd919e', (205, 145, 158)),
('pink4', '#8b636c', (139, 99, 108)),
('plum', '#dda0dd', (221, 160, 221)),
('plum1', '#ffbbff', (255, 187, 255)),
('plum2', '#eeaeee', (238, 174, 238)),
('plum3', '#cd96cd', (205, 150, 205)),
('plum4', '#8b668b', (139, 102, 139)),
('powder blue', '#b0e0e6', (176, 224, 230)),
('PowderBlue', '#b0e0e6', (176, 224, 230)),
('purple', '#800080', (128, 0, 128)),
('purple1', '#9b30ff', (155, 48, 255)),
('purple2', '#912cee', (145, 44, 238)),
('purple3', '#7d26cd', (125, 38, 205)),
('purple4', '#551a8b', (85, 26, 139)),
('red', '#ff0000', (255, 0, 0)),
('red1', '#ff0000', (255, 0, 0)),
('red2', '#ee0000', (238, 0, 0)),
('red3', '#cd0000', (205, 0, 0)),
('red4', '#8b0000', (139, 0, 0)),
('rosy brown', '#bc8f8f', (188, 143, 143)),
('RosyBrown', '#bc8f8f', (188, 143, 143)),
('RosyBrown1', '#ffc1c1', (255, 193, 193)),
('RosyBrown2', '#eeb4b4', (238, 180, 180)),
('RosyBrown3', '#cd9b9b', (205, 155, 155)),
('RosyBrown4', '#8b6969', (139, 105, 105)),
('royal blue', '#4169e1', (65, 105, 225)),
('RoyalBlue', '#4169e1', (65, 105, 225)),
('RoyalBlue1', '#4876ff', (72, 118, 255)),
('RoyalBlue2', '#436eee', (67, 110, 238)),
('RoyalBlue3', '#3a5fcd', (58, 95, 205)),
('RoyalBlue4', '#27408b', (39, 64, 139)),
('saddle brown', '#8b4513', (139, 69, 19)),
('SaddleBrown', '#8b4513', (139, 69, 19)),
('salmon', '#fa8072', (250, 128, 114)),
('salmon1', '#ff8c69', (255, 140, 105)),
('salmon2', '#ee8262', (238, 130, 98)),
('salmon3', '#cd7054', (205, 112, 84)),
('salmon4', '#8b4c39', (139, 76, 57)),
('sandy brown', '#f4a460', (244, 164, 96)),
('SandyBrown', '#f4a460', (244, 164, 96)),
('sea green', '#2e8b57', (46, 139, 87)),
('SeaGreen', '#2e8b57', (46, 139, 87)),
('SeaGreen1', '#54ff9f', (84, 255, 159)),
('SeaGreen2', '#4eee94', (78, 238, 148)),
('SeaGreen3', '#43cd80', (67, 205, 128)),
('SeaGreen4', '#2e8b57', (46, 139, 87)),
('seashell', '#fff5ee', (255, 245, 238)),
('seashell1', '#fff5ee', (255, 245, 238)),
('seashell2', '#eee5de', (238, 229, 222)),
('seashell3', '#cdc5bf', (205, 197, 191)),
('seashell4', '#8b8682', (139, 134, 130)),
('sienna', '#a0522d', (160, 82, 45)),
('sienna1', '#ff8247', (255, 130, 71)),
('sienna2', '#ee7942', (238, 121, 66)),
('sienna3', '#cd6839', (205, 104, 57)),
('sienna4', '#8b4726', (139, 71, 38)),
('silver', '#c0c0c0', (192, 192, 192)),
('sky blue', '#87ceeb', (135, 206, 235)),
('SkyBlue', '#87ceeb', (135, 206, 235)),
('SkyBlue1', '#87ceff', (135, 206, 255)),
('SkyBlue2', '#7ec0ee', (126, 192, 238)),
('SkyBlue3', '#6ca6cd', (108, 166, 205)),
('SkyBlue4', '#4a708b', (74, 112, 139)),
('slate blue', '#6a5acd', (106, 90, 205)),
('slate gray', '#708090', (112, 128, 144)),
('slate grey', '#708090', (112, 128, 144)),
('SlateBlue', '#6a5acd', (106, 90, 205)),
('SlateBlue1', '#836fff', (131, 111, 255)),
('SlateBlue2', '#7a67ee', (122, 103, 238)),
('SlateBlue3', '#6959cd', (105, 89, 205)),
('SlateBlue4', '#473c8b', (71, 60, 139)),
('SlateGray', '#708090', (112, 128, 144)),
('SlateGray1', '#c6e2ff', (198, 226, 255)),
('SlateGray2', '#b9d3ee', (185, 211, 238)),
('SlateGray3', '#9fb6cd', (159, 182, 205)),
('SlateGray4', '#6c7b8b', (108, 123, 139)),
('SlateGrey', '#708090', (112, 128, 144)),
('snow', '#fffafa', (255, 250, 250)),
('snow1', '#fffafa', (255, 250, 250)),
('snow2', '#eee9e9', (238, 233, 233)),
('snow3', '#cdc9c9', (205, 201, 201)),
('snow4', '#8b8989', (139, 137, 137)),
('spring green', '#00ff7f', (0, 255, 127)),
('SpringGreen', '#00ff7f', (0, 255, 127)),
('SpringGreen1', '#00ff7f', (0, 255, 127)),
('SpringGreen2', '#00ee76', (0, 238, 118)),
('SpringGreen3', '#00cd66', (0, 205, 102)),
('SpringGreen4', '#008b45', (0, 139, 69)),
('steel blue', '#4682b4', (70, 130, 180)),
('SteelBlue', '#4682b4', (70, 130, 180)),
('SteelBlue1', '#63b8ff', (99, 184, 255)),
('SteelBlue2', '#5cacee', (92, 172, 238)),
('SteelBlue3', '#4f94cd', (79, 148, 205)),
('SteelBlue4', '#36648b', (54, 100, 139)),
('tan', '#d2b48c', (210, 180, 140)),
('tan1', '#ffa54f', (255, 165, 79)),
('tan2', '#ee9a49', (238, 154, 73)),
('tan3', '#cd853f', (205, 133, 63)),
('tan4', '#8b5a2b', (139, 90, 43)),
('teal', '#008080', (0, 128, 128)),
('thistle', '#d8bfd8', (216, 191, 216)),
('thistle1', '#ffe1ff', (255, 225, 255)),
('thistle2', '#eed2ee', (238, 210, 238)),
('thistle3', '#cdb5cd', (205, 181, 205)),
('thistle4', '#8b7b8b', (139, 123, 139)),
('tomato', '#ff6347', (255, 99, 71)),
('tomato1', '#ff6347', (255, 99, 71)),
('tomato2', '#ee5c42', (238, 92, 66)),
('tomato3', '#cd4f39', (205, 79, 57)),
('tomato4', '#8b3626', (139, 54, 38)),
('turquoise', '#40e0d0', (64, 224, 208)),
('turquoise1', '#00f5ff', (0, 245, 255)),
('turquoise2', '#00e5ee', (0, 229, 238)),
('turquoise3', '#00c5cd', (0, 197, 205)),
('turquoise4', '#00868b', (0, 134, 139)),
('violet', '#ee82ee', (238, 130, 238)),
('violet red', '#d02090', (208, 32, 144)),
('VioletRed', '#d02090', (208, 32, 144)),
('VioletRed1', '#ff3e96', (255, 62, 150)),
('VioletRed2', '#ee3a8c', (238, 58, 140)),
('VioletRed3', '#cd3278', (205, 50, 120)),
('VioletRed4', '#8b2252', (139, 34, 82)),
('wheat', '#f5deb3', (245, 222, 179)),
('wheat1', '#ffe7ba', (255, 231, 186)),
('wheat2', '#eed8ae', (238, 216, 174)),
('wheat3', '#cdba96', (205, 186, 150)),
('wheat4', '#8b7e66', (139, 126, 102)),
('white', '#ffffff', (255, 255, 255)),
('white smoke', '#f5f5f5', (245, 245, 245)),
('WhiteSmoke', '#f5f5f5', (245, 245, 245)),
('yellow', '#ffff00', (255, 255, 0)),
('yellow green', '#9acd32', (154, 205, 50)),
('yellow1', '#ffff00', (255, 255, 0)),
('yellow2', '#eeee00', (238, 238, 0)),
('yellow3', '#cdcd00', (205, 205, 0)),
('yellow4', '#8b8b00', (139, 139, 0)),
('YellowGreen', '#9acd32', (154, 205, 50)),
)

Here's the table of Tkinter colors:

Name	Hex	RGB
alice blue	`#f0f8ff`	`(240, 248, 255)`
AliceBlue	`#f0f8ff`	`(240, 248, 255)`
antique white	`#faebd7`	`(250, 235, 215)`
AntiqueWhite	`#faebd7`	`(250, 235, 215)`
AntiqueWhite1	`#ffefdb`	`(255, 239, 219)`
AntiqueWhite2	`#eedfcc`	`(238, 223, 204)`
AntiqueWhite3	`#cdc0b0`	`(205, 192, 176)`
AntiqueWhite4	`#8b8378`	`(139, 131, 120)`
aqua	`#00ffff`	`(0, 255, 255)`
aquamarine	`#7fffd4`	`(127, 255, 212)`
aquamarine1	`#7fffd4`	`(127, 255, 212)`
aquamarine2	`#76eec6`	`(118, 238, 198)`
aquamarine3	`#66cdaa`	`(102, 205, 170)`
aquamarine4	`#458b74`	`(69, 139, 116)`
azure	`#f0ffff`	`(240, 255, 255)`
azure1	`#f0ffff`	`(240, 255, 255)`
azure2	`#e0eeee`	`(224, 238, 238)`
azure3	`#c1cdcd`	`(193, 205, 205)`
azure4	`#838b8b`	`(131, 139, 139)`
beige	`#f5f5dc`	`(245, 245, 220)`
bisque	`#ffe4c4`	`(255, 228, 196)`
bisque1	`#ffe4c4`	`(255, 228, 196)`
bisque2	`#eed5b7`	`(238, 213, 183)`
bisque3	`#cdb79e`	`(205, 183, 158)`
bisque4	`#8b7d6b`	`(139, 125, 107)`
black	`#000000`	`(0, 0, 0)`
blanched almond	`#ffebcd`	`(255, 235, 205)`
BlanchedAlmond	`#ffebcd`	`(255, 235, 205)`
blue	`#0000ff`	`(0, 0, 255)`
blue violet	`#8a2be2`	`(138, 43, 226)`
blue1	`#0000ff`	`(0, 0, 255)`
blue2	`#0000ee`	`(0, 0, 238)`
blue3	`#0000cd`	`(0, 0, 205)`
blue4	`#00008b`	`(0, 0, 139)`
BlueViolet	`#8a2be2`	`(138, 43, 226)`
brown	`#a52a2a`	`(165, 42, 42)`
brown1	`#ff4040`	`(255, 64, 64)`
brown2	`#ee3b3b`	`(238, 59, 59)`
brown3	`#cd3333`	`(205, 51, 51)`
brown4	`#8b2323`	`(139, 35, 35)`
burlywood	`#deb887`	`(222, 184, 135)`
burlywood1	`#ffd39b`	`(255, 211, 155)`
burlywood2	`#eec591`	`(238, 197, 145)`
burlywood3	`#cdaa7d`	`(205, 170, 125)`
burlywood4	`#8b7355`	`(139, 115, 85)`
cadet blue	`#5f9ea0`	`(95, 158, 160)`
CadetBlue	`#5f9ea0`	`(95, 158, 160)`
CadetBlue1	`#98f5ff`	`(152, 245, 255)`
CadetBlue2	`#8ee5ee`	`(142, 229, 238)`
CadetBlue3	`#7ac5cd`	`(122, 197, 205)`
CadetBlue4	`#53868b`	`(83, 134, 139)`
chartreuse	`#7fff00`	`(127, 255, 0)`
chartreuse1	`#7fff00`	`(127, 255, 0)`
chartreuse2	`#76ee00`	`(118, 238, 0)`
chartreuse3	`#66cd00`	`(102, 205, 0)`
chartreuse4	`#458b00`	`(69, 139, 0)`
chocolate	`#d2691e`	`(210, 105, 30)`
chocolate1	`#ff7f24`	`(255, 127, 36)`
chocolate2	`#ee7621`	`(238, 118, 33)`
chocolate3	`#cd661d`	`(205, 102, 29)`
chocolate4	`#8b4513`	`(139, 69, 19)`
coral	`#ff7f50`	`(255, 127, 80)`
coral1	`#ff7256`	`(255, 114, 86)`
coral2	`#ee6a50`	`(238, 106, 80)`
coral3	`#cd5b45`	`(205, 91, 69)`
coral4	`#8b3e2f`	`(139, 62, 47)`
cornflower blue	`#6495ed`	`(100, 149, 237)`
CornflowerBlue	`#6495ed`	`(100, 149, 237)`
cornsilk	`#fff8dc`	`(255, 248, 220)`
cornsilk1	`#fff8dc`	`(255, 248, 220)`
cornsilk2	`#eee8cd`	`(238, 232, 205)`
cornsilk3	`#cdc8b1`	`(205, 200, 177)`
cornsilk4	`#8b8878`	`(139, 136, 120)`
crimson	`#dc143c`	`(220, 20, 60)`
cyan	`#00ffff`	`(0, 255, 255)`
cyan1	`#00ffff`	`(0, 255, 255)`
cyan2	`#00eeee`	`(0, 238, 238)`
cyan3	`#00cdcd`	`(0, 205, 205)`
cyan4	`#008b8b`	`(0, 139, 139)`
dark blue	`#00008b`	`(0, 0, 139)`
dark cyan	`#008b8b`	`(0, 139, 139)`
dark goldenrod	`#b8860b`	`(184, 134, 11)`
dark gray	`#a9a9a9`	`(169, 169, 169)`
dark green	`#006400`	`(0, 100, 0)`
dark grey	`#a9a9a9`	`(169, 169, 169)`
dark khaki	`#bdb76b`	`(189, 183, 107)`
dark magenta	`#8b008b`	`(139, 0, 139)`
dark olive green	`#556b2f`	`(85, 107, 47)`
dark orange	`#ff8c00`	`(255, 140, 0)`
dark orchid	`#9932cc`	`(153, 50, 204)`
dark red	`#8b0000`	`(139, 0, 0)`
dark salmon	`#e9967a`	`(233, 150, 122)`
dark sea green	`#8fbc8f`	`(143, 188, 143)`
dark slate blue	`#483d8b`	`(72, 61, 139)`
dark slate gray	`#2f4f4f`	`(47, 79, 79)`
dark slate grey	`#2f4f4f`	`(47, 79, 79)`
dark turquoise	`#00ced1`	`(0, 206, 209)`
dark violet	`#9400d3`	`(148, 0, 211)`
DarkBlue	`#00008b`	`(0, 0, 139)`
DarkCyan	`#008b8b`	`(0, 139, 139)`
DarkGoldenrod	`#b8860b`	`(184, 134, 11)`
DarkGoldenrod1	`#ffb90f`	`(255, 185, 15)`
DarkGoldenrod2	`#eead0e`	`(238, 173, 14)`
DarkGoldenrod3	`#cd950c`	`(205, 149, 12)`
DarkGoldenrod4	`#8b6508`	`(139, 101, 8)`
DarkGray	`#a9a9a9`	`(169, 169, 169)`
DarkGreen	`#006400`	`(0, 100, 0)`
DarkGrey	`#a9a9a9`	`(169, 169, 169)`
DarkKhaki	`#bdb76b`	`(189, 183, 107)`
DarkMagenta	`#8b008b`	`(139, 0, 139)`
DarkOliveGreen	`#556b2f`	`(85, 107, 47)`
DarkOliveGreen1	`#caff70`	`(202, 255, 112)`
DarkOliveGreen2	`#bcee68`	`(188, 238, 104)`
DarkOliveGreen3	`#a2cd5a`	`(162, 205, 90)`
DarkOliveGreen4	`#6e8b3d`	`(110, 139, 61)`
DarkOrange	`#ff8c00`	`(255, 140, 0)`
DarkOrange1	`#ff7f00`	`(255, 127, 0)`
DarkOrange2	`#ee7600`	`(238, 118, 0)`
DarkOrange3	`#cd6600`	`(205, 102, 0)`
DarkOrange4	`#8b4500`	`(139, 69, 0)`
DarkOrchid	`#9932cc`	`(153, 50, 204)`
DarkOrchid1	`#bf3eff`	`(191, 62, 255)`
DarkOrchid2	`#b23aee`	`(178, 58, 238)`
DarkOrchid3	`#9a32cd`	`(154, 50, 205)`
DarkOrchid4	`#68228b`	`(104, 34, 139)`
DarkRed	`#8b0000`	`(139, 0, 0)`
DarkSalmon	`#e9967a`	`(233, 150, 122)`
DarkSeaGreen	`#8fbc8f`	`(143, 188, 143)`
DarkSeaGreen1	`#c1ffc1`	`(193, 255, 193)`
DarkSeaGreen2	`#b4eeb4`	`(180, 238, 180)`
DarkSeaGreen3	`#9bcd9b`	`(155, 205, 155)`
DarkSeaGreen4	`#698b69`	`(105, 139, 105)`
DarkSlateBlue	`#483d8b`	`(72, 61, 139)`
DarkSlateGray	`#2f4f4f`	`(47, 79, 79)`
DarkSlateGray1	`#97ffff`	`(151, 255, 255)`
DarkSlateGray2	`#8deeee`	`(141, 238, 238)`
DarkSlateGray3	`#79cdcd`	`(121, 205, 205)`
DarkSlateGray4	`#528b8b`	`(82, 139, 139)`
DarkSlateGrey	`#2f4f4f`	`(47, 79, 79)`
DarkTurquoise	`#00ced1`	`(0, 206, 209)`
DarkViolet	`#9400d3`	`(148, 0, 211)`
deep pink	`#ff1493`	`(255, 20, 147)`
deep sky blue	`#00bfff`	`(0, 191, 255)`
DeepPink	`#ff1493`	`(255, 20, 147)`
DeepPink1	`#ff1493`	`(255, 20, 147)`
DeepPink2	`#ee1289`	`(238, 18, 137)`
DeepPink3	`#cd1076`	`(205, 16, 118)`
DeepPink4	`#8b0a50`	`(139, 10, 80)`
DeepSkyBlue	`#00bfff`	`(0, 191, 255)`
DeepSkyBlue1	`#00bfff`	`(0, 191, 255)`
DeepSkyBlue2	`#00b2ee`	`(0, 178, 238)`
DeepSkyBlue3	`#009acd`	`(0, 154, 205)`
DeepSkyBlue4	`#00688b`	`(0, 104, 139)`
dim gray	`#696969`	`(105, 105, 105)`
dim grey	`#696969`	`(105, 105, 105)`
DimGray	`#696969`	`(105, 105, 105)`
DimGrey	`#696969`	`(105, 105, 105)`
dodger blue	`#1e90ff`	`(30, 144, 255)`
DodgerBlue	`#1e90ff`	`(30, 144, 255)`
DodgerBlue1	`#1e90ff`	`(30, 144, 255)`
DodgerBlue2	`#1c86ee`	`(28, 134, 238)`
DodgerBlue3	`#1874cd`	`(24, 116, 205)`
DodgerBlue4	`#104e8b`	`(16, 78, 139)`
firebrick	`#b22222`	`(178, 34, 34)`
firebrick1	`#ff3030`	`(255, 48, 48)`
firebrick2	`#ee2c2c`	`(238, 44, 44)`
firebrick3	`#cd2626`	`(205, 38, 38)`
firebrick4	`#8b1a1a`	`(139, 26, 26)`
floral white	`#fffaf0`	`(255, 250, 240)`
FloralWhite	`#fffaf0`	`(255, 250, 240)`
forest green	`#228b22`	`(34, 139, 34)`
ForestGreen	`#228b22`	`(34, 139, 34)`
fuchsia	`#ff00ff`	`(255, 0, 255)`
gainsboro	`#dcdcdc`	`(220, 220, 220)`
ghost white	`#f8f8ff`	`(248, 248, 255)`
GhostWhite	`#f8f8ff`	`(248, 248, 255)`
gold	`#ffd700`	`(255, 215, 0)`
gold1	`#ffd700`	`(255, 215, 0)`
gold2	`#eec900`	`(238, 201, 0)`
gold3	`#cdad00`	`(205, 173, 0)`
gold4	`#8b7500`	`(139, 117, 0)`
goldenrod	`#daa520`	`(218, 165, 32)`
goldenrod1	`#ffc125`	`(255, 193, 37)`
goldenrod2	`#eeb422`	`(238, 180, 34)`
goldenrod3	`#cd9b1d`	`(205, 155, 29)`
goldenrod4	`#8b6914`	`(139, 105, 20)`
gray	`#808080`	`(128, 128, 128)`
gray0	`#000000`	`(0, 0, 0)`
gray1	`#030303`	`(3, 3, 3)`
gray2	`#050505`	`(5, 5, 5)`
gray3	`#080808`	`(8, 8, 8)`
gray4	`#0a0a0a`	`(10, 10, 10)`
gray5	`#0d0d0d`	`(13, 13, 13)`
gray6	`#0f0f0f`	`(15, 15, 15)`
gray7	`#121212`	`(18, 18, 18)`
gray8	`#141414`	`(20, 20, 20)`
gray9	`#171717`	`(23, 23, 23)`
gray10	`#1a1a1a`	`(26, 26, 26)`
gray11	`#1c1c1c`	`(28, 28, 28)`
gray12	`#1f1f1f`	`(31, 31, 31)`
gray13	`#212121`	`(33, 33, 33)`
gray14	`#242424`	`(36, 36, 36)`
gray15	`#262626`	`(38, 38, 38)`
gray16	`#292929`	`(41, 41, 41)`
gray17	`#2b2b2b`	`(43, 43, 43)`
gray18	`#2e2e2e`	`(46, 46, 46)`
gray19	`#303030`	`(48, 48, 48)`
gray20	`#333333`	`(51, 51, 51)`
gray21	`#363636`	`(54, 54, 54)`
gray22	`#383838`	`(56, 56, 56)`
gray23	`#3b3b3b`	`(59, 59, 59)`
gray24	`#3d3d3d`	`(61, 61, 61)`
gray25	`#404040`	`(64, 64, 64)`
gray26	`#424242`	`(66, 66, 66)`
gray27	`#454545`	`(69, 69, 69)`
gray28	`#474747`	`(71, 71, 71)`
gray29	`#4a4a4a`	`(74, 74, 74)`
gray30	`#4d4d4d`	`(77, 77, 77)`
gray31	`#4f4f4f`	`(79, 79, 79)`
gray32	`#525252`	`(82, 82, 82)`
gray33	`#545454`	`(84, 84, 84)`
gray34	`#575757`	`(87, 87, 87)`
gray35	`#595959`	`(89, 89, 89)`
gray36	`#5c5c5c`	`(92, 92, 92)`
gray37	`#5e5e5e`	`(94, 94, 94)`
gray38	`#616161`	`(97, 97, 97)`
gray39	`#636363`	`(99, 99, 99)`
gray40	`#666666`	`(102, 102, 102)`
gray41	`#696969`	`(105, 105, 105)`
gray42	`#6b6b6b`	`(107, 107, 107)`
gray43	`#6e6e6e`	`(110, 110, 110)`
gray44	`#707070`	`(112, 112, 112)`
gray45	`#737373`	`(115, 115, 115)`
gray46	`#757575`	`(117, 117, 117)`
gray47	`#787878`	`(120, 120, 120)`
gray48	`#7a7a7a`	`(122, 122, 122)`
gray49	`#7d7d7d`	`(125, 125, 125)`
gray50	`#7f7f7f`	`(127, 127, 127)`
gray51	`#828282`	`(130, 130, 130)`
gray52	`#858585`	`(133, 133, 133)`
gray53	`#878787`	`(135, 135, 135)`
gray54	`#8a8a8a`	`(138, 138, 138)`
gray55	`#8c8c8c`	`(140, 140, 140)`
gray56	`#8f8f8f`	`(143, 143, 143)`
gray57	`#919191`	`(145, 145, 145)`
gray58	`#949494`	`(148, 148, 148)`
gray59	`#969696`	`(150, 150, 150)`
gray60	`#999999`	`(153, 153, 153)`
gray61	`#9c9c9c`	`(156, 156, 156)`
gray62	`#9e9e9e`	`(158, 158, 158)`
gray63	`#a1a1a1`	`(161, 161, 161)`
gray64	`#a3a3a3`	`(163, 163, 163)`
gray65	`#a6a6a6`	`(166, 166, 166)`
gray66	`#a8a8a8`	`(168, 168, 168)`
gray67	`#ababab`	`(171, 171, 171)`
gray68	`#adadad`	`(173, 173, 173)`
gray69	`#b0b0b0`	`(176, 176, 176)`
gray70	`#b3b3b3`	`(179, 179, 179)`
gray71	`#b5b5b5`	`(181, 181, 181)`
gray72	`#b8b8b8`	`(184, 184, 184)`
gray73	`#bababa`	`(186, 186, 186)`
gray74	`#bdbdbd`	`(189, 189, 189)`
gray75	`#bfbfbf`	`(191, 191, 191)`
gray76	`#c2c2c2`	`(194, 194, 194)`
gray77	`#c4c4c4`	`(196, 196, 196)`
gray78	`#c7c7c7`	`(199, 199, 199)`
gray79	`#c9c9c9`	`(201, 201, 201)`
gray80	`#cccccc`	`(204, 204, 204)`
gray81	`#cfcfcf`	`(207, 207, 207)`
gray82	`#d1d1d1`	`(209, 209, 209)`
gray83	`#d4d4d4`	`(212, 212, 212)`
gray84	`#d6d6d6`	`(214, 214, 214)`
gray85	`#d9d9d9`	`(217, 217, 217)`
gray86	`#dbdbdb`	`(219, 219, 219)`
gray87	`#dedede`	`(222, 222, 222)`
gray88	`#e0e0e0`	`(224, 224, 224)`
gray89	`#e3e3e3`	`(227, 227, 227)`
gray90	`#e5e5e5`	`(229, 229, 229)`
gray91	`#e8e8e8`	`(232, 232, 232)`
gray92	`#ebebeb`	`(235, 235, 235)`
gray93	`#ededed`	`(237, 237, 237)`
gray94	`#f0f0f0`	`(240, 240, 240)`
gray95	`#f2f2f2`	`(242, 242, 242)`
gray96	`#f5f5f5`	`(245, 245, 245)`
gray97	`#f7f7f7`	`(247, 247, 247)`
gray98	`#fafafa`	`(250, 250, 250)`
gray99	`#fcfcfc`	`(252, 252, 252)`
gray100	`#ffffff`	`(255, 255, 255)`
green	`#008000`	`(0, 128, 0)`
green yellow	`#adff2f`	`(173, 255, 47)`
green1	`#00ff00`	`(0, 255, 0)`
green2	`#00ee00`	`(0, 238, 0)`
green3	`#00cd00`	`(0, 205, 0)`
green4	`#008b00`	`(0, 139, 0)`
GreenYellow	`#adff2f`	`(173, 255, 47)`
grey	`#808080`	`(128, 128, 128)`
grey0	`#000000`	`(0, 0, 0)`
grey1	`#030303`	`(3, 3, 3)`
grey2	`#050505`	`(5, 5, 5)`
grey3	`#080808`	`(8, 8, 8)`
grey4	`#0a0a0a`	`(10, 10, 10)`
grey5	`#0d0d0d`	`(13, 13, 13)`
grey6	`#0f0f0f`	`(15, 15, 15)`
grey7	`#121212`	`(18, 18, 18)`
grey8	`#141414`	`(20, 20, 20)`
grey9	`#171717`	`(23, 23, 23)`
grey10	`#1a1a1a`	`(26, 26, 26)`
grey11	`#1c1c1c`	`(28, 28, 28)`
grey12	`#1f1f1f`	`(31, 31, 31)`
grey13	`#212121`	`(33, 33, 33)`
grey14	`#242424`	`(36, 36, 36)`
grey15	`#262626`	`(38, 38, 38)`
grey16	`#292929`	`(41, 41, 41)`
grey17	`#2b2b2b`	`(43, 43, 43)`
grey18	`#2e2e2e`	`(46, 46, 46)`
grey19	`#303030`	`(48, 48, 48)`
grey20	`#333333`	`(51, 51, 51)`
grey21	`#363636`	`(54, 54, 54)`
grey22	`#383838`	`(56, 56, 56)`
grey23	`#3b3b3b`	`(59, 59, 59)`
grey24	`#3d3d3d`	`(61, 61, 61)`
grey25	`#404040`	`(64, 64, 64)`
grey26	`#424242`	`(66, 66, 66)`
grey27	`#454545`	`(69, 69, 69)`
grey28	`#474747`	`(71, 71, 71)`
grey29	`#4a4a4a`	`(74, 74, 74)`
grey30	`#4d4d4d`	`(77, 77, 77)`
grey31	`#4f4f4f`	`(79, 79, 79)`
grey32	`#525252`	`(82, 82, 82)`
grey33	`#545454`	`(84, 84, 84)`
grey34	`#575757`	`(87, 87, 87)`
grey35	`#595959`	`(89, 89, 89)`
grey36	`#5c5c5c`	`(92, 92, 92)`
grey37	`#5e5e5e`	`(94, 94, 94)`
grey38	`#616161`	`(97, 97, 97)`
grey39	`#636363`	`(99, 99, 99)`
grey40	`#666666`	`(102, 102, 102)`
grey41	`#696969`	`(105, 105, 105)`
grey42	`#6b6b6b`	`(107, 107, 107)`
grey43	`#6e6e6e`	`(110, 110, 110)`
grey44	`#707070`	`(112, 112, 112)`
grey45	`#737373`	`(115, 115, 115)`
grey46	`#757575`	`(117, 117, 117)`
grey47	`#787878`	`(120, 120, 120)`
grey48	`#7a7a7a`	`(122, 122, 122)`
grey49	`#7d7d7d`	`(125, 125, 125)`
grey50	`#7f7f7f`	`(127, 127, 127)`
grey51	`#828282`	`(130, 130, 130)`
grey52	`#858585`	`(133, 133, 133)`
grey53	`#878787`	`(135, 135, 135)`
grey54	`#8a8a8a`	`(138, 138, 138)`
grey55	`#8c8c8c`	`(140, 140, 140)`
grey56	`#8f8f8f`	`(143, 143, 143)`
grey57	`#919191`	`(145, 145, 145)`
grey58	`#949494`	`(148, 148, 148)`
grey59	`#969696`	`(150, 150, 150)`
grey60	`#999999`	`(153, 153, 153)`
grey61	`#9c9c9c`	`(156, 156, 156)`
grey62	`#9e9e9e`	`(158, 158, 158)`
grey63	`#a1a1a1`	`(161, 161, 161)`
grey64	`#a3a3a3`	`(163, 163, 163)`
grey65	`#a6a6a6`	`(166, 166, 166)`
grey66	`#a8a8a8`	`(168, 168, 168)`
grey67	`#ababab`	`(171, 171, 171)`
grey68	`#adadad`	`(173, 173, 173)`
grey69	`#b0b0b0`	`(176, 176, 176)`
grey70	`#b3b3b3`	`(179, 179, 179)`
grey71	`#b5b5b5`	`(181, 181, 181)`
grey72	`#b8b8b8`	`(184, 184, 184)`
grey73	`#bababa`	`(186, 186, 186)`
grey74	`#bdbdbd`	`(189, 189, 189)`
grey75	`#bfbfbf`	`(191, 191, 191)`
grey76	`#c2c2c2`	`(194, 194, 194)`
grey77	`#c4c4c4`	`(196, 196, 196)`
grey78	`#c7c7c7`	`(199, 199, 199)`
grey79	`#c9c9c9`	`(201, 201, 201)`
grey80	`#cccccc`	`(204, 204, 204)`
grey81	`#cfcfcf`	`(207, 207, 207)`
grey82	`#d1d1d1`	`(209, 209, 209)`
grey83	`#d4d4d4`	`(212, 212, 212)`
grey84	`#d6d6d6`	`(214, 214, 214)`
grey85	`#d9d9d9`	`(217, 217, 217)`
grey86	`#dbdbdb`	`(219, 219, 219)`
grey87	`#dedede`	`(222, 222, 222)`
grey88	`#e0e0e0`	`(224, 224, 224)`
grey89	`#e3e3e3`	`(227, 227, 227)`
grey90	`#e5e5e5`	`(229, 229, 229)`
grey91	`#e8e8e8`	`(232, 232, 232)`
grey92	`#ebebeb`	`(235, 235, 235)`
grey93	`#ededed`	`(237, 237, 237)`
grey94	`#f0f0f0`	`(240, 240, 240)`
grey95	`#f2f2f2`	`(242, 242, 242)`
grey96	`#f5f5f5`	`(245, 245, 245)`
grey97	`#f7f7f7`	`(247, 247, 247)`
grey98	`#fafafa`	`(250, 250, 250)`
grey99	`#fcfcfc`	`(252, 252, 252)`
grey100	`#ffffff`	`(255, 255, 255)`
honeydew	`#f0fff0`	`(240, 255, 240)`
honeydew1	`#f0fff0`	`(240, 255, 240)`
honeydew2	`#e0eee0`	`(224, 238, 224)`
honeydew3	`#c1cdc1`	`(193, 205, 193)`
honeydew4	`#838b83`	`(131, 139, 131)`
hot pink	`#ff69b4`	`(255, 105, 180)`
HotPink	`#ff69b4`	`(255, 105, 180)`
HotPink1	`#ff6eb4`	`(255, 110, 180)`
HotPink2	`#ee6aa7`	`(238, 106, 167)`
HotPink3	`#cd6090`	`(205, 96, 144)`
HotPink4	`#8b3a62`	`(139, 58, 98)`
indian red	`#cd5c5c`	`(205, 92, 92)`
IndianRed	`#cd5c5c`	`(205, 92, 92)`
IndianRed1	`#ff6a6a`	`(255, 106, 106)`
IndianRed2	`#ee6363`	`(238, 99, 99)`
IndianRed3	`#cd5555`	`(205, 85, 85)`
IndianRed4	`#8b3a3a`	`(139, 58, 58)`
indigo	`#4b0082`	`(75, 0, 130)`
ivory	`#fffff0`	`(255, 255, 240)`
ivory1	`#fffff0`	`(255, 255, 240)`
ivory2	`#eeeee0`	`(238, 238, 224)`
ivory3	`#cdcdc1`	`(205, 205, 193)`
ivory4	`#8b8b83`	`(139, 139, 131)`
khaki	`#f0e68c`	`(240, 230, 140)`
khaki1	`#fff68f`	`(255, 246, 143)`
khaki2	`#eee685`	`(238, 230, 133)`
khaki3	`#cdc673`	`(205, 198, 115)`
khaki4	`#8b864e`	`(139, 134, 78)`
lavender	`#e6e6fa`	`(230, 230, 250)`
lavender blush	`#fff0f5`	`(255, 240, 245)`
LavenderBlush	`#fff0f5`	`(255, 240, 245)`
LavenderBlush1	`#fff0f5`	`(255, 240, 245)`
LavenderBlush2	`#eee0e5`	`(238, 224, 229)`
LavenderBlush3	`#cdc1c5`	`(205, 193, 197)`
LavenderBlush4	`#8b8386`	`(139, 131, 134)`
lawn green	`#7cfc00`	`(124, 252, 0)`
LawnGreen	`#7cfc00`	`(124, 252, 0)`
lemon chiffon	`#fffacd`	`(255, 250, 205)`
LemonChiffon	`#fffacd`	`(255, 250, 205)`
LemonChiffon1	`#fffacd`	`(255, 250, 205)`
LemonChiffon2	`#eee9bf`	`(238, 233, 191)`
LemonChiffon3	`#cdc9a5`	`(205, 201, 165)`
LemonChiffon4	`#8b8970`	`(139, 137, 112)`
light blue	`#add8e6`	`(173, 216, 230)`
light coral	`#f08080`	`(240, 128, 128)`
light cyan	`#e0ffff`	`(224, 255, 255)`
light goldenrod	`#eedd82`	`(238, 221, 130)`
light goldenrod yellow	`#fafad2`	`(250, 250, 210)`
light gray	`#d3d3d3`	`(211, 211, 211)`
light green	`#90ee90`	`(144, 238, 144)`
light grey	`#d3d3d3`	`(211, 211, 211)`
light pink	`#ffb6c1`	`(255, 182, 193)`
light salmon	`#ffa07a`	`(255, 160, 122)`
light sea green	`#20b2aa`	`(32, 178, 170)`
light sky blue	`#87cefa`	`(135, 206, 250)`
light slate blue	`#8470ff`	`(132, 112, 255)`
light slate gray	`#778899`	`(119, 136, 153)`
light slate grey	`#778899`	`(119, 136, 153)`
light steel blue	`#b0c4de`	`(176, 196, 222)`
light yellow	`#ffffe0`	`(255, 255, 224)`
LightBlue	`#add8e6`	`(173, 216, 230)`
LightBlue1	`#bfefff`	`(191, 239, 255)`
LightBlue2	`#b2dfee`	`(178, 223, 238)`
LightBlue3	`#9ac0cd`	`(154, 192, 205)`
LightBlue4	`#68838b`	`(104, 131, 139)`
LightCoral	`#f08080`	`(240, 128, 128)`
LightCyan	`#e0ffff`	`(224, 255, 255)`
LightCyan1	`#e0ffff`	`(224, 255, 255)`
LightCyan2	`#d1eeee`	`(209, 238, 238)`
LightCyan3	`#b4cdcd`	`(180, 205, 205)`
LightCyan4	`#7a8b8b`	`(122, 139, 139)`
LightGoldenrod	`#eedd82`	`(238, 221, 130)`
LightGoldenrod1	`#ffec8b`	`(255, 236, 139)`
LightGoldenrod2	`#eedc82`	`(238, 220, 130)`
LightGoldenrod3	`#cdbe70`	`(205, 190, 112)`
LightGoldenrod4	`#8b814c`	`(139, 129, 76)`
LightGoldenrodYellow	`#fafad2`	`(250, 250, 210)`
LightGray	`#d3d3d3`	`(211, 211, 211)`
LightGreen	`#90ee90`	`(144, 238, 144)`
LightGrey	`#d3d3d3`	`(211, 211, 211)`
LightPink	`#ffb6c1`	`(255, 182, 193)`
LightPink1	`#ffaeb9`	`(255, 174, 185)`
LightPink2	`#eea2ad`	`(238, 162, 173)`
LightPink3	`#cd8c95`	`(205, 140, 149)`
LightPink4	`#8b5f65`	`(139, 95, 101)`
LightSalmon	`#ffa07a`	`(255, 160, 122)`
LightSalmon1	`#ffa07a`	`(255, 160, 122)`
LightSalmon2	`#ee9572`	`(238, 149, 114)`
LightSalmon3	`#cd8162`	`(205, 129, 98)`
LightSalmon4	`#8b5742`	`(139, 87, 66)`
LightSeaGreen	`#20b2aa`	`(32, 178, 170)`
LightSkyBlue	`#87cefa`	`(135, 206, 250)`
LightSkyBlue1	`#b0e2ff`	`(176, 226, 255)`
LightSkyBlue2	`#a4d3ee`	`(164, 211, 238)`
LightSkyBlue3	`#8db6cd`	`(141, 182, 205)`
LightSkyBlue4	`#607b8b`	`(96, 123, 139)`
LightSlateBlue	`#8470ff`	`(132, 112, 255)`
LightSlateGray	`#778899`	`(119, 136, 153)`
LightSlateGrey	`#778899`	`(119, 136, 153)`
LightSteelBlue	`#b0c4de`	`(176, 196, 222)`
LightSteelBlue1	`#cae1ff`	`(202, 225, 255)`
LightSteelBlue2	`#bcd2ee`	`(188, 210, 238)`
LightSteelBlue3	`#a2b5cd`	`(162, 181, 205)`
LightSteelBlue4	`#6e7b8b`	`(110, 123, 139)`
LightYellow	`#ffffe0`	`(255, 255, 224)`
LightYellow1	`#ffffe0`	`(255, 255, 224)`
LightYellow2	`#eeeed1`	`(238, 238, 209)`
LightYellow3	`#cdcdb4`	`(205, 205, 180)`
LightYellow4	`#8b8b7a`	`(139, 139, 122)`
lime	`#00ff00`	`(0, 255, 0)`
lime green	`#32cd32`	`(50, 205, 50)`
LimeGreen	`#32cd32`	`(50, 205, 50)`
linen	`#faf0e6`	`(250, 240, 230)`
magenta	`#ff00ff`	`(255, 0, 255)`
magenta1	`#ff00ff`	`(255, 0, 255)`
magenta2	`#ee00ee`	`(238, 0, 238)`
magenta3	`#cd00cd`	`(205, 0, 205)`
magenta4	`#8b008b`	`(139, 0, 139)`
maroon	`#800000`	`(128, 0, 0)`
maroon1	`#ff34b3`	`(255, 52, 179)`
maroon2	`#ee30a7`	`(238, 48, 167)`
maroon3	`#cd2990`	`(205, 41, 144)`
maroon4	`#8b1c62`	`(139, 28, 98)`
medium aquamarine	`#66cdaa`	`(102, 205, 170)`
medium blue	`#0000cd`	`(0, 0, 205)`
medium orchid	`#ba55d3`	`(186, 85, 211)`
medium purple	`#9370db`	`(147, 112, 219)`
medium sea green	`#3cb371`	`(60, 179, 113)`
medium slate blue	`#7b68ee`	`(123, 104, 238)`
medium spring green	`#00fa9a`	`(0, 250, 154)`
medium turquoise	`#48d1cc`	`(72, 209, 204)`
medium violet red	`#c71585`	`(199, 21, 133)`
MediumAquamarine	`#66cdaa`	`(102, 205, 170)`
MediumBlue	`#0000cd`	`(0, 0, 205)`
MediumOrchid	`#ba55d3`	`(186, 85, 211)`
MediumOrchid1	`#e066ff`	`(224, 102, 255)`
MediumOrchid2	`#d15fee`	`(209, 95, 238)`
MediumOrchid3	`#b452cd`	`(180, 82, 205)`
MediumOrchid4	`#7a378b`	`(122, 55, 139)`
MediumPurple	`#9370db`	`(147, 112, 219)`
MediumPurple1	`#ab82ff`	`(171, 130, 255)`
MediumPurple2	`#9f79ee`	`(159, 121, 238)`
MediumPurple3	`#8968cd`	`(137, 104, 205)`
MediumPurple4	`#5d478b`	`(93, 71, 139)`
MediumSeaGreen	`#3cb371`	`(60, 179, 113)`
MediumSlateBlue	`#7b68ee`	`(123, 104, 238)`
MediumSpringGreen	`#00fa9a`	`(0, 250, 154)`
MediumTurquoise	`#48d1cc`	`(72, 209, 204)`
MediumVioletRed	`#c71585`	`(199, 21, 133)`
midnight blue	`#191970`	`(25, 25, 112)`
MidnightBlue	`#191970`	`(25, 25, 112)`
mint cream	`#f5fffa`	`(245, 255, 250)`
MintCream	`#f5fffa`	`(245, 255, 250)`
misty rose	`#ffe4e1`	`(255, 228, 225)`
MistyRose	`#ffe4e1`	`(255, 228, 225)`
MistyRose1	`#ffe4e1`	`(255, 228, 225)`
MistyRose2	`#eed5d2`	`(238, 213, 210)`
MistyRose3	`#cdb7b5`	`(205, 183, 181)`
MistyRose4	`#8b7d7b`	`(139, 125, 123)`
moccasin	`#ffe4b5`	`(255, 228, 181)`
navajo white	`#ffdead`	`(255, 222, 173)`
NavajoWhite	`#ffdead`	`(255, 222, 173)`
NavajoWhite1	`#ffdead`	`(255, 222, 173)`
NavajoWhite2	`#eecfa1`	`(238, 207, 161)`
NavajoWhite3	`#cdb38b`	`(205, 179, 139)`
NavajoWhite4	`#8b795e`	`(139, 121, 94)`
navy	`#000080`	`(0, 0, 128)`
navy blue	`#000080`	`(0, 0, 128)`
NavyBlue	`#000080`	`(0, 0, 128)`
old lace	`#fdf5e6`	`(253, 245, 230)`
OldLace	`#fdf5e6`	`(253, 245, 230)`
olive	`#808000`	`(128, 128, 0)`
olive drab	`#6b8e23`	`(107, 142, 35)`
OliveDrab	`#6b8e23`	`(107, 142, 35)`
OliveDrab1	`#c0ff3e`	`(192, 255, 62)`
OliveDrab2	`#b3ee3a`	`(179, 238, 58)`
OliveDrab3	`#9acd32`	`(154, 205, 50)`
OliveDrab4	`#698b22`	`(105, 139, 34)`
orange	`#ffa500`	`(255, 165, 0)`
orange red	`#ff4500`	`(255, 69, 0)`
orange1	`#ffa500`	`(255, 165, 0)`
orange2	`#ee9a00`	`(238, 154, 0)`
orange3	`#cd8500`	`(205, 133, 0)`
orange4	`#8b5a00`	`(139, 90, 0)`
OrangeRed	`#ff4500`	`(255, 69, 0)`
OrangeRed1	`#ff4500`	`(255, 69, 0)`
OrangeRed2	`#ee4000`	`(238, 64, 0)`
OrangeRed3	`#cd3700`	`(205, 55, 0)`
OrangeRed4	`#8b2500`	`(139, 37, 0)`
orchid	`#da70d6`	`(218, 112, 214)`
orchid1	`#ff83fa`	`(255, 131, 250)`
orchid2	`#ee7ae9`	`(238, 122, 233)`
orchid3	`#cd69c9`	`(205, 105, 201)`
orchid4	`#8b4789`	`(139, 71, 137)`
pale goldenrod	`#eee8aa`	`(238, 232, 170)`
pale green	`#98fb98`	`(152, 251, 152)`
pale turquoise	`#afeeee`	`(175, 238, 238)`
pale violet red	`#db7093`	`(219, 112, 147)`
PaleGoldenrod	`#eee8aa`	`(238, 232, 170)`
PaleGreen	`#98fb98`	`(152, 251, 152)`
PaleGreen1	`#9aff9a`	`(154, 255, 154)`
PaleGreen2	`#90ee90`	`(144, 238, 144)`
PaleGreen3	`#7ccd7c`	`(124, 205, 124)`
PaleGreen4	`#548b54`	`(84, 139, 84)`
PaleTurquoise	`#afeeee`	`(175, 238, 238)`
PaleTurquoise1	`#bbffff`	`(187, 255, 255)`
PaleTurquoise2	`#aeeeee`	`(174, 238, 238)`
PaleTurquoise3	`#96cdcd`	`(150, 205, 205)`
PaleTurquoise4	`#668b8b`	`(102, 139, 139)`
PaleVioletRed	`#db7093`	`(219, 112, 147)`
PaleVioletRed1	`#ff82ab`	`(255, 130, 171)`
PaleVioletRed2	`#ee799f`	`(238, 121, 159)`
PaleVioletRed3	`#cd6889`	`(205, 104, 137)`
PaleVioletRed4	`#8b475d`	`(139, 71, 93)`
papaya whip	`#ffefd5`	`(255, 239, 213)`
PapayaWhip	`#ffefd5`	`(255, 239, 213)`
peach puff	`#ffdab9`	`(255, 218, 185)`
PeachPuff	`#ffdab9`	`(255, 218, 185)`
PeachPuff1	`#ffdab9`	`(255, 218, 185)`
PeachPuff2	`#eecbad`	`(238, 203, 173)`
PeachPuff3	`#cdaf95`	`(205, 175, 149)`
PeachPuff4	`#8b7765`	`(139, 119, 101)`
peru	`#cd853f`	`(205, 133, 63)`
pink	`#ffc0cb`	`(255, 192, 203)`
pink1	`#ffb5c5`	`(255, 181, 197)`
pink2	`#eea9b8`	`(238, 169, 184)`
pink3	`#cd919e`	`(205, 145, 158)`
pink4	`#8b636c`	`(139, 99, 108)`
plum	`#dda0dd`	`(221, 160, 221)`
plum1	`#ffbbff`	`(255, 187, 255)`
plum2	`#eeaeee`	`(238, 174, 238)`
plum3	`#cd96cd`	`(205, 150, 205)`
plum4	`#8b668b`	`(139, 102, 139)`
powder blue	`#b0e0e6`	`(176, 224, 230)`
PowderBlue	`#b0e0e6`	`(176, 224, 230)`
purple	`#800080`	`(128, 0, 128)`
purple1	`#9b30ff`	`(155, 48, 255)`
purple2	`#912cee`	`(145, 44, 238)`
purple3	`#7d26cd`	`(125, 38, 205)`
purple4	`#551a8b`	`(85, 26, 139)`
red	`#ff0000`	`(255, 0, 0)`
red1	`#ff0000`	`(255, 0, 0)`
red2	`#ee0000`	`(238, 0, 0)`
red3	`#cd0000`	`(205, 0, 0)`
red4	`#8b0000`	`(139, 0, 0)`
rosy brown	`#bc8f8f`	`(188, 143, 143)`
RosyBrown	`#bc8f8f`	`(188, 143, 143)`
RosyBrown1	`#ffc1c1`	`(255, 193, 193)`
RosyBrown2	`#eeb4b4`	`(238, 180, 180)`
RosyBrown3	`#cd9b9b`	`(205, 155, 155)`
RosyBrown4	`#8b6969`	`(139, 105, 105)`
royal blue	`#4169e1`	`(65, 105, 225)`
RoyalBlue	`#4169e1`	`(65, 105, 225)`
RoyalBlue1	`#4876ff`	`(72, 118, 255)`
RoyalBlue2	`#436eee`	`(67, 110, 238)`
RoyalBlue3	`#3a5fcd`	`(58, 95, 205)`
RoyalBlue4	`#27408b`	`(39, 64, 139)`
saddle brown	`#8b4513`	`(139, 69, 19)`
SaddleBrown	`#8b4513`	`(139, 69, 19)`
salmon	`#fa8072`	`(250, 128, 114)`
salmon1	`#ff8c69`	`(255, 140, 105)`
salmon2	`#ee8262`	`(238, 130, 98)`
salmon3	`#cd7054`	`(205, 112, 84)`
salmon4	`#8b4c39`	`(139, 76, 57)`
sandy brown	`#f4a460`	`(244, 164, 96)`
SandyBrown	`#f4a460`	`(244, 164, 96)`
sea green	`#2e8b57`	`(46, 139, 87)`
SeaGreen	`#2e8b57`	`(46, 139, 87)`
SeaGreen1	`#54ff9f`	`(84, 255, 159)`
SeaGreen2	`#4eee94`	`(78, 238, 148)`
SeaGreen3	`#43cd80`	`(67, 205, 128)`
SeaGreen4	`#2e8b57`	`(46, 139, 87)`
seashell	`#fff5ee`	`(255, 245, 238)`
seashell1	`#fff5ee`	`(255, 245, 238)`
seashell2	`#eee5de`	`(238, 229, 222)`
seashell3	`#cdc5bf`	`(205, 197, 191)`
seashell4	`#8b8682`	`(139, 134, 130)`
sienna	`#a0522d`	`(160, 82, 45)`
sienna1	`#ff8247`	`(255, 130, 71)`
sienna2	`#ee7942`	`(238, 121, 66)`
sienna3	`#cd6839`	`(205, 104, 57)`
sienna4	`#8b4726`	`(139, 71, 38)`
silver	`#c0c0c0`	`(192, 192, 192)`
sky blue	`#87ceeb`	`(135, 206, 235)`
SkyBlue	`#87ceeb`	`(135, 206, 235)`
SkyBlue1	`#87ceff`	`(135, 206, 255)`
SkyBlue2	`#7ec0ee`	`(126, 192, 238)`
SkyBlue3	`#6ca6cd`	`(108, 166, 205)`
SkyBlue4	`#4a708b`	`(74, 112, 139)`
slate blue	`#6a5acd`	`(106, 90, 205)`
slate gray	`#708090`	`(112, 128, 144)`
slate grey	`#708090`	`(112, 128, 144)`
SlateBlue	`#6a5acd`	`(106, 90, 205)`
SlateBlue1	`#836fff`	`(131, 111, 255)`
SlateBlue2	`#7a67ee`	`(122, 103, 238)`
SlateBlue3	`#6959cd`	`(105, 89, 205)`
SlateBlue4	`#473c8b`	`(71, 60, 139)`
SlateGray	`#708090`	`(112, 128, 144)`
SlateGray1	`#c6e2ff`	`(198, 226, 255)`
SlateGray2	`#b9d3ee`	`(185, 211, 238)`
SlateGray3	`#9fb6cd`	`(159, 182, 205)`
SlateGray4	`#6c7b8b`	`(108, 123, 139)`
SlateGrey	`#708090`	`(112, 128, 144)`
snow	`#fffafa`	`(255, 250, 250)`
snow1	`#fffafa`	`(255, 250, 250)`
snow2	`#eee9e9`	`(238, 233, 233)`
snow3	`#cdc9c9`	`(205, 201, 201)`
snow4	`#8b8989`	`(139, 137, 137)`
spring green	`#00ff7f`	`(0, 255, 127)`
SpringGreen	`#00ff7f`	`(0, 255, 127)`
SpringGreen1	`#00ff7f`	`(0, 255, 127)`
SpringGreen2	`#00ee76`	`(0, 238, 118)`
SpringGreen3	`#00cd66`	`(0, 205, 102)`
SpringGreen4	`#008b45`	`(0, 139, 69)`
steel blue	`#4682b4`	`(70, 130, 180)`
SteelBlue	`#4682b4`	`(70, 130, 180)`
SteelBlue1	`#63b8ff`	`(99, 184, 255)`
SteelBlue2	`#5cacee`	`(92, 172, 238)`
SteelBlue3	`#4f94cd`	`(79, 148, 205)`
SteelBlue4	`#36648b`	`(54, 100, 139)`
tan	`#d2b48c`	`(210, 180, 140)`
tan1	`#ffa54f`	`(255, 165, 79)`
tan2	`#ee9a49`	`(238, 154, 73)`
tan3	`#cd853f`	`(205, 133, 63)`
tan4	`#8b5a2b`	`(139, 90, 43)`
teal	`#008080`	`(0, 128, 128)`
thistle	`#d8bfd8`	`(216, 191, 216)`
thistle1	`#ffe1ff`	`(255, 225, 255)`
thistle2	`#eed2ee`	`(238, 210, 238)`
thistle3	`#cdb5cd`	`(205, 181, 205)`
thistle4	`#8b7b8b`	`(139, 123, 139)`
tomato	`#ff6347`	`(255, 99, 71)`
tomato1	`#ff6347`	`(255, 99, 71)`
tomato2	`#ee5c42`	`(238, 92, 66)`
tomato3	`#cd4f39`	`(205, 79, 57)`
tomato4	`#8b3626`	`(139, 54, 38)`
turquoise	`#40e0d0`	`(64, 224, 208)`
turquoise1	`#00f5ff`	`(0, 245, 255)`
turquoise2	`#00e5ee`	`(0, 229, 238)`
turquoise3	`#00c5cd`	`(0, 197, 205)`
turquoise4	`#00868b`	`(0, 134, 139)`
violet	`#ee82ee`	`(238, 130, 238)`
violet red	`#d02090`	`(208, 32, 144)`
VioletRed	`#d02090`	`(208, 32, 144)`
VioletRed1	`#ff3e96`	`(255, 62, 150)`
VioletRed2	`#ee3a8c`	`(238, 58, 140)`
VioletRed3	`#cd3278`	`(205, 50, 120)`
VioletRed4	`#8b2252`	`(139, 34, 82)`
wheat	`#f5deb3`	`(245, 222, 179)`
wheat1	`#ffe7ba`	`(255, 231, 186)`
wheat2	`#eed8ae`	`(238, 216, 174)`
wheat3	`#cdba96`	`(205, 186, 150)`
wheat4	`#8b7e66`	`(139, 126, 102)`
white	`#ffffff`	`(255, 255, 255)`
white smoke	`#f5f5f5`	`(245, 245, 245)`
WhiteSmoke	`#f5f5f5`	`(245, 245, 245)`
yellow	`#ffff00`	`(255, 255, 0)`
yellow green	`#9acd32`	`(154, 205, 50)`
yellow1	`#ffff00`	`(255, 255, 0)`
yellow2	`#eeee00`	`(238, 238, 0)`
yellow3	`#cdcd00`	`(205, 205, 0)`
yellow4	`#8b8b00`	`(139, 139, 0)`
YellowGreen	`#9acd32`	`(154, 205, 50)`

Vibe Coding Experiment Failures

2025-08-20T10:00:00-04:00

Over the past week I've been experimenting with vibe coding: asking LLMs such as ChatGPT, Claude, and Gemini write entire apps as if I had absolutely no programming ability at all. LLMs can easily solve programming challenges or interview questions. But I wanted to see how far the current LLMs can go when asked to make complete apps, and what kinds of failure patterns emerge. From the role of a non-programmer, I would only be able to fix bugs by describing them to the LLM. For simplicity, I choose small apps written in Python that use only the standard library and the tkinter package for the GUI. This blog post details the failures: the kinds of apps that AI just isn't capable of making.

I'll update this blog post as I find new examples.

I don't care about polished or beautiful user interfaces (they are restricted to using tkinter after all.) I want to know if the generated app actually works without significant errors. For these experiments I'm using ChatGPT 5, Gemini 2.5 Pro, and Claude Sonnet 4.

I've included the source for some of the programs that the LLMs produced. If you do manage to get a working version of any of these ideas, I'd love to hear about the results: al@inventwithpython.com.

Failure Patterns in LLM-Generated Apps

LLMs tended to fail to create software with these qualities:

Slightly unusual. Any app that hasn't been implement hundreds of times before (Tetris, stopwatch, to-do list, etc.)
Require spacial or visual qualities. LLMs generate text, but dealing with coordinates or drawing tended to fall apart.
Similar but not identical to common apps. When asked to create pinball, it would create pong. When asked to create the amorphous blobs of a lava lamp, it draws perfect circles. LLMs would regress to common but inaccurate examples, sometimes even in spite of specifric instructions not to.

African Countries Geography Quiz

Prompt: "Create a Python program using tkinter for the GUI and only uses the packages in the Python standard library. The app displays a simple map of Africa that doesn’t have country borders. It’s just the outline of Africa. It prompts the user with the name of a random African country, then user must click on the map. The app shows the outline of the country on the map for a few seconds, and then prompts the user with another random country name. To keep it simple, there is no score or points. The app doesn’t acknowledge if the user clicked within the borders of the country or not. (They can see this for themselves when the country outline appears.) To keep it simple, there is no stopping point. The geography quiz continues until the user closes the app’s window."

Result: LLMs keep forgetting that Madagascar is part of Africa unless you remind them. Also, LLMs seem to think that Africa is shaped like a potato.

I was hoping for something similar to this geography quiz that shows Africa without country borders, then asks the user to click on a given country.

One of the LLMs got something approximate to Africa, and it also drew Madagascar (after I reminded it that Madagascar is part of Africa.) The shapes of countries are not... accurate. I instructed them to do web searches for SVG files of maps of Africa. They said they did, and then would draw another potato.

fail_africa_1.py

fail_africa_2.py

fail_africa_3.py

Pinball Game

Prompt: "Create a simple pinball game in Python using tkinter or turtle and only the standard library."

Result: Invariably the LLMs wanted to give me a pong game with a ball that moved at a constant speed. I had to add additional details telling it to not make pong, to have two flippers, to have realistic gravity, and the sides should funnel the ball towards the flippers. The LLMs didn't implement collision detection and left the pinball field blank. I wasn't expecting Space Cadet Pinball, but no amount of re-prompting created anything remotely acceptable. I also tried creating examples that use Pygame, just in case tkinter was too limiting of a factor.

In one case, the left flipper was incorrectly positioned but flipped the correct way, while the right flipper was correctly positioned but flipped the wrong way.

fail_pinball_1.py (uses Pygame)

Circular Maze Generator

Prompt: "Write a Python program that only uses tkinter and the standard library to generate a picture of a circle-shaped maze. The walls and boundaries of the maze should not be straight lines or rectangles. The player starts in the center and must reach the exit at the top. The player uses the keyboard arrow keys to move, and must not be able to walk through walls."

Result: LLMs can easily generate rectangular mazes programs. However, the circular mazes they made were crude fascimiles: the walls were sprinkled randomly with unreachable areas and obvious, almost straight line paths. Sometimes the LLM would write a program that for all its code simply displayed a blank window. And the keyboard controls were completely broken and unfixable.

Interactive Chinese Abacus

Prompt: "Create a Python program that uses only tkinter and the standard library to create an interactive abacus. The user can click on beads to slide them around. There should be both "heaven" and "earth" beads. The number represented by the abacus's configuration should be displayed at the bottom of the window."

Result: The LLMs made programs that displayed an abacus, but the sliding behavior of the beads would invariably be broken. The wrong beads would slide when clicked and couldn't slide back to their original position. The display number would be completely off and sometimes negative.

fail_abacus_1.py

fail_abacus_2.py

fail_abacus_3.py

Combination Lock Simulator

Prompt: "Create a Python program that uses only tkinter and the standard library. The program is a combination lock simulator. The program displays a combination lock and and lets the user drag the mouse to spin the dial. The combination is displayed at the top. If the user has correctly entered the combination, when they click the latch the latch will pop open. The window should display instructions to the user on how to use the app to open the lock."

Result: While the programs would display a rudimentary combination lock and dial with numbers, turning the dial was haphazard. The dial numbers would always be upright as the dial turned, but I didn't require that they be rotated correctly. Entering the combination was impossible, and even when I entered the correct numbers, clicking the latch button had no effect.

fail_combo_1.py

fail_combo_2.py

fail_combo_3.py

Family Tree Diagram Editor

Prompt: "Create a Python program that uses only tkinter and the standard library. Create a family tree diagram app. The program uses squares with text names to represent people. The program begins with a single square. You can click on squares to edit the name, add a spouse, add a child, add a parent, or delete the person. The diagram automatically redraws itself as people are added or deleted. Use the standard lines of a family tree diagram."

Result: Completely broken. The window would display the starting person square and some of the generated apps let me edit the name. But adding any relations would either do nothing or completely break/make invisible the existing diagram. It was never able to draw a second square.

fail_familytree_1.py

fail_familytree_2.py

fail_familytree_3.py

Lava Lamp Simulator

Prompt: "Create a Python program that only uses tkinter and the standard library. The program should be a lava lamp simulator that shows blobs gently floating around the window. Do not use circles, ellipses, or polygons for the blobs. Use bezier curves for the blob shapes. The blobs should slowly combine and separate like they do in a lava lamp."

Result: These looked nothing like lava lamps. The programs would display shapes that move, but that's all. They would bluntly combine together as they came close, with one blob disappearing and the other immediately increasing in size. The blobs would never separate; some apps had small blobs spontaneously generate out of thin air. The blobs tended to vibrate like nervous Chihuahuas.

One of the LLMs just drew blob outlines.

fail_lavalamp_1.py

fail_lavalamp_2.py

Snow Globe Simulator

Prompt: "Create a Python program that uses only tkinter and the standard library. The program is a "snow globe" with a blue background and white "snow" in it. When the window is moved around and "shook", the snow should also move around in it the way it would in a snow globe. Shaking the window faster causes the snow to move faster. The snow flakes should swirl inside the window rather than move like bouncing ping pong balls."

Result: Claude had some limited success; moving the window would "shake" the snow flakes but their behavior was more like ping pong balls in a cardboard box than snow flakes in a snow globe. The speed and vigor I shook the window seemed to have no difference; slow and fast shaking resulted in the same effect.

fail_snowglobe_1.py

fail_snowglobe_2.py

Al Sweigart's Endorsements for PSF Board 2025

2025-08-18T09:38:00-04:00

The nominees for the Python Software Foundation's Board of Directors 2025 election have been announced. You can find a full list on the nominees page. This year there are 4 seats open on the PSF Board. You can see who is currently on the board on the PSF Officers & Directors page. I'm pleased to announce I'm endorsing the following nominees: Abigail Dogbe, Archana Vaidheeswaran, Daniele Procida, Jannis Leidel, Sheena O'Connell, Simon Willison

You can become a member of the PSF. If you wish to vote in this year's election, you must affirm your intention to vote no later than Tuesday, August 26th, 2:00 pm UTC, to participate in this year’s election. This year's Board Election vote begins Tuesday, September 2nd, 2:00 pm UTC, and closes on Tuesday, September 16th, 2:00 pm UTC.

Abigail Dogbe

Dogbe has a long history of involvement with various Python & Django conferences, PyLadies, and Django Girls. She is a PSF Fellow and PSF Community Service Award recipient. Dogbe is a personal acquaintance I met at PyOhio in 2024. I endorse Abigail Dogbe for the 2025 PSF Board election.

Archana Vaidheeswaran

Vaidheeswaran has extensive experience with fundraising, event organizing, non-profit organizations, teaching, and technical expertise. Vaidheeswaran is a PSF Fellow. I endorse Archana Vaidheeswaran for the 2025 PSF Board election.

Daniele Procida

Procida has a long history in technical and leadership roles. He is a PSF Fellow and PSF Community Service Award recipient. I endorse Daniele Procida for the 2025 PSF Board election.

Jannis Leidel

Leidel has previously served on the PSF board twice before and served on numerous committees and working groups. He shows a keen awareness of the role of the PSF and what it needs from the board. I endorse Jannis Leidel for the 2025 PSF Board election.

Sheena O'Connell

O'Connell has a long history of conference organizing and education programs in the Python and Django communities. She has a clear plan of action for how the board can help the global Python community. O'Connell is a personal acquaintance, and we met at PyCon US 2025. I endorse Sheena O'Connell for the 2025 PSF Board election.

Simon Willison

Willison is one of the co-creators of Django, the creator of Datasette, and has a widely-read blog covering LLM news and his own software experiments. In the current hype bubble, he is one of the only people I trust to be knowledgeable and sober about AI. He is a PSF Fellow and has previously served on the PSF board. I endorse Simon Willison for the 2025 PSF Board election.

The Recursive Leap of Faith, Explained

2025-08-09T10:01:00-04:00

There is a phrase used when teaching recursion and recursive functions, leap of faith. In researching my book, The Recursive Book of Recursion, I found that most explanation of this technique were vague or even misleading. In this article, I'll go into what the leap of faith is and how it can help you write your recursive functions.

TL;DR: See "The Five Guidelines for Taking a Leap of Faith" list.

For brevity, I'll assume you have heard of recursive functions (i.e. functions that call themselves) and are familiar with the factorial function. Here's the Python code for it:

def factorial(number):
    if number == 0 or number == 1:
        # BASE CASE
        return 1
    else:
        # RECURSIVE CASE
        return number * factorial(number - 1)

The base case, where number is passed the argument 0 or 1, returns 1. The recursive case makes the recursive call factorial(number - 1). Factorial only Since the number argument must be an integer of 1 or greater, the argument to the recursive case gets closer and closer to the base case: 1. In fact, in The Recursive Book of Recursion, I advise that you always ask yourself three questions when writing recursive functions (to which I've provided answers for our factorial() function):

What is the base case? - The base case for factorial() is when number is 0 or 1, and 0! = 1 and 1! = 1 so the base case should evaluate to 1.
What argument is passed to the recursive function call? - In the recursive case, the argument is number - 1.
How does this argument become closer to the base case? - Since number starts off larger than 1, number - 1 ensures it keeps getting smaller until it reaches 1, the base case.

But in case this isn't enough for you to figure out how to write the recursive function, let's use the leap-of-faith technique. First, we start with a blank function:

def factorial(number):
    # Uh... I don't know what code goes here. Leave it blank for now.

Then let's apply the following guidelines:

Start by figuring out the data types of the parameters and return value.

This is easy for factorial. 5! = 120. There is one integer parameter (number) and the function returns an integer.

This is general good advice for writing recursive functions, because the parameters and return value must have consistent data types. You wouldn't want to, say, have factorial() return an integer for the base case and a list of integers for the recursive case. If your recursive function has multiple recursive cases, you wouldn't want one recursive call to pass an integer argument and the other recursive call pass the None value. Make sure you have a firm grasp on what the data types of the parameters and return value are, and make sure your code always sticks to it.

Next, implement the base case.

The base case is usually something small, simple, and has no recursive calls. 1! = 1 is such a base case:

def factorial(number):
    if number == 0 or number == 1:
        # BASE CASE
        return 1

Take a leap of faith and assume your recursive function magically returns the correct value, and write your recursive case.

This means that, before we're done writing our factorial() function, we assume that factorial() always returns the correct value. Wait... that makes it easy! We could just write our function like this:

def factorial(number):
    return factorial(number)

Of course recursion couldn't be this simple. Indeed, if you run this program, you get a stack overflow error:

>>> factorial(10)
Traceback (most recent call last):
  File "<python-input-1>", line 1, in <module>
    factorial(10)
    ~~~~~~~~~^^^
  File "<python-input-0>", line 2, in factorial
    return factorial(number)
  File "<python-input-0>", line 2, in factorial
    return factorial(number)
  File "<python-input-0>", line 2, in factorial
    return factorial(number)
  [Previous line repeated 988 more times]
RecursionError: maximum recursion depth exceeded

This is because there are two important caveats to our magical function:

First Caveat: The argument to the recursive function call cannot be the original argument.

This is a fact that most leap-of-faith explanations fail to mention. This restricts us so that our factorial() function can't simply call factorial(number). Instead, we have to pass some other argument to the recursive factorial() call. After all, "Ten factorial is ten factorial." may be true but it doesn't tell us much. We're forced to think about how factorial(number) can be related to factorial(*something_besides_just_number*).

Earlier, I pointed out that 5! = 5 x 4 x 3 x 2 x 1. If we sit and think for a bit (easier said than done, and this will be different for each recursive algorithm), we can notice that 4! = 4 x 3 x 2 x 1 and then, after more sitting and thinking, 5! = 5 x 4!. As code, this would look like factorial(5) == 5 * factorial(4). But we'd want to generalize this for any argument for the number parameter. We know that factorial(5) == 5 * factorial(4) and factorial(4) == 4 * factorial(3), so it seems the general pattern here is mathematically N! = N x (N - 1)!. As code, this would be return number * factorial(number - 1):

def factorial(number):
    if number == 0 or number == 1:
        # BASE CASE
        return 1
    else:
        # RECURSIVE CASE
        return number * factorial(number - 1)

Ah, if only our magical recursive call to factorial(number - 1) would give us the correct value, then we'd have our solution.

But wait... it does! Or at least, we're taking a leap of faith that it does. But faith is rather useless, so let's try it out and see:

>>> factorial(5)
120
>>> factorial(6)
720
>>> factorial(10)
3628800
>>> factorial(1)
1

It works! Well done! But wait, didn't I say there was a second caveat? There is, and it's one our factorial() function avoided by pure luck:

Second Caveat: The argument to the recursive function call must ALWAYS get closer to the base case.

For the recursive factorial() function we wrote, this is true. The number - 1 argument ensures that the next number argument gets closer to the base case, 1.

This works. We have used the five guidelines of the leap-of-faith technique to write a recursive function. You could stop reading this blog post now.

Or you could keep reading and follow me down a rather strange and demented turn.

What if, instead of having the insight that 5! = 5 x 4!, we noticed that 5! = 6! / 6. Mathematically, this is a correct equation. This would make our recursive case return factorial(number + 1) // (number + 1). (If 5 is our number, we'd generalize this to 6 being number + 1. The integer division operator // ensures we stick with integers and don't get floating-point rounding errors.) And number + 1 is not number, so guideline 4 is being followed. However, by adding to number and making it bigger, we are actually getting further away from the base case, 1.

If we tried to use this code, our factorial() function would look like this:

def factorial(number):
    if number == 0 or number == 1:
        # BASE CASE
        return 1
    else:
        # RECURSIVE CASE - The number + 1 argument gets further away from the base case 1.
        return factorial(number + 1) // (number + 1)

When we run this code, we get a stack overflow:

>>> factorial(5)
Traceback (most recent call last):
  File "<python-input-13>", line 1, in <module>
    factorial(5)
    ~~~~~~~~~^^^
  File "<python-input-12>", line 10, in factorial
    return factorial(number + 1) // (number + 1)
           ~~~~~~~~~^^^^^^^^^^^^
  File "<python-input-12>", line 10, in factorial
    return factorial(number + 1) // (number + 1)
           ~~~~~~~~~^^^^^^^^^^^^
  File "<python-input-12>", line 10, in factorial
    return factorial(number + 1) // (number + 1)
           ~~~~~~~~~^^^^^^^^^^^^
  [Previous line repeated 988 more times]
RecursionError: maximum recursion depth exceeded

Okay, so calling factorial(5) failed. But what if we used a bigger base case? I can figure out 100! by entering the Python expression 100 * 99 * 98 * 97 ... and so on, and that tells me that 100! is 93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000. (This is rather demented.) I'll make this my new base case:

def factorial(number):
    if number == 100:
        # BASE CASE
        return 93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000
    else:
        # RECURSIVE CASE
        return factorial(number + 1) // (number + 1)

And now factorial(5) works, because the argument getting bigger makes it get closer to the base case, 100. It works with all the previous test cases we did:

>>> factorial(5)
120
>>> factorial(6)
720
>>> factorial(10)
3628800
>>> factorial(1)
1
>>> factorial(101)
Traceback (most recent call last):
  File "<python-input-5>", line 1, in <module>
    factorial(101)
    ~~~~~~~~~^^^^^
  File "<python-input-4>", line 10, in factorial
    return factorial(number + 1) // (number + 1)
           ~~~~~~~~~^^^^^^^^^^^^
  File "<python-input-4>", line 10, in factorial
    return factorial(number + 1) // (number + 1)
           ~~~~~~~~~^^^^^^^^^^^^
  File "<python-input-4>", line 10, in factorial
    return factorial(number + 1) // (number + 1)
           ~~~~~~~~~^^^^^^^^^^^^
  [Previous line repeated 988 more times]
RecursionError: maximum recursion depth exceeded

This works as long as the argument passed to factorial() is less or equal to than 100. Unfortunately, calling factorial(101) (or any argument greater than 100) results in a stack overflow. You have to read that fifth guideline carefully, especially the word "always":

The argument to the recursive function call must ALWAYS get closer to the base case.

The factorial() function we wrote with a base case of 100 doesn't ALWAYS get closer to the base case. It only gets closer to the 100 base case when the number argument is less than 100. Well, we can fix this code by only doing return factorial(number + 1) // (number + 1) if number is less than 100. The rest of the time, we can do return number * factorial(number - 1):

def factorial(number):
    if number == 100:
        # BASE CASE
        return 93326215443944152681699238856266700490715968264381621468592963895217599993229915608941463976156518286253697920827223758251185210916864000000000000000000000000
    elif number < 100:
        # RECURSIVE CASE
        return factorial(number + 1) // (number + 1)
    else:
        # ANOTHER RECURSIVE CASE
        return number * factorial(number - 1)

Now that our code handles number arguments greater than 100 and less than 100, the argument to the recursive function call ALWAYS gets closer to our base case of 100:

>>> factorial(101)
9425947759838359420851623124482936749562312794702543768327889353416977599316221476503087861591808346911623490003549599583369706302603264000000000000000000000000
>>> factorial(5)
120
>>> factorial(102) == factorial(100) * 101 * 102
True

Though perhaps I took this a bit too far.

The Five Guidelines for Taking a Leap of Faith

Start by figuring out the data types of the parameters and return value.
Next, implement the base case.
Take a leap of faith and assume your recursive function magically returns the correct value, and write your recursive case.
First Caveat: The argument to the recursive function call cannot be the original argument.
Second Caveat: The argument to the recursive function call must ALWAYS get closer to the base case.

As long as you follow these five guidelines, you can write a correctly working recursive function. Even if it comes out as demented as that last factorial() function I wrote, the code will work.

Another Example: Recursive Permutation

For all my expertise with recursion, I admit that I still have trouble writing a recursive permutation function. This is a function that is given a string and then returns a set of all permutations (that is, different orderings) of that string. For example, calling permutations('ABC') should return the list ['ABC', 'ACB', 'BAC', 'BCA', 'CAB', 'CBA']. I can never seem to remember how to write this function. I'll follow my own advice and use the four guidelines of the leap-of-faith technique to create it here.

(By the way, the number of permutations for a group of N objects is N!. This is why the factorial of zero is mathematically defined as one; if you have a set of zero objects, there is one way to order the objects in that set: a set of zero objects.)

Start by figuring out the data types of the parameters and return value.

Okay. This is easy. For simplicity, our function will take a single string. The return value will always be a list of strings of the permutations of the string argument. So permutations('ABC') returns ['ABC', 'ACB', 'BAC', 'BCA', 'CAB', 'CBA'], or permutations('AB') returns ['AB', 'BA'].

Next, implement the base case.

Also simple: permutations('') should return the list [''] and permutations('A') should return ['A']. So if the length of the string argument is 0 or 1, the function should return a list of the argument. Remember the data types we set out: permutations() should always return a list of strings like ['A'] and not just a string like 'A'.

def permutations(chars):
    if len(chars) == 0 or len(chars) == 1:
        # BASE CASE
        return [chars]

Take a leap of faith and assume your recursive function magically returns the correct value, and write your recursive case.

Ah, if only we could do this and be done with our problem:

def permutations(chars):
    if len(chars) == 0 or len(chars) == 1:
        # BASE CASE
        return [chars]
    else return permutations(chars)

But we have to keep in mind the fourth guideline:

First Caveat: The argument to the recursive function call cannot be the original argument.

So what can we pass to permutations() instead? Let's sit and think for a bit: To find the permutations of 'ABC', we could split it into the first character (we'll call this the "head") and everything after the first character (the "tail"). We could get all the permutations of the tail, and then inject the head into each position of each permutation. We satisfy the first caveat: when permutations(chars) is called, the recursive case is permutations(chars[1:]) and chars[1:] is different from chars.

Let's think this through with an example. If chars was 'ABC', the head is 'A' and the tail is 'BC'. If we take a leap of faith and assume that permutations('BC') works and returns ['BC', 'CB'], we could go through both these string permutations and make a list with 'A' at each position:

For 'BC', we'd need to create 'ABC', 'BAC', and 'BCA'.
For 'CB', we'd need to create 'ACB', 'CAB', and 'CBA'.

We'd combine this all into one list and return it: ['ABC', 'BAC', 'BCA', 'ACB', 'CAB', 'CBA'].

Okay, I think that would work as long as permutations('BC') works. But does this pass the second caveat?

Second Caveat: The argument to the recursive function call must ALWAYS get closer to the base case.

Well, the tail of the argument to permutations() is always smaller than the argument because it will have one less character. And our base case is when the argument has zero or one characters. So, yes, the argument would always get closer to the base case.

Now we have to actually write the code:

def permutations(chars):
    if len(chars) == 0 or len(chars) == 1:
        # BASE CASE
        return [chars]
    else:
        # RECURSIVE CASE
        all_perms = []  # Start with an empty list.
        head = chars[0]
        tail = chars[1:]

        tail_perms = permutations(tail)
        for perm in tail_perms:  # Go through each of the tail's permutations.
            for i in range(len(perm) + 1):  # Go through each position and inject the head.
                new_perm = perm[:i] + head + perm[i:]
                all_perms.append(new_perm)  # Add it to the complete list of permutations.
        return all_perms  # Return all of the permutations.

Let's take that leap of faith and try it out. Here goes nothing:

>>> permutations('ABC')
['ABC', 'BAC', 'BCA', 'ACB', 'CAB', 'CBA']
>>> permutations('Z')
['Z']
>>> permutations('ABCD')
['ABCD', 'BACD', 'BCAD', 'BCDA', 'ACBD', 'CABD', 'CBAD', 'CBDA', 'ACDB', 'CADB', 'CDAB', 'CDBA', 'ABDC', 'BADC', 'BDAC', 'BDCA', 'ADBC', 'DABC', 'DBAC', 'DBCA', 'ADCB', 'DACB', 'DCAB', 'DCBA']

Hey, it works!

How Does ChatGPT (Fail to) Teach the Leap of Faith Technique (Just Like Every Other Tutorial)?

AI hype continues to annoy me, but I keep an open mind and investigate how useful it is. I gave it the prompt, "Explain the "leap of faith" technique for recursive functions." to see how it would teach the concept. The output was the typical, disappointing tutorial. You can read it if you want, or give it a pass:

The “leap of faith” technique is a way of reasoning about recursive functions that helps you trust the recursion instead of getting tangled up trying to simulate every call in your head.

Here’s how it works:

1. The idea

When you write a recursive function, there are usually two parts:

Base case — a simple, direct answer for the smallest input (no recursion needed).
Recursive case — solve the problem by calling the same function on a smaller or simpler input, then combine that result with some additional work.

The “leap of faith” is the mindset where, once you’ve ensured that the recursive call is on a simpler input and will eventually hit the base case, you assume that it works correctly and returns the right answer — without trying to trace through every smaller call.

2. Why it’s useful

When learning recursion, beginners often get stuck simulating each step:

“Okay, factorial(4) calls factorial(3), which calls factorial(2), which calls… wait, what was I calculating again?”

Instead, the leap of faith says:

“I don’t need to track every call. I’ll assume factorial(3) gives the right answer — because I’ve already made sure it works for smaller inputs — and then I’ll just use that answer to finish factorial(4).”

3. Example: factorial

def factorial(n):
    if n == 0:
        return 1                     # base case
    else:
        return n * factorial(n - 1)   # recursive case

Using the leap of faith for factorial(4):

Base case check: eventually n will be 0, so recursion stops.
Recursive case: assume factorial(3) correctly returns 6 — don’t calculate it in your head — then factorial(4) is 4 * 6 = 24.

4. How to apply the leap of faith

Verify that your recursion moves toward the base case.
Trust that the recursive call returns the correct result for smaller inputs.
Focus only on combining that result to solve the current problem.

5. Why it’s called a leap of faith

You’re “leaping” over the details of how the recursive call works, and having “faith” that it returns the right answer, just like you trust a well-tested library function without reading its source code every time you use it.

If you want, I can also explain how the leap of faith relates to induction proofs — since the reasoning is very similar.

Here are the problems that this, and every other "leap of faith" tutorial has:

No mention on keeping data types consistent. - A common problem beginners have when writing recursive functions, especially for problems like permutations, is having the return value use different data types such as the strings/list of strings example I pointed to earlier. This needs to be made explicit to beginners.
Explicitly pointing out that the recursive call's argument can't just be the original argument. - This is the first thought anyone has when we say, "Assume the recursive function already works." Keep in mind the first caveat (guideline 4): the recursive call argument must be different from the original argument.
Using vague words like "simpler" or "smaller" to describe arguments to the recursive function calls. - What we really mean is that, specifically, the argument in the recursive function call gets closer to the base case. It's not enough to say "smaller", we need to connect it to base case, which also means explicitly writing the code for the base case first (guideline 2 in the list of guidelines I gave.) And keep in mind the second caveat (guideline 5): the argument must always get closer to the base, otherwise you'll end up with a stack overflow.

There's nothing wrong with ChatGPT's explanation; it's technically correct and similar to any other tutorial on the topic. But that's what's wrong with it: students read it, have trouble understanding the vaguely worded concepts, and then assume they just aren't smart enough to understand recursion.

Conclusion

I've always held that recursion isn't a difficult topic so much as it is poorly taught. Many tutorials have a lot of hand-waving and unspoken assumptions, especially for terms like "leap of faith". This tutorial tells you exactly what this term means, along with two caveats you need to keep in mind when using the leap-of-faith technique. If you're interested in learning more about recursion (including drawing pretty fractals and making recursive photos), you can read my free book, The Recursive Book of Recursion or buy a print copy. Good luck!

Recursive Functions To Anger Your CS Professor

2025-07-18T10:00:00-04:00

Here are some recursive functions that are technically correct and technically recursive.

The programs here are available in a git repository.

(Explaining the joke kills the humor, but explanations have been given at the bottom if you aren't familiar with recursive programming. Input validation in these functions has been skipped for brevity.)

Factorial

def fact(num):
    # Base cases:
    if num == 0: return 1
    elif num == 1: return 1
    elif num == 2: return 2
    elif num == 3: return 6
    elif num == 4: return 24
    elif num == 5: return 120
    elif num == 6: return 720
    elif num == 7: return 5040
    elif num == 8: return 40320
    elif num == 9: return 362880
    elif num == 10: return 3628800
    # Skip the base case for 11.
    elif num == 12: return 479001600
    elif num == 13: return 6227020800
    elif num == 14: return 87178291200
    elif num == 15: return 1307674368000
    elif num == 16: return 20922789888000
    elif num == 17: return 355687428096000
    elif num == 18: return 6402373705728000
    elif num == 19: return 121645100408832000
    elif num == 20: return 2432902008176640000

    # Recursive case:
    else: return num * fact(num - 1)

Fibonacci

fib_cache = [None, 0, 1]  # Memoization cache with base cases

def fibonacci(nth):
    # Check if nth fib number is in the cache:
    if len(fib_cache) <= nth:
        return fib_cache[nth]
    else:
        # If not, expand the cache:
        b = fib_cache[len(fib_cache) - 1]
        a = fib_cache[len(fib_cache) - 2]
        while len(fib_cache) < nth:
            b, a = a + b, b
            fib_cache.append(b)

    # Recursive case:
    return fibonacci(nth - 1) + fibonacci(nth - 2)

Even Odd Detection

def is_odd(num, originally_positive=None):
    # Base case:
    if num == 0:
        return False

    # Determine argument for originally_positive:
    if originally_positive == None:
        if num > 0:
            return not is_odd(num - 1, True)
        else:
            return not is_odd(num + 1, False)

    # Recursive cases:
    if originally_positive:
        return not is_odd(num - 1, True)
    else:
        return not is_odd(num + 1, False)

Depth First Search

import random

data = {'key': 'a', 'value': 42, 'branches': [
           {'key': 'c', 'value': 13, 'branches': []},
           {'key': 'z', 'value': 21, 'branches': [
               {'key': 'x', 'value': -5, 'branches': []}
           ]}
       ]}

def dfs(needle, haystack):
    if haystack['key'] == needle:
        # Key found base case:
        return haystack['value']

    for branch in haystack['branches']:
        # Recursively check each of the branches:
        try:
            return dfs(needle, branch)
        except KeyError:
            # Check again sometimes, just to make sure:
            if random.randint(0, 1) == 1:
                try:
                    return dfs(needle, branch)
                except KeyError:
                    pass

    # Key not found base case:
    raise KeyError

Joke Explanations

Before you tell me some nitpick about why this code is wrong or a suggestion about how I should have written the code some other way, remember the MST3K mantra: "It's just a show, I should really just relax."

And then you should keep the nitpick or suggestion to yourself.

Factorial Explanation

The factorial of an integer is the product of all integers from 1 up the integer. For example, the factorial of 5 (written as 5! in mathematics) is 5 x 4 x 3 x 2 x 1 or 120.

Recursive functions need to have at least one base case (or else it will eventually cause a stack overflow) and at least one recursive case (or else it isn't recursive). This can be done recursive because 5! is the same thing as 5 x 4!, and 4! is the same thing as 4 x 3!, and so on.

Recursive factorial only needs one base case: 0! is 1. However, the gag here is that I supply several base cases, effectively getting rid of the need for any recursion for the integers 0 through 20. The function still uses recursion for integers larger than 21, but you could theoretically have millions or billions of base cases and still technically claim this is a recursive function. You are effectively hard-coding the recursion away.

(This sort of pre-calculated caching is called memoization.)

Bonus joke: I skipped the base case for 11 for absolutely no reason. The function still works for finding 11!.

Fibonacci Explanation

The Fibonacci sequence starts with the numbers 0 and 1. Each subsequent number in the sequence is the sum of the previous two numbers: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, and so on forever. It's a pattern that comes up in nature.

The base cases are for the 1st and 2nd Fibonacci numbers: 0 and 1, respectively. You can determine the Nth Fibonacci number by adding the Nth - 1 and Nth - 2 Fibonacci numbers. This lends itself well to recursion, however it results in a staggering amount of recalculation: Finding fibonacci(5) means finding fibonacci(4) and fibonacci(3), but finding fibonacci(4) involves finding fibonacci(3) and fibonacci(2). The fibonacci(3) call is made multiple times, even though the 3rd Fibonacci number doesn't change and doesn't need to be recalculated.

This issue of overlapping subproblems is solved by memoization, or the caching of results already calculated.

The gag here is that when the given Fibonacci number hasn't been calculated, the cache is populated by iteratively calculating the Fibonacci number. The two recursive calls are then made (making this a recursive function), even though the answer already exists in the cache. The recursion here is compeltely pointless.

Even Odd Detection Explanation

Determining if an integer is even or odd is straightforward in programming: mod the number by two and if the result is 0 it is even and if the result is 1 it is odd. The Python code is:

def is_odd(num):
    return num % 2

def is_even(num):
    return not (num % 2)

But this can also be done recursively. Is the integer 42 even or odd? Well, the answer is the opposite of whether 41 is even or odd. And 41's oddness is the opposite of 40's oddness, and so on. The base case is that 0 is an even number.

The gag here is that the mod approach works in one step for any number, the recursive approach gets slower and slower the larger the number is: finding out if 1,000,000,000 requires a billion function calls to determine if it is odd or not.

Let's make this even worse by unnecessarily splitting the recursive case into two recursive cases: whether the number argument was originally positive or negative by storing this information in a parameter. This is similar to the way certain recursive functions use an accumulator parameter for their operation. (My opinion is that any recursive function has an accumulator, it can always be done easier without using recursion.)

Depth First Search Explanation

Depth first search is an algorithm for finding data in a tree data structure. Recursion is actually a suitable solution for this, as it involves 1) tree-like data structures and 2) backtracking. If your problem doesn't have both of these features, then recursion is an messy, overengineered approach.

We have a tree data structure where each node has a key-value pair and branches to other nodes. The root node of the tree is passed to the dfs() function along with the key to search for. If the root node's key matches the key we are searching for, it returns the value in that key-value pair. This is the first of two base cases.

Otherwise, dfs() is called on each of the branches of that node. This is the recursive case. In this way, the entire tree is searched. If the recursion stops at nodes that do not have any branches. If we return from all the recursive calls without finding the key, the KeyError exception is raised to indicate that the key doesn't exist in the tree. This is the second base case.

The gag here is that, randomly, the function will re-check the branches of the node. The function is still technically recursive, though it makes far more recursive function calls than needed.

A similar joke is in my Poisoned Merge Sort implementation, which contains a subtle bug for anyone who blindly copies and pastes the code into their programs.

Book Plug

My love-hate relationship with recursion led me to write The Recursive Book of Recursion. It's a wonderful but often overrated technique, and I am quite vocal that I think it's intimidating reputation comes from it being poorly taught more than an inherent difficulty.

The book has code in Python and JavaScript, and is free to read online. I also have a large collection of recursive code examples in Python, including Python programs that use the Turtle module to draw beautiful fractals including your own custom fractals.

I've given talks on recursion at PyCon conferences (also on pyvideo.org), if you want a 30 minute crash course on the subject.

Audio, Video, and Webcams in Python (Lost Chapter from Automate the Boring Stuff)

2025-07-07T10:00:00-04:00

The third edition of Automate the Boring Stuff with Python is now available for purchase or to read for free online. It has updated content and several new chapters, but one chapter that was left on the cutting room floor was "Working with Audio, Video, and Webcams". I present the 26-page rough draft chapter in this blog, where you can learn how to write Python code that records and plays multimedia content.

Working with Audio, Video, and Webcams

These days a smartphone is a portable film studio that fits in your pocket. The ability to not just readily view but also produce video has led to an explosion of video content easily accessible over the internet. There’s plenty of video and audio editing software available for users of all levels of sophistication. But if you have, say, a thousand video files that you need to automate reducing their volume by 50% and then extract thumbnail images, you don’t want to have to edit each of those files individually yourself. Similarly, you may want to record video, audio, or photos from a laptop’s webcam for some automated process too specialized for off-the-shelf software. Or maybe you’d just like your program to play a funny sound effect. In this chapter, you’ll learn how to control your computer’s microphone, webcam, and speaker hardware from Python and play multimedia files.

This chapter assumes you have already read Chapter 21 to learn the basics about how programs work with image data. Since video is just a series of images, many of the same concepts apply.

Audio and Video Data

First, you should have a reliable way to open and view video and audio files. Since its release over twenty years ago, the open source VLC Media Player application has been free of charge and the gold standard for multimedia players. Install the VLC Media Player from https://www.videolan.org/vlc/, which runs on Windows, macOS, and Linux. Mobile versions for Android and iOS are also freely available. VLC is far superior to any multimedia application that came with your computer.

While you may be familiar with audio and video files by their file extension such as .mp3 or .webm, audio and video formats are split into container formats and codecs. A container format is a wrapper that contains metadata and the encoded video or audio data. MP4, AVI, MKV, and MOV are popular container formats. A codec (or encoding) is the compression algorithm used for the video or audio data. MP3, H.264, VP9, and AAC are common video or audio codecs. Not all applications and devices support all codecs.

The audio file formats we’ll be using in this chapter are:

.wav files - an uncompressed format that are widely supported by apps and libraries but tend to have large file sizes so they are often used for short sound effects.
.mp3 files - a popular compressed format often used for music and other lengthy audio.
.ogg files - an open standard, compressed format that is less popular than .mp3 but provides better compression and quality.

The video file formats we’ll be using in this chapter are:

.avi files - an older format that tends to have larger file sizes.
.mp4 files - a popular format that is widely supported by different software
.mkv files - an open format that has many features but isn’t as widely supported as .mp4.
.webm files - a more recent format based on .mkv that offers better compression and quality.

Common Video Sizes and Aspect Ratios

The aspect ratio is the relative size of a video or screen’s width to its height, often written as width:height. For example, 4:3 (4 pixels of width for every 3 pixels of height) was a common aspect ratio for 20th century computer monitors and standard-definition televisions in the broadcast TV era. Today, 16:9 is common for most laptop screens and high-definition televisions. More recently, the wider 19.5:9 aspect ratio is becoming common for smart phones. An aspect ratio that is wider than it is tall has a landscape orientation, while an upright aspect ratio that is taller than it is wide is called a portrait orientation.

Screen resolution is the number of columns and rows of pixels that a laptop or mobile screen displays. It’s often written as width x height, such as 1280 x 720 or 1920 x 1080 (also written as 720p and 1080p, respectively). Your laptop’s screen often supports multiple resolutions that can be configured in your operating system’s settings. Videos have one size, though they can be scaled larger or smaller to fit a display or app window. While videos can have any size, they often match common screen resolutions so they can be viewed in fullscreen mode without disproportionate scaling.

Recording from Webcams and Microphones

The webcam and microphone you use for video chats can be accessed by Python scripts through the OpenCV, sounddevice, and wavio Python packages. OpenCV, the open computer vision library, is an advanced open source imaging library. To use it you must first you must install the mathematics and data science package NumPy by running pip install numpy on Windows and macOS or sudo apt install python3-numpy on Ubuntu Linux. Then you can install OpenCV with pip install opencv-python from the terminal. See Appendix A for full instructions. The sounddevice and wavio packages are installed with pip install sounddevice and pip install wavio, respectively.

The following programs have been kept to a minimum so that you can easily insert their code into your own Python programs that record audio and video.

Taking a Photo from a Webcam

You can use your laptop’s webcam to take photos or record videos through a Python script. This has a few advantages over using a regular camera or photo app. Your Python script could:

Automatically take photos in response to certain events such as receiving emails.
Take time lapse photos over a long period of time at various intervals.
Add a photo booth feature to your program, using the Pillow module to edit the photos.
Scan QR codes.

OpenCV list your computer’s webcams with integer indexes that begin with 0. A laptop could easily have multiple webcams. For example, it could have a built-in camera at the top of the screen (perhaps at index 0 in OpenCV) along with a separate USB webcam (perhaps at index 1). The following webcamPreview.py program has a `list_webcam_indexes()`` function check which OpenCV webcam indexes exist on your computer. The program then takes repeated photos from the webcam to display in a preview window. When the user presses the space key, it saves the latest photo as photo.png (though you can change the filename to photo.jpg or any other image format.) Or the user can press the Esc key to quit without saving.

import cv2

def list_webcam_indexes():
    detected_webcam_indexes = []
    for i in range(10):  # Test for up to 10 possible webcams.
        webcam = cv2.VideoCapture(i)  # Connect to webcam.
        status, frame = webcam.read()
        if status:
            # A webcam exists at this index:
            detected_webcam_indexes.append(i)
        webcam.release()  # Disconnect from webcam.
    return detected_webcam_indexes  # Returns a list of integer webcam indexes.

first_available_index = list_webcam_indexes()[0]  # Fails if there are no webcams.
webcam = cv2.VideoCapture(first_available_index)  # (1) Connect to webcam.

print('index:', first_available_index)
print('width:', webcam.get(cv2.CAP_PROP_FRAME_WIDTH))
print('height:', webcam.get(cv2.CAP_PROP_FRAME_HEIGHT))
print('fps:', webcam.get(cv2.CAP_PROP_FPS))

while True:  # (2)
    success, frame = webcam.read()  # (3)
    if not success:
        print('Could not capture frame.')
        break

    # Show the frame in a preview window:
    cv2.imshow('Press space to save photo or Esc to exit', frame)  # (4)

    pressed_key_code = cv2.waitKey(1)  # (5)
    if pressed_key_code == 32:  # (6) 32 is the space key code.
        cv2.imwrite("photo.png", frame)  # Save photo.
        break
    elif pressed_key_code == 27:  # (7) 27 is the Esc key code.
        break  # Exit without saving photo.

webcam.release()  # (8) Disconnect from webcam.
cv2.destroyAllWindows()  # Close preview window.

On my laptop, this program makes a window with a live preview from the built-in webcam and outputs the following text:

index: 0
width: 640.0
height: 480.0
fps: 30.0

From this output we can tell that the webcam produces 640 x 480 sized images and can record video up to 30 frames per second. The preview window closes when the user presses the space bar or Esc key. The live preview window looks like Figure 24-1.

The live preview window from webcamPreview.py.

The VideoCapture object that gets stored in the webcam variable (1) represents the connected camera. The webcam.read() method (2) returns a numpy.ndarray data structure with all the photo pixel data in it. (NumPy is beyond the scope of this book, but an ndarray is similar to a Python list.) This can be passed to the cv2.imshow()`` function (3) to create a window with the webcam photo data. Thewhile` loop runs fast enough to make the series of still photos look like live video in the preview window 4.

The cv2.waitKey() function (5) returns an integer key code of the keyboard key the user pressed while the preview window is focused. The integer argument passed to cv2.waitKey() is how many milliseconds the function waits for the user to press a key, with cv2.waitKey(0) meaning that it should wait forever. We call cv2.waitKey(1) because the function should wait just 1 millisecond before returning so our program can continue to fetch new images from the webcam. If the user hasn’t pressed a key, cv2.waitKey() returns -1. The program checks if the key code is 32 (for the space key) (6) and 27 (for the Esc key) (7) lets the user choose whether to save a photo or not. Afterwards, the VideoCapture object in webcam is released (8) and the live preview window is closed so that the program can exit.

To find other keyboard key codes, pass a single-character string to Python’s ord() function. For example, ord('q') returns the integer 113, and 113 is the key code for the Q key.

Take a Photo without the Preview Window

If you want a program that simply saves a picture from the first available webcam as soon as possible, you can use this much simpler webcamPhoto.py program:

import cv2, sys
camera = cv2.VideoCapture(0)  # 0 is the index of the webcam to use.
success, frame = camera.read()
if not success:
    sys.exit('Invalid webcam index.')
cv2.imwrite('photo.png', frame)

You can incorporate this code into your own program that needs to take a photo from the webcam (though you may also wish to include the list_webcam_indexes() from webcamPreview.py instead of assuming index 0 is correct.)

You can also use the Pygame library to take photos from a webcam. While Pygame is designed for making 2D video games, it has several useful multimedia features as well. You can install it by running pip install pygame. Appendix A has full instructions. The following webcamPhotoPygame.py program takes a photo with the webcam and saves it as photo.png:

import pygame.camera, pygame.image, time
pygame.camera.init()

all_webcams = pygame.camera.list_cameras()  # (1)
webcam = pygame.camera.Camera(all_webcams[0])  # (2) Use the first found webcam.
webcam.start()  # (3) Initialize the webcam.

time.sleep(1)  # (4) Wait for the camera to get ready.
photo = webcam.get_image()  # (5) Take a photo from the webcam.

pygame.image.save(photo, "photo.png")  # (6) You can also use .jpg or .bmp.
pygame.camera.quit()

After importing the pygame.camera and pygame.image modules and initializing the pygame.camera module by calling pygame.camera.init(), you can obtain a list of the webcams connected to your computer by calling pygame.camera.list_cameras() (1). For example, on my computer, this function call returned the list ['HD Pro Webcam C920', 'Integrated Camera'] which represents an external USB webcam and the built-in webcam at the top of my laptop’s screen. You can then pass one of these strings to pygame.camera.Camera() to obtain a new Camera object to take pictures with.

This Camera object, which this program stores in a variable named webcam (2), must also be initialized by calling its start() method (3). You can take a picture by calling the get_image() method (5), which returns a Surface object that holds the image data.

Unfortunately, the start() method can take up to a full second before it’s ready to take photos. If you call get_image() before it’s ready, you will get a blank, black image. In my testing, it only takes 0.6 or 0.7 seconds for the webcam to get ready, so a full second delay by calling time.sleep(1) should be more than enough of a wait before calling get_image() for any modern computer. Test this on your computer and increase the delay if you are getting an all-black image.

After this, you can save the image to a file by passing the Surface object and image filename to pygame.image.save() (6). The file extension in your filename can either be .bmp, .jpg, or .png. When your program is done using the webcam, it can call pygame.camera.quit().

Recording Video from a Webcam

OpenCV can also record video files. Open a new file editor window and enter the following code, saving it as webcamVideo.py. This program begins recording immediately while showing a preview window of the video it’s recording to the file video.avi. When the user presses the Esc key, the program stops recording.

import cv2

# NOTE: Using webcam index 0 by default:
webcam = cv2.VideoCapture(0)  # (1) Connect to webcam.

# Define the codec using VideoWriter_fourcc and create a VideoWriter object
fourcc = cv2.VideoWriter_fourcc(*'XVID')  # (2)
fps = webcam.get(cv2.CAP_PROP_FPS)
width = int(webcam.get(cv2.CAP_PROP_FRAME_WIDTH))
height = int(webcam.get(cv2.CAP_PROP_FRAME_HEIGHT))

video_file = cv2.VideoWriter('video.avi', fourcc, fps, (width, height))  # (3)

while True:
    success, frame = webcam.read()  # (4)
    if not success:
        print('Could not capture frame.')
        break

    cv2.imshow('Recording... (press Esc to stop)', frame)
    video_file.write(frame)  # (5)

    if cv2.waitKey(1) == 27:  # (6) 27 is the Esc key code.
        break  # Stop recording.

webcam.release()  # Disconnect from webcam.
video_file.release()  # Disconnect from output video file.
cv2.destroyAllWindows()  # Close preview window.

While the VideoCapture object stored in the webcam variable (1) represents the camera hardware, the VideoWriter object stored in the video_file variable (3) represents the video file. The VideoWriter_fourcc object (2) we create represents the four-character code that identifies the video encoding. In our case, the four-character code is 'XVID' for the Xvid codec. The width, height, and frames per second settings are also passed to cv2.VideoWriter(). Each frame of video from the webcam.read() method call (4) is added to the video file by calling video_file.write() (5) until the user presses the Esc key (6).

Note that OpenCV can record video but not audio. We’ll use the sounddevice module in the next section to record audio, but unfortunately recording videos that include synced audio is complicated and beyond the scope of this book.

Recording Audio from a Webcam or Microphone

The sounddevice and wavio third-party modules can use your computer’s or external webcam’s microphones to record audio. These modules have several audio-related features, but the following micRecord.py program has been stripped down to the basics. Still, you may want to review multithreaded programming in Chapter 19 to understand how the record_audio_stream() function runs in the background while the rest of the Python program continues executing.

import sounddevice, wavio, threading, time

1def list_microphone_devices():
    # Return a list of microphone indexes and names.
    microphones = []
    for i, device in enumerate(sounddevice.query_devices()):
        # Check if the microphone has max input channels:
        if device['max_input_channels'] > 0:  # (2)
            # Append i (the device id) and mic name:
            microphones.append((i, device['name']))
    return microphones

def record_audio_stream(filename, device=None, rate=44100, channels=2):
    # Create a list to store the audio data:
    recorded_data = []

    with sounddevice.InputStream(samplerate=rate, channels=channels, device=device) as stream:  # (3)
        while True:
            # Record audio in chunks and add it the recorded_data list:
            audio_chunk, overflowed = stream.read(rate)
            recorded_data.extend(audio_chunk.tolist())

            if stop_recording_signal.is_set():
                break

    # Save the recorded data to a WAV file
    wavio.write(filename, recorded_data, rate, sampwidth=2)  # (4)

# Display information about audio/visual recording devices:
print('Devices on this computer:')
5print(sounddevice.query_devices())
print()

print('Microphones connected to this computer:')
print(list_microphone_devices())
print()

# Create an event to signal the other thread to stop:
stop_recording_signal = threading.Event()

input('Ready. Press Enter to start recording.')
# Start recording in a separate thread:
recording_thread = threading.Thread(target=record_audio_stream, args=('output.wav',))  # (6)
recording_thread.start()

# Wait for user to press Enter:
input('Now recording. Press Enter to stop.')  # (7)

# Replace the previous input() call with this code to record for a set time:
#time.sleep(1.0)  # Record for 1 second.

# Signal the recording thread to stop and wait for it to finish:
stop_recording_signal.set()  # (8)
recording_thread.join()  # (9) Block until the other thread has stopped.
print('Recording saved.')

There are several parts to this program aside from the actual recording of audio, so let’s explore those first. The sounddevice.query_devices() function (5) returns an object that, when printed, displays a numbered list of multimedia input and output devices on the computer, such as the following:

>>> import sounddevice
>>> print(sounddevice.query_devices())
   0 Microsoft Sound Mapper - Input, MME (2 in, 0 out)
>  1 Microphone Array (Realtek High , MME (2 in, 0 out)
   2 Microsoft Sound Mapper - Output, MME (0 in, 2 out)
<  3 Speaker/HP (Realtek High Defini, MME (0 in, 2 out)
   4 Primary Sound Capture Driver, Windows DirectSound (2 in, 0 out)
   5 Microphone Array (Realtek High Definition Audio), Windows DirectSound (2 in, 0 out)
--snip--

This lists the various microphone input and speaker output devices on your computer, along with their integer sounddevice index. The > angle bracket marks the default input device and the < angle bracket marks the default output device. This program also has a list_microphone_devices() function (1) that calls sounddevice.query_devices() and filters for only the microphone devices (which will have a max_input_channels key with a value greater than 0 (2)) to make it easy to find microphones. The list_microphone_devices() returns a list of tuples, with each tuple having the device index and string description, like:

[(0, 'Microsoft Sound Mapper - Input'), (1, 'Microphone Array (Realtek High '), --snip—

The program also has a record_audio_stream() function, with the following parameters:

filename, a string of the filename (which should end with .wav) to save the audio.
device, the integer sounddevice index of the microphone to use to record the audio (the default value None indicates that the default input device should be used.)
rate, the number of samples to take per second. Higher sample rates provide higher quality audio, and 44.1k (or the integer 44100) is a standard sample rate for most microphones.
channels, the number of channels to use. The default stereo audio uses 2 channels and mono audio uses 1.

These parameters are used to create the InputStream object (3) that represents the recording from the given microphone. The while loop that follows constantly reads audio data in from the read() method call, which is a list of audio sample data that is added to the recorded_data list. The recording stops and breaks out of the while loop when the stop_recorded_signal thread event is set (explained later). Then the wavio.write() function (4) saves it to a .wav audio file.

We use a separate thread of execution to have our program run the code inside the record_audio_stream() function while the rest of the code continues to also run. Multithreaded programming was explained in Chapter 19. First we create a Thread object set with the record_audio_stream (without the parentheses, since we want to refer to the function itself rather than call it) and the function arguments 'output.wav' for its filename parameter. For the sake of this explanation, we’ll call this the “recording thread” and the program’s original thread that continues in the main part of the program the “main thread.”

Next, we don’t want to call record_audio_stream() directly. Instead, we call the start() method on this Thread object so the recording thread runs the code inside record_audio_stream() (6) while the main thread continues on to input('Now recording. Press Enter to stop.') (7). This way, the user can choose when to stop the recording by pressing Enter. (Alternatively, we can replace the call to input() with a call to time.sleep() to record a set number of seconds instead of however long until the user presses Enter.) The user input thread then calls stop_recording_signal.set() (8). The recording thread will notice this when stop_recording_signal.is_set() returns True, causing it to break out of the while loop that continuously calls stream.read().

Finally, the user input thread calls recording_thread.join() (9), making it pause until the recording thread has returned from the record_audio_stream() function. Now there will be only the user input thread running, which then calls print('Recording saved.') and exits the program.

This program is rather complicated, but that’s because it has to handle so many small details: selecting which of possibly multiple microphones to record from, the sample rate and number of audio channels to use for the recording, and constantly gathering the audio data until the user directs the program to stop. The sounddevice and wavio modules themselves offer even more features, and you can find their full documentation at https://python-sounddevice.readthedocs.io/ and https://github.com/WarrenWeckesser/wavio.

Playing Audio Files

If you just need to play a simple audio file, you can use the playsound3 module. First, install it from the terminal by running pip install playsound3. See Appendix A for full instructions. Once installed, you can play an audio file by calling the playsound3 module’s playsound() function and passing the filename of the audio file. Download the hello.mp3 file from https://autbor.com/hello.mp3 (or use your own .mp3 file) and enter the following into the interactive shell:

>>> import playsound3
>>> playsound3.playsound('hello.mp3')

The playsound() function won’t return until the audio file has finished playing, that is, the function blocks until the audio has finished. Keep in mind that this will halt your program for a while if you give it a long audio file to play. The playsound3 module can play MP3 and WAV files. If you cannot hear the sound, make sure your computer is unmuted. If playsound() raises exceptions (which happens if the filename contains odd characters such as an equal sign), try passing a Path object of the audio file instead of a string, as in the following example:

>>> import playsound3
>>> from pathlib import Path
>>> audio_file = Path(r'C:\Users\Al\Desktop\hello.mp3')
>>> playsound3.playsound(audio_file)

The playsound3 module is best if you just need to play a simple sound effect and you want your program to block until the sound has finished. If you need to have better control over playback, such as changing volume, pausing and unpausing the audio file, seeking to a specific time in the audio, and other features, use the Pygame’s mixer module.

For example, to play hello.mp3 with Pygame, enter the following into the interactive shell:

>>> import pygame.mixer
>>> pygame.mixer.init()
>>> pygame.mixer.music.load('hello.mp3')
>>> pygame.mixer.music.play()

With Pygame, you must call the pygame.mixer.init() function once after importing the pygame.mixer module in order to play any audio files. Then load the audio file by calling pygame.mixer.music.load() and pass either a string or Path object of the audio file’s filename. Calling pygame.mixer.music.play() starts playing the loaded audio file from the beginning. The play() function doesn’t block; it returns immediately and the audio continues to play in the background while your Python program runs other lines of code.

You can continue to affect the playing of the music with the other functions in the pygame.mixer.music module. All of these functions are non-blocking and return immediately:

pygame.mixer.music.stop() stops playing the music immediately.
pygame.mixer.music.pause() stops playing the music, but will resume where it left off when unpaused.
pygame.mixer.music.unpause() resumes playing paused music.
pygame.mixer.music.fadeout(milliseconds) fades the volume of the music down to silence over the next milliseconds milliseconds. For example, passing 2000 will fade out the music over the next 2 seconds after the function call.
pygame.mixer.music.get_volume() returns a float of the volume level for the pygame.mixer music, with 1.0 for full volume and 0.0 for muted volume.
pygame.mixer.music.set_volume(level) lets you set the volume by passing a float between 1.0 and 0.0.
pygame.mixer.music.get_busy() returns True if music is currently playing and False if the music has finished, stopped, or paused.
pygame.mixer.music.get_pos() returns the position in the audio file Pygame's mixer module is playing it (or, if paused, would play it) in milliseconds. For example, returning 0 means the position is at the very start of the audio file and returning 5000 means the position is 5 seconds into the audio file.
pygame.mixer.music.set_pos(position) sets the position in the audio file to play. The position parameter is a float or int for the number of seconds into the audio. The audio must currently be playing to call set_pos().
pygame.mixer.music.queue(audio_filename) lets you set another audio file to begin playing as soon as the current one has finished. The audio_filename parameter is either a string or a Path object of the audio file to queue.

Pygame also has other audio features such as playing multiple sound files at the same time. The full documentation is at https://www.pygame.org/docs/.

Working with Video Files

The programs you create from this book have text-based input and output with the input() and print() commands, so displaying images and videos in a conventional graphical user interface (GUI) is beyond the scope of this book. However, your Python programs can still download videos from the internet without a GUI and control the playback of the video in VLC Media Player, as you’ll learn in this section.

Downloading Videos from YouTube

The main limitation of YouTube and other video sites is that you can only view the videos in a browser while online. You can’t edit the videos to extract clips or make adjustments. The yt-dlp tool is a fork of the youtube-dl project, and can download videos as files from YouTube, Vimeo, Facebook, TikTok, Instagram, and hundreds of other video websites. You can install it by running pip install yt-dlp from the terminal. Appendix A has full instructions.

The yt-dlp project is both a terminal command and a Python module. We’ll focus on the terminal command first but also explore how to incorporate it in your Python programs. Both youtube-dl and yt-dlp are written in Python. Because video websites change their layout from time to time, you’ll need to always run the latest version of yt-dlp. You can make yt-dlp update itself by running yt-dlp -U. The yt-dlp command uses calver or calendar versioning, so the version number is always the date of that version’s release. For example, version 2023.07.06 was released on July 6, 2023.

To download a video, run the yt-dlp command from a terminal with the video’s URL as the command-line argument:

C:\Users\Al\Desktop>yt-dlp https://youtu.be/mDNa10gQTJA
[youtube] Extracting URL: https://youtu.be/mDNa10gQTJA
[youtube] mDNa10gQTJA: Downloading webpage
--snip--

If the URL contains characters such as an ampersand or spaces, you may have to enclose them in double quotes. The filename is automatically made from the video description. To specify your own filename for the downloaded video file, pass the -o argument:

C:\Users\Al\Desktop>yt-dlp -o catvideo.webm https://youtu.be/mDNa10gQTJA

If the video is a music video and you only want the audio data, pass the -x argument to extract the audio:

C:\Users\Al\Desktop>yt-dlp -x https://youtu.be/9RHFFeQ2tu4

Depending on the video and video website, the audio format may be an .mp3, .ogg, or .webm file. You can convert it to another audio format with ffmpeg, explained later in this chapter.

If a video requires that you must be logged in to view it, log into the site in your browser and then run yt-dlp with the --cookies-from-browser argument followed by the name of the browser (either Firefox, Chrome, Edge, or Safari). This makes yt-dlp examine your browser’s cookies to reuse the login session information there:

C:\Users\Al\Desktop>yt-dlp --cookies-from-browser Firefox https://youtu.be/mDNa10gQTJA

You can also specify the username and password of the account with the -u and -p command line arguments. You can leave out the -p argument to have yt-dlp ask you to enter the password at the keyboard.

C:\Users\Al\Desktop>yt-dlp -u my_username -p secret_passw0rd https://youtu.be/9RHFFeQ2tu4

There are many features for downloading videos with yt-dlp, such as downloading entire playlists, using a VPN proxy, downloading subtitles, and others. To view all of them, run yt-dlp --help.

Running yt-dlp from Python

You can also download videos using yt-dlp using Python code. The module name is yt_dlp, which lets you create YoutubeDL objects. Despite the name, the YoutubeDL object can download videos from any video website that yt-dlp supports. Open a new file and add the following code for a minimal program that downloads videos with the `yt_dlp module. Name it videoDownloader.py:

from yt_dlp import YoutubeDL
URLs = ['https://www.youtube.com/watch?v=BaW_jenozKc']  # Add video URLs here.
with YoutubeDL() as ydl:
    ydl.download(URLs)

The yt-dlp documentation at https://pypi.org/project/yt-dlp/ has more information on supplying the download() function with more options.

Alternatively, you can run the yt-dlp terminal command from a Python script using the subprocess.run() function:

>>> import subprocess
>>> subprocess.run(['yt-dlp', 'https://www.youtube.com/watch?v=BaW_jenozKc'])

If you want the video’s metadata, such as duration, number of views, or description, you can download this as JSON data using the -J argument. Chapter 19 covers using the subprocess module to run terminal commands from a Python program and capture their output as strings. Chapter 18 covers the json module and how to work with JSON data. Let’s look at the following example of parsing a video’s metadata as JSON from Python code:

>>> import json, subprocess
>>> proc = subprocess.run(['yt-dlp', '-J', 'https://youtu.be/mDNa10gQTJA'], capture_output=True, text=True)
>>> json_text = proc.stdout
>>> python_data = json.loads(json_text)
>>> list(python_data.keys())
['id', 'title', 'formats', 'thumbnails', 'thumbnail', 'description', 'channel_id', 'channel_url', 'duration', 'view_count', --snip--
>>> python_data['title']
'Sister cats Grace, Mercy, and Patience love each other very much.'
>>> python_data['description']
"These were kittens I rescued from a backyard cat colony in Houston in October 2021. Grace (gray), Mercy (brown tabby), and Patience (tortoiseshell) probably aren't actually sisters, but they grew up together in my house and are the same age and--snip--
>>> python_data['duration']  # In seconds.
116
>>> python_data['view_count']
1797
>>> python_data['upload_date']  # In YYYYMMDD format.
'20220903'

Every video website returns different metadata, so the list(python_data.keys()) part of our example can show you the dictionary keys that are available.

Play a Video File

Playing a video file from your Python program is complicated. For the most part, this book covers Python programs that don’t use a graphical user interface. However, if you just need a video to play somewhere on your screen, you can install VLC Media Player and then use the third-party python-vlc library to display videos in their own window. After installing VLC Media Player, run pip install python-vlc to install the module that lets you control VLC from your Python programs. See Appendix A for full instructions.

Once installed, you can then use the vlc module to create an Instance, MediaPlayer, and Media object. Just replace the 'video.mp4' string with the filename of the video file you want to play. Enter the following into the interactive shell with a video file named video.mp4 in the current working directory:

>>> import vlc
>>> instance = vlc.Instance('--no-xlib', '--quiet')  # These arguments stop debug output.
>>> player = instance.media_player_new()
>>> media = instance.media_new('video.mp4')  # Replace with your filename.
>>> player.set_media(media)
>>> player.play()

The play() method call causes the video to appear in a new window and start playing until it has finished. This method immediately returns; it doesn’t block until the video has finished playing. You can also call other MediaPlayer methods:

pause() will pause the video, and unpauses when play() is called again.
stop() will immediately stop the video and close the video’s window.
is_playing() returns 1 if the video is currently playing and returns 0 if the video is paused, stopped, or has finished. (In Python, True is equal to 1 and False is equal to 0.)
get_length() returns an integer of the video length in milliseconds.
get_fps() returns the frame rate of the video in frames per second.
get_time() returns the position currently playing in the video, in milliseconds. Returns -1 if the video is stopped.
set_time(seek) sets the position of the video to seek milliseconds. This can only be called while the video is playing or is paused.
toggle_fullscreen() switches the video window between windowed and fullscreen mode.
audio_get_volume() returns an integer of the MediaPlayer object’s volume: 100 is full volume and 0 is muted.
audio_set_volume(volume) sets the MediaPlayer object’s volume to the volume integer, which can be greater than 100.
video_get_size() returns a tuple of two integers of the width and height of the video in pixels.
video_take_snapshot(0, '.', 0, 0) takes a snapshot of the current frame. The first 0 argument is for the “video output number” which is usually zero, the '.' argument tells VLC to save the snapshot image file in the current working directory, and the third and fourth arguments are the width and height of the snapshot (with the 0 arguments meaning “use the original video’s width and height”). The snapshot image filename will be “vlcsnap” followed by a timestamp, such as vlcsnap-2025-08-21-15h21m32s719.png. The method returns 0 if the snapshot was successful and -1 if it failed for some reason.

While the vlc module doesn’t provide much in the way a graphical user interface, the popup video window is enough for your basic Python programs to display a video clip as needed.

Editing Video and Audio with ffmpeg

One of the most powerful tools for editing video and audio content is the ffmpeg command. While ffmpeg has no user-friendly graphical user interface like other apps (though ffmpeg GUI extensions have been separately made), it does have an extensive set of command line arguments. This makes it easy to automate from Python programs which is invaluable if you have a large number of multimedia files to process.

Downloading and Installing ffmpeg

The ffmpeg command is available for Windows, macOS, and Linux. You can download it from https://ffmpeg.org/download.html. The ffmpeg website also has an ffplay and ffprobe programs available for download. The ffplay is a terminal command that plays video and audio files in a barebones window while the ffprobe command extracts information about video and audio files. There is no installer for these commands. Instead, just place the ffmpeg, ffplay, and ffprobe executable files into a folder on your system PATH. (On Ubuntu Linux, you may be able to install them with the sudo apt install ffmpeg command.) See Chapter 12 for an explanation of the PATH environment variable and working on the terminal command-line in general.

On macOS, the ffmpeg, ffprobe, and ffplay programs might not run from the terminal since they don’t have a digital signature. Double-click on these commands in the Finder, and in the warning window about “unidentified developer,” click the Open button. This tells macOS that you consider these programs safe to run. You’ll only have to do this once for each program.

ffmpeg Recipes

The ffmpeg program’s set of command line arguments is far too complicated to cover in this book. Instead, this chapter features specific recipes for carrying out common editing tasks.

The ffmpeg program produces a lot of output. You can hide all of this by passing the -loglevel warning command-line arguments, which suppresses all logging output except for warnings and errors. For example, instead of running ffmpeg -i input.mp4 output.avi to show you all the information associated with converting an .mp4 video file to an .avi file, you can run ffmpeg -loglevel warning -i input.mp4 output.avi to do the conversion with no output.

In all of the ffmpeg recipes, the input file follows the -i command line argument and the output file is placed at the very end of the command after all the other command line arguments.

If a file already exists with the output filename you passed to ffmpeg, then ffmpeg pauses and asks for confirmation to overwrite this file by asking the user to press y and Enter on the keyboard. This pause can interrupt your programs, so the -y argument you see in the ffmpeg recipes causes ffmpeg to skip this confirmation step.

You can run the ffmpeg command from your Python scripts using the subprocess.run() function, as covered in Chapter 19. Remember to run import subprocess first before calling subprocess.run().

You can transform the audio or video of your files with ffmpeg’s many filters. The recipes here explain some, but you can view the full list by running ffmpeg -filters and then get help information about a specific filter by running ffmpeg -h filter=filter_name.

The ffmpeg command has a vast set of command line arguments for doing almost any kind of editing you’d like from a terminal window or Python script. If you don’t have the time to read through its documentation, you can ask an AI large language model such as ChatGPT for the command. For example, you could give it the prompt: “What is the ffmpeg command for converting a video to black and white?” and receive the command along with an explanation of each command-line argument. Be sure to test the information the AI gives you, as it often makes mistakes.

Alternatively, the website https://ffmpeg.app/ features an interactive prompt system that reliably guides you to an ffmpeg command with arguments to carry out your intended actions. The website looks like Figure 24-2:

The website https://ffmpeg.app helps you find command line arguments.

Keep in mind that ffmpeg can not only edit video and audio, it can also edit image files as well. Instead of specifying a video file with -i input.mp4 or output.mp4 command line arguments, for images you can use -i input.png or output.webp If ffmpeg gives you an error message about how the output filename “does not contain an image sequence pattern” you can include the -update 1 argument. See the Extract Frames from a Video section for more information about sequence patterns and the -update argument.

View Video and Audio File Metadata with ffprobe

The ffprobe command (which comes with ffmpeg) can give you a large amount of information about a video or audio file. Its basic usage looks like this:

ffprobe input.mp4

This command produces a large amount of text output with details about the input.mp4 file:

ffprobe version N-109948-ge026e29460-20230301 Copyright (c) 2007-2023 the FFmpeg developers
  built with gcc 12.2.0 (crosstool-NG 1.25.0.90_cf9beb1)
--snip--
  Stream #0:0[0x1](eng): Audio: aac (LC) (mp4a / 0x6134706D), 48000 Hz, stereo, fltp, 191 kb/s (default)
--snip--
  Stream #0:1[0x2](eng): Video: h264 (High) (avc1 / 0x31637661), yuvj420p(pc, smpte170m/bt470bg/smpte170m, progressive), 1920x1080, 22582 kb/s, SAR 1:1 DAR 16:9, 30.01 fps, 30 tbr, 90k tbn (default)
--snip--

You can also run this command from the following Python instruction, which saves the output as a string in proc.stderr:

>>> import subprocess
>>> proc = subprocess.run(['ffprobe', 'input.mp4'], capture_output=True, text=True)
>>> print(proc.stderr)
ffprobe version N-109948-ge026e29460-20230301 Copyright (c) 2007-2023 the FFmpeg developers
--snip--

Video and audio files contain streams of encoded video and audio data. For example, a movie video file may have a stream of video data and multiple audio streams for English, Spanish, and French dubs. The ffprobe command can show you these streams and their associated information. For example, this input.mp4 file has audio encoded with the AAC codec and video that has 30.01 frames per second (fps) and a size of 1920x1080. If you want your program to extract this information, you’ll likely need to use regular expressions (covered in Chapter 9).

For example, you can enter this code into the interactive shell to use regular expressions to find the 1920 x 1080 width and height dimensions of an input.mp4 video file:

>>> import subprocess, re
>>> proc = subprocess.run(['ffprobe', 'input.mp4'], capture_output=True, text=True)
>>> mo = re.search('Video.*, (\d+)x(\d+),', proc.stderr)
>>> int(mo.group(1))
1920
>>> int(mo.group(2))
1080

Using code like this, you could then find the dimensions of, say, each video file in a folder. This is similar to the video_get_size() method in the vlc module, though ffprobe can read far more detail than just video size.

You can run ffprobe --help to view the command-line options, but the output is over 2,400 lines long! It may be useful to ask a large language model AI for specific command line arguments to pass to ffprobe for a given task if you are overwhelmed by the documentation.

The next several sections cover individual ffmpeg commands along with their command line arguments for performing a number of common video-related tasks. We’ll be using example filenames such as input.mp4 and output.mp4, and keep in mind that ffmpeg won’t modify the input video and audio files; it only produces a new video or audio file with the changes as the output. You can download some short example files to practice with from https://autbor.com/input_ffmpeg.zip.

Convert Video and Audio File Formats

You can convert video and audio files from one format to another with this terminal command or Python instruction:

ffmpeg -y -i input.mp4 output.avi

>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', 'output.avi'])

The -i option indicates that the input.mp4 file is the input file, which is then converted to an .avi file named output.avi. You can specify any video file formats you want, including .gif for an animated GIF. Remember that ffmpeg works with image files as well, so you can convert a .png to a .webp or any other format.

Extract Audio from a Video

You can extract the audio from a video file with this terminal command or Python instruction:

ffmpeg -y -i input.mp4 output.mp3

>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', 'output.mp3'])

This is the same set of arguments as converting formats. The ffmpeg command can understand that if the output file is an .mp3 audio file (or any other audio file format), the video data is dropped and only the audio data is used.

Mute or Change Volume in a Video File

You can increase, decrease, or mute the volume in a video file with the following terminal command or Python instruction:

ffmpeg -y -i input.mp4 -af volume=2.0 output.mp4

>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-af', 'volume=2.0', 'output.mp4'])

The -af argument specifies an audio filter named volume to change the volume by a factor of 2.0, or double the volume of the input.mp4 file. The video with the new volume is in output.mp4. If you wanted to halve the volume, you could pass volume=0.5 instead. You could also change the volume by a number of decibels. For example, passing volume=5dB increases the volume of the input file by 5 decibels. You could also pass volume=-5dB to decrease the volume by 5 decibels.

If you want to simply mute the volume by removing the audio data completely, pass the -an argument:

ffmpeg -y -i input.mp4 -c:v copy -an output.mp4

>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-c:v', 'copy', '-an', 'output.mp4'])

The -c:v copy argument means that ffmpeg will copy the video stream data from input.mp4 directly to output.mp4 without re-encoding it. The -an argument removes the audio stream data altogether. Keep in mind that once you completely mute the volume on a video, you won’t be able to increase the volume later.

Combine a Video and Audio File

You can add an audio file to a silent video with the following terminal command or Python instruction:

ffmpeg -y -i input_video.mp4 -i input_audio.mp3 -c copy output.mp4

>>> subprocess.run(['ffmpeg', '-y', '-i', 'input_video.mp4', '-i', 'input_audio.mp3', '-c', 'copy', 'output.mp4'])

The -c copy arguments copy the video and audio stream data without re-encoding, respectively. If the audio has some problems because the video format doesn’t support it, try replacing -c copy with -c:v copy -c:a aac to copy the video but re-encode the audio with the widely-supported AAC audio codec.

If the video already has audio, but you want to replace it with the audio in a separate audio file, run the following terminal command or Python instruction:

ffmpeg -y -i video.mp4 -i audio.mp3 -c copy -map 0:v:0 -map 1:a:0 output.mp4

>>> subprocess.run(['ffmpeg', '-y', '-i', 'video.mp4', '-i', 'audio.mp3', '-c', 'copy', '-map', '0:v:0', '-map', '1:a:0', 'output.mp4'])

The -map 0:v:0 -map 1:a:0 arguments direct ffmpeg to use the video stream from the first input, video.mp4, and the audio from the second input, audio.mp3, when creating the output.mp4 file. The original audio stream data in video.mp4 is dropped.

Resize a Video

You can resize a video with this terminal command or Python instruction:

ffmpeg -y -i input.mp4 -vf scale=1280:720 output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-vf', 'scale=1280:720', 'output.mp4'])

The -vf indicates you are using a video filter, in this case a filter named scale that scales the size of the video to 1280 x 720 resolution and outputs it to a video file named output.mp4. You can change the resolution to any dimensions you want.

Extract a Video or Audio Segment

You can extract a segment from a video or audio file with the following terminal command or Python instruction:

ffmpeg -y -i input.mp4 -ss 00:01:30 -to 00:01:45 output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-ss', '00:01:30', '-to', '00:01:45', 'output.mp4'])

The -ss argument and -to arguments mark the starting and ending times of the segment to extract, given in an HH:MM:SS format. So -ss 00:01:30 -to 00:01:45 means extract the video or audio content from 1 minute, 30 seconds to 1 minute, 45 seconds from input.mp4 file. This will result in a 15 second segment placed in a file named output.mp4. You can change the starting and ending timestamps as needed. To extract an audio segment from an audio file, use the audio filenames for the input and output file. The rest of the command remains the same. You can use an ffprobe recipe described later in this chapter to find out the length of the video or audio content in a file.

Extract Frames from a Video

You can extract a single frame from a video with the following terminal command or Python instruction:

ffmpeg -y -i input.mp4 -ss 00:00:15 -vframes 12 output%04d.jpg
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-ss', '00:00:15', '-vframes', '12', 'output%04d.jpg'])

The -vframes 12 and -ss 00:00:15 arguments mean that 12 frames are extracted from the video starting at 15 seconds into the video is extracted and placed into an image file named output0001.jpg. The %04d in the output%04d.jpg output name is a sequence pattern that means the 12 frames are saved to files with 4-digit numbers with leading zeros: output0001.jpg, output0002.jpg, output0003.jpg, and so on up to output0012.jpg. Also, you can use a wide range of image formats in addition to .jpg, including .png, .bmp, or .webp.

If you only want to extract a single frame from the video and don’t want to use a sequence pattern in the output filenames, use -vframe 1 and add the additional -update 1 argument:

ffmpeg -y -i input.mp4 -ss 00:00:15 -vframes 1 -update 1 output.jpg
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-ss', '00:00:15', '-vframes', '1', '-update', '1', 'output.jpg'])

If you want to extract every frame from a video, you can run a much simpler terminal command or Python instruction:

ffmpeg -y -i input.mp4 output%04d.jpg
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', 'output%04d.jpg'])

Many videos are about 30 frames per second, so a single minute of video will produce about 1,800 image files.

Concatenate Multiple Video or Audio Files

You can concatenate a video or audio file to the end of another video or audio file with the following terminal command or Python instruction:

ffmpeg -y -f concat -i videolist.txt -c copy output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-f', 'concat', '-i', 'mylist.txt', '-c', 'copy', 'output.mp4'])

This command concatenates all the videos listed in the videolist.txt text file together into a single video in a file named output.mp4. The videolist.txt file has the following format:

file 'input_spam.mp4'
file 'input_eggs.mp4'
file 'input_bacon.mp4'

This command only works if the videos have the same codecs and size, otherwise you’ll need to consult the ffmpeg documentation for mixing videos of different formats.

Add Watermark or Overlay to a Video

You can add a watermark or overlay image to a video with the following terminal command or Python instruction:

ffmpeg -y -i input.mp4 -i logo.png -filter_complex overlay=10:50 output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-i', 'logo.png', '-filter_complex', 'overlay=10:50', 'output.mp4'])

The -i logo.png means that the logo.png file is also an input, and the -filter_complex overlay=10:50 means that it will be placed on top of the input.mp4 input video, 10 pixels from the left edge and 50 pixels from the top edge.

You can also use a video as the overlay instead of a still image if you want a picture-in-picture effect.

Rotate a Video

If you have videos that are incorrectly rotated, you can correct this with the following terminal command or Python instruction:

ffmpeg -y -i input.mp4 -vf transpose=1 -c:a copy output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-vf', 'transpose=1', '-c:a', 'copy', 'output.mp4'])

The -vf argument means ffmpeg will apply a video filter, and the specific video filter is transpose=1. The number 1 means the video is rotated 90 degrees clockwise. You can also use any of the following numbers:

0: Rotate by 90 degrees counterclockwise and flip vertically.
1: Rotate by 90 degrees clockwise.
2: Rotate by 90 degrees counterclockwise.
3: Rotate by 90 degrees clockwise and flip vertically.

If you would like to rotate the video 180 degrees clockwise, then apply the transpose video filter twice with the -vf transpose=1,transpose=1 arguments.

Normalizing audio in a video file

If you have audio with wild fluctuations in volume, you can normalize it with the following terminal command or Python instruction:

ffmpeg -y -i input.mp4 -af dynaudnorm output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-af', 'dynaudnorm', 'output.mp4'])

The dynaudnorm audio filter performs dynamic audio normalization and is good for evening out volume for, say, conversations where people speak at different volumes. There’s also the loudnorm audio filter, which sets specific loudness standards commonly used in broadcast media:

ffmpeg -y -i input.mp4 -af loudnorm output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-af', 'dynaudnorm', 'output.mp4'])

The default settings for these filters should work well, but you can run ffmpeg -h filter=dynaudnorm and ffmpeg -h filter=loudnorm to view the help information for their various settings.

Compress a Video or Audio File

Video files, especially high-quality videos, can be quite large. You can re-encode a video with the following terminal command or Python instruction:

ffmpeg -y -i input.mp4 -vcodec libx265 -crf 28 output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-vcodec', 'libx265', '-crf', '28', 'output.mp4'])

This command compresses a video file by re-encoding its video stream data with the H.265 (HEVC) codec and setting a higher CRF (Constant Rate Factor) value. This may slightly reduce the quality of the video, but it also reduces its disk size.

The bitrate of an audio file is how many bits are used per unit of time. For example, 128kbps uses 128 kilobits (or 16 kilobytes) per second of audio, so a 60 second MP3 file at 128kbps would take up about 1.1 megabytes of disk space. In general, a higher bitrate produces higher quality audio.

You can re-encode an audio file with a lower bitrate with the following terminal command or Python instruction:

ffmpeg -y -i input.mp3 -b:a 32k output.mp3
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp3', '-b:a', '32k', 'output.mp3'])

For MP3s, 32kbps is low quality while 256kbps is high quality and 320kbps is almost indistinguishable from a music CD. (CDs, or compact discs, were an audio storage media used by ancient civilizations.)

While you can create smaller files by re-encoding a high quality audio file to a lower bitrate audio file, re-encoding a low bitrate audio file to a higher bitrate won’t magically improve the audio quality.

Video Fade In and Out

You can add a fade in from or fade out to black effect at the start or end of your video with the following terminal command or Python instruction:

ffmpeg -y -i input.mp4 -vf fade=in:0:30 output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-vf', 'fade=in:0:30', 'output.mp4'])

This recipe uses a video filter name fade. The -vf fade=in:0:30 argument means that the fade in starts at frame 0 (the very start of the video) and ends at frame 30. For a video that is 30 frames per second, this creates a 1-second fade in at the start of the video. You can also have a fade out with this terminal command or Python instruction:

ffmpeg -y -i input.mp4 -vf fade=in:0:30,fade=out:150:60 output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-vf', 'fade=in:0:30,fade=out:300:15', 'output.mp4'])

The fade out starts at frame 150 (5 seconds into the video) and finishes in 60 frames, or two seconds.

Decrease Saturation or Convert to Black and White

You can decrease the saturation (how colorful the video is) with the following terminal commands or Python instructions:

ffmpeg -y -i input.mp4 -vf eq=saturation=0.5 output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-vf', 'eq=saturation=0.5', 'output.mp4'])

The -vf argument applies a video filter, specifically the eq=saturation=0.5 video filter, which reduces the saturation by one half. To make the video completely black and white (that is, grayscale), use eq=saturation=0.0. You can also increase the saturation to give the video a colorful, almost cartoon look by doubling the saturation with eq=saturation=2.0.

Adjust Video Brightness and Contrast

You can increase the brightness of a video by 6% with the following terminal command or Python instruction:

ffmpeg -y -i input.mp4 -vf eq=brightness=0.06 output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-vf', 'eq=brightness=0.06', 'output.mp4'])

The -vf argument means you want to apply a video filter, specifically the eq=brightness=0.06 filter that increases brightness by 6%. Using eq=brightness=0.5 would increase brightness by 50%, while using eq=brightness=-0.5 would decrease brightness by 50%.

On the other hand, the value for the contrast filter ranges from 0.0 (no contrast) to 1.0 (normal contrast) and up. You can set the contrast 30% higher than normal with the following terminal command or Python instruction:

ffmpeg -y -i input.mp4 -vf eq=contrast=1.3 output.mp4
>>> subprocess.run(['ffmpeg', '-y', '-i', 'input.mp4', '-vf', 'eq=contrast=1.3', 'output.mp4'])

Alternatively, you can make the contrast 30% lower than normal by using eq=contrast=0.7.

Summary

Audio and video data make up a large part of how we interact with computers whether it’s podcasts, dance videos, security camera footage, or sound effects. Python has several third-party modules for downloading, playing, and editing audio and video data, and this chapter provides small code examples you can embed in your own programs.

Python has are several multimedia libraries installable through pip. The OpenCV computer vision library can access your webcam to take photos and videos. The Pygame library, while designed for making video games, can record images from webcams as well as play sound files. The sounddevice and wavio modules for Python can record audio from your computer’s microphone.

There are also several free, open source applications for dealing with multimedia data: yt-dlp for downloading videos, VLC Media Player for viewing videos, and ffmpeg for applying a wide range of filters and conversions to video and audio files.

The topics touched on here could easily fill a book of their own, but this chapter provides a wide introduction and sample code for getting started. Python is much more than a programming language; it’s also a popular development community that has created many free third-party modules to bring new features to your programs.

Practice Questions

Divide the following into audio or video file format: .ogg, .mp3, .mp4, .wav, .avi
Can the OpenCV library record audio for the video files it creates?
Between the sounddevice and pygame modules, which would you use to play an audio file and block the execution of the Python program until the audio finishes playing? Which would you use to start playing an audio file and immediately continue with the rest of the Python program?
What yt-dlp command line argument extracts the audio from a downloaded video file?
How do you specify the input file for the ffmpeg command?
How much does the VLC Media Player application cost?
What does the ffprobe command do?

Practice Projects

For practice, write programs that do the following.

Take Time Lapse Photos

Write a program that uses either OpenCV to take photos using a webcam once every 5 seconds, and then after a preset number of photos, assembles them into a time lapse video. Since time lapse videos can take hours to create, for testing purposes, it may help to find a lava lamp video online to play while the webcam on top of your screen is pointed at a mirror to view the video.

Add Fade In and Fade Out

Write a program that uses ffmpeg to add a two second fade in and fade out effect to every video file in a given folder. For testing purposes, you can make multiple copies of the same short video file. The program should also check the video length and offer a warning if the video is shorter than four seconds.

Brightness Preview

Write a program that uses ffmpeg to get a preview of various brightness changes. It can take quite a while to adjust the brightness of an entire video, and you may want to reprocess the video multiple times at varying brightness levels until you find one you like. It’s much faster to have ffmpeg change the brightness of a single image than an entire video. To keep from having to re-run ffmpeg, your program should extract a frame from an input video, then run ffmpeg again on that frame image to produce other images at varying brightness levels. For example, in a loop you can pass ffmpeg the argument eq=brightness=0.01, eq=brightness=0.02, eq=brightness=0.03 and so on up to, say, eq=brightness=0.50. Be sure to give the output image files different names, such as brightness0.01.png, brightness0.02.png, and so on. Then user will be free to view the different preview images and pick the brightness setting they’d like to later apply to the entire video.

The TurtleSC Package for Python turtle.py Shortcuts

2025-07-03T10:00:00-04:00

TurtleSC provides a mini-language of shortcut instructions to carry out turtle.py function calls, like 'f 100' instead of forward(100). Git Repo, PyPI Project Page.

These two examples do the same thing:

Original Turtle Code	TurtleSC Code
`from turtle import ` `from random import ` `colors = ['red', 'orange', 'yellow', 'blue', 'green', 'purple']` `speed('fastest')` `pensize(3)` `bgcolor('black')` `for i in range(300):` `pencolor(choice(colors))` `forward(i)` `left(91)` `hideturtle()` `done()`	`from turtlesc import ` `from random import ` `colors = ['red', 'orange', 'yellow', 'blue', 'green', 'purple']` `sc('spd fastest, ps 3, bc black')` `for i in range(300):` `sc(f'pc {choice(colors)}, f {i}, l 91')` `sc('hide,done')`

These shortcuts are quicker to type, making them ideal for experimenting from the interactive shell. TurtleSC takes the idea of the existing fd() and rt() aliases for forward() and right() to the next level. All shortcuts are run from a string passed to the turtlesc.sc() function.

I created this to help with some digital art projects, namely recreating the "impossible objects" of Swedish artist Oscar Reutersvärd:

The code for this is in my oscarsturtle repo, which I'll write a blog post on in the future.

TurtleSC was created by me, Al Sweigart, author of Automate the Boring Stuff with Python and other programming books. All of his books are available for free online under a Creative Commons license. If you'd like a tutorial specifically about Python's turtle module, check out The Simple Turtle Tutorial.

You can also write (less readable) turtle programs using shortcuts. For example, this program:

from turtle import *
from random import *

tracer(4, 0)

for i in range(50):
    fillcolor((random(), random(), random()))

    # Set a random heading and draw several short lines with changing direction:
    setheading(randint(0, 360))
    begin_fill()
    for j in range(randint(200, 600)):
        forward(1)
        left(randint(-4, 4))
    home()
    end_fill()

update()
done()

...could be written as:

from turtlesc import *
from random import *

sc('t 4 0')

for i in range(50):
    sc(f'fc {random()} {random()} {random()}, sh {randint(0, 360)}, bf')
    for j in range(randint(200, 600)):
        sc(f'''f 1
               l {randint(-4, 4)}''')
    sc('h,ef')

sc('u,done')

This code isn't very readable, but it's quick to type. This is useful if you are making rapid prototypes of ideas.

Shortcuts in the sc() string argument are separated by a comma, with any shortcut arguments separated by spaces. Whitespace is insignificant (you can have one more spaces, and it's the same as a single space). Shortcut names and arguments are case-insensitive: 'f' and 'F' work the same. Newlines in the string argument are treated as shortcut-separating commas.

Some less-common shortcuts (such as 'done') only have their full function name. All shortcuts have their full function name as a shortcut name: you can use either 'f' or 'forward'.

TurtleSC also adds cardinal movement shortcuts that move the turtle independent of it's current heading (and does not change the heading): 'n 100', 's 100', 'e 100', 'w 100' will move the turtle up, down, right, and left 100 steps, respectively. There are also full name shortcuts ('north', 'south', 'east', 'west') and diagonal shortcuts ('nw', 'ne', 'sw', 'se', 'northwest', 'northeast', 'southwest', 'southeast').

By default, the sc() function operates on the single, global turtle. You can also pass the turtle_obj keyword argument to operate on different Turtle objects:

from turtlesc import *
from turtle import *

t1 = Turtle()
t2 = Turtle()

# Make turtle 1 red and move up-right:
sc('pc red, l 45, f 100', turtle_obj=t1)

# Make turtle 2 blue and move down-right:
sc('pc blue, r 45, f 100', turtle_obj=t2)

sc('done')

The turtlesc module also provides new in_radians_mode() or in_degrees_mode() functions that return a Boolean True or False value depending on which mode the turtle is in. These features are missing in the original turtle module.

If you want to get the original code for a shortcuts string (which can be helpful to print the shortcuts), pass it to the scs() function:

>>> from turtlesc import *
>>> scs('f 100, r 45, f 100')
'forward(100)\nright(45)\nforward(100)'

Note that the return value of scs() is a string. If there are multiple shortcuts, they are separated by a newline and all lack the turtle. prefix in case you want to add your own (either the turtle module or a variable containing a Turtle object.)

To easily print out this shortcut string, call psc():

>>> from turtlesc import *
>>> psc('f 100, r 45, f 100')
forward(100)
right(45)
forward(100)

Reference

Here is a complete reference of supported shortcuts:

Shortcut Call	Turtle.py Equivalent
`sc('f 100')`	`forward(100)`
`sc('b -100.5')`	`backward(-100.5)`
`sc('l 45')`	`left(45)`
`sc('r 90')`	`right(90)`
`sc('h')`	`home()`
`sc('c')`	`clear()`
`sc('g 15 40')`	`goto(15 40)`
`sc('x 10')`	`setx(10)`
`sc('y -20')`	`sety(-20)`
`sc('st')`	`stamp()`
`sc('pd')`	`pendown()`
`sc('pu')`	`penup()`
`sc('ps 4')`	`pensize(4)`
`sc('pc 1.0 0.0 0.5')`	`pencolor(1.0, 0.0, 0.5)`
`sc('fc 255 0 128')`	`fillcolor(255, 0, 128)`
`sc('bc #FF00FF')`	`bgcolor('#FF00FF')`
`sc('sh 90')`	`setheading(90)`
`sc('cir 10')`	`circle(10)`
`sc('undo')`	`undo()`
`sc('bf')`	`begin_fill()`
`sc('ef')`	`end_fill()`
`sc('reset')`	`reset()`
`sc('sleep 5')`	`time.sleep(5)`
`sc('n 10')`	`setheading(90)` `;` `forward(10)`
`sc('s 10')`	`setheading(270)` `;` `forward(10)`
`sc('e 10')`	`setheading(180)` `;` `forward(10)`
`sc('w 10')`	`setheading(0)` `;` `forward(10)`
`sc('nw 10')`	`setheading(135)` `;` `forward(10)`
`sc('ne 10')`	`setheading(45)` `;` `forward(10)`
`sc('sw 10')`	`setheading(225)` `;` `forward(10)`
`sc('se 10')`	`setheading(315)` `;` `forward(10)`
`sc('done')`	`done()`
`sc('bye')`	`bye()`
`sc('exitonelick')`	`exitonclick()`
`sc('eoc')`	`exitonclick()`
`sc('t 100 0')`	`tracer(100, 0)`
`sc('u')`	`update()`
`sc('hide')`	`hide()`
`sc('show')`	`show()`
`sc('dot 5')`	`dot(5)`
`sc('cs 42')`	`clearstamp(42)`
`sc('css')`	`clearstamps()`
`sc('css 10')`	`clearstamps(10)`
`sc('degrees')`	`degrees()`
`sc('radians')`	`radians()`
`sc('spd 5')`	`speed(5)`
`sc('spd fastest')`	`speed('fastest')`
`sc('# this is a comment')`	`# this is a comment`

Notes

The sc(skip=True) keyword argument skips all the shortcuts. Consider this the same as commenting out the sc() call.

The sc('sleep 5') shortcut exists to call the time.sleep() function.

You can pass multiple strings to sc(). For example, sc('f 100', 'r 45', 'f 100') is equivalent to sc('f 100, r 45, f 100').

The 'pc', 'fc', and 'bc' shortcuts for pen color, fill color, and background color can take a color argument as:

A color name, such as 'red'
Three 0 to 255 integer values, such as '255 0 0 (turtle.py's color mode must be set to 255)
Three 0.0 to 1.0 float values, such as '1.0 0.0 0.0 (turtle.py's color mode must be set to 255)
A hexadecimal RGB code, such as '#FF0000' (the leading # hashtag is required)

The cardinal directions shortcuts change both the heading and position of the turtle.

scs (shortcut strings) and psc (print shortcuts)

If you pass the shortcut string to scs(), instead of carrying out the turtle instructions, it will return a string of the original turtle.py function calls the sc() function would make. For example:

>>> from turtlesc import *
>>> scs('bf, f 100, r 90, f 100, r 90, ef')
'begin_fill()\nforward(100)\nright(90)\nforward(100)\nright(90)\nend_fill()\n'

If you'd like to print these out for debugging purposes, you can call psc():

>>> from turtlesc import *
>>> psc('bf, f 100, r 90, f 100, r 90, ef')
begin_fill()
forward(100)
right(90)
forward(100)
right(90)
end_fill()

Comments

You can put comments inside the shortcut string. This is especially helpful when passing multi-line strings to sc(). Comments begin with a # hashtag character and go up to the next comma (which marks the start of the next shortcut). For example:

>>> from turtlesc import *
>>> sc('''f 100
          r 100
          f 100, # This is a comment
          # Another comment
          r 100, f 100''')

Skipping Shortcuts

If you want to temporarily disable a call to sc(), you could comment it out like any other Python instruction. However, this is difficult for sc() calls that have multi-line string arguments. Instead, add the skip=True keyword argument to the call. For example, this instruction does absolutely nothing:

from turtlesc import *
sc('''f 100
      r 100
      f 100,
      r 100, f 100''', skip=True)

When you want to add these shortcuts back in, remove the skip=True text.

Recording Turtle Function Calls

If you want to collect the turtle.py function calls for all your sc() calls, add a call to begin_recording() to the start of your program. When you call end_recording() at the end, it returns a list of strings of turtle.py function calls. For example:

>>> from turtlesc import *
>>> begin_recording()
>>> sc('f 100, r 90, f 100')
3
>>> sc(' r 90,f 100, r 90, f 100')
4
>>> end_recording()
['f 100', ' r 90', ' f 100', ' r 90', 'f 100', ' r 90', ' f 100']

Interactive Drawing Mode

You can draw with the turtle like an etch a sketch by using TurtleSC's interactive mode. Make one of the following function calls:

>>> from turtlesc import *
>>> interactive()  # Use cardinal direction style (the default): WASD moves up/down, left/right
>>> interactive('turn')  # WASD moves forward/backward, turn counterclockwise/clockwise
>>> interactive('isometric')  # WASD moves up/down, and the AD, QE keys move along a 30 degree isometric plane

For all styles, the O and L key move the pen up and down, respectively. The H key moves the cursor home (to 0, 0) and clears the window. The U key is an undo. A mouse click moves the turtle with the pen up (and puts the pen back down if it had been down before.)

Details of each movement style:

'cardinal' style has the WASD and arrow keys move up/down/left/right. The QE, ZC keys also move diagonally. Pass the length argument for how long each movement should be. Diagonal movements are shortened so that a diagonal up-right movement goes to the same position as an up movement and a right movement.
'turn' style has the WASD and arrow keys move forward/backward and turn left and right relative to its current heading. Each turn is 90 degrees. However, you can also add a number like 'turn45' or 'turn30' to have it turn by a different amount for each key press.
'isometric' style has the WA keys move up/down, but the QE, AD keys move diagonally along an isometric plane.

Cardinal:

Turn:

Isometric:

What is the difference between GitHub vs. GitLab vs Alternatives?

2025-06-29T10:01:00-04:00

This article and its content were written, reviewed, and verified by a human, Al Sweigart. In my research I found that most "GitHub vs GitLab" articles are AI slop containing false or outdated information. I wrote this article with links to actual documentation pages, and not just copying what every other article on this topic says. For those who have heard of this "Git stuff," here's a summary of the differences and details. My hot take: For the needs of most individual or small group users, they're basically the same. GitLab seems to be more oriented towards self-hosting and custom configuration. Wikipedia has an extensive comparison list of source code repo hosting servers.

GitHub, GitLab, and Alternatives

While Git is the version control software you install on your computer to create and manage Git repositories, there are several websites that can host your Git repos online (i.e., "in the cloud."). There are several popular Git servers that are free or have free-tier options:

GitHub (bought and owned by Microsoft)
GitLab (developed and owned by GitLab Inc.)
GNU Savannah (developed and owned by the Free Software Foundation)
Bitbucket (bought and owned by Atlassian)
Gitea (fork of Gogs, crowdfunded)
Codeberg (open source developed by German non-profit Codeberg e.V.)
SourceForge (one of the most longstanding services, aimed at open source projects)

Azure Repos is also owned by Microsoft and is not free (you get $200 in credit for free to use in the first 30 days.)

These are "cloud hosted" servers; you sign up for an account and they run the online Git server for you. There is also "self-hosted" or "self-managed", where you run the Git server software on an online host yourself and manage/admin it yourself. GitHub-like servers on your own internet-connected servers. You have more control with self-hosting options, but you must pay for hosting and admin the server yourself. (If something happens, you need to fix it.) This article only discusses cloud hosted Git servers.

Summary of GitHub and GitLab

Feature	GitHub	GitLab
Pricing	Free and paid options	Free and paid options
Hosting	Cloud with optionally self-hosted GitHub Action runners	Cloud & self-hosting option
CI/CD	Yes, through GitHub Actions	Yes, through GitLab Runners
Permissions	Yes, with fine-grain permissions, roles, and "teams"	Yes, with fine-grained permissions, roles, and groups.
Project Management	Issue tracker/discussion forums/etc	Same
Self-Hosted Licensing	Proprietary	MIT-licensed community edition and proprietary enterprise edition

What Reddit Says

There are several posts on the r/DevOps subreddit where folks discuss GitHub vs GitLab. Here are the ones best conversations I found:

GitHub vs Gitlab (May 2023)
Gitlab CI vs Jenkins vs GitHub Actions (Jan 2023)
Full suite comparison: BitBucket vs Gitlab vs Github? (Aug 2021)
What does GitLab offer that GitHub doesn't? (Jan 2021)

If you have objections or corrections to the information in this article, contact al@inventwithpython.com

Procedurally Generating a Tic-Tac-Toe Zine with Python

2025-06-25T10:01:00-04:00

At PyCon 2025, I handed out a pocket-sized zine that lets you play a procedurally generated choose-your-own-adventure version of tic-tac-toe. The zine itself is available as a PDF for viewing on your computer and a PDF for double-sided printing. Here's how I made it using Python.

What are Zines?

I never really liked zines.

Zines (pronounced "zeens", short for "magazines") are small, self-published print booklets made by individuals or small groups, often about indie or non-mainstream topics. In the 80s and 90s when photocopying was accessible but the internet was not, so zines made sense as a way to do custom small-scale publishing. But once social media and smartphones took off, I thought of zines as an anachronism at best. Why not just have a website?

In tech, Julia Evans' Wizard Zines do a great job of explaining various technical subjects. But I kept thinking, "Couldn't this just be a website?" What changed my mind and made me see the value in zines was:

Zines can be a physical gift or souvenir that don't take up much space.
A zine will persist to be picked up later, unlike a forgotten browser tab or bookmark.
There are so many possibilities for zines with the advent of laser printers, QR codes, and procedural-generated content.
They're a fun, crafty little thing you can make for cheap.

In the future I'll write a blog post about designing zines in the 2020s, but for now I'd like to show you how I made this zine.

Choose Your Own Adventure Books

If you're like me and... of a certain age... you may remember Choose Your Own Adventure books. These books would tell a story, then prompt the reader to choose what happens next based on what page they turn to. "If you want to explore the old cave, turn to page 37. If you want to go back to the motel, turn to page 45."

You could think of a tic-tac-toe game as a Choose Your Own Adventure book with 362,880 (or 9 x 8 x 7 x 6 x 5 x 4 x 3 x 2 x 1) pages. You start on page 1 with a blank tic-tac-toe board and there are nine possible places the first player can move. Each of those nine boards in turn have eight possible moves for the second player to go to.

362,880 is a lot, but much smaller than other games like chess. And the true number is much smaller: some boards are duplicates, games can end before the entire board is filled, and the human reader's move and the zine's responding move can be collapsed into one board. And you can fit multiple tables on each page.

My zine was going to be folded such that each zine page was one-eighth of a US letter-sized page. (This is perfect for fitting into a pants pocket.) Printing duplex (i.e., on both sides of the sheet), I could get 32 zine pages for two sheets of paper. Experimenting with my Brother HL-l2460DW laser printer, I could fit 24 tic-tac-toe tables per zine page and still have it mostly readable. (Your phone's camera can be a magnifying lens if the tables are too small.)

My zines could have 768 tic-tac-toe boards, but I'd want to use some of the pages for the front & back cover, instructions, and the centerfold. Really, I would have 25 pages available for 600 (24 x 25) tic-tac-toe boards.

I wrote Python code to create the tic-tac-toe boards and then do the layout for the PDFs.

Procedurally Generated Tic-Tac-Toe

The code that generates the zine is make_ttt_zine.py in my tictactoe_zine repo.

I've created simple tic-tac-toe programs for The Big Book of Small Python Projects and Invent Your Own Computer Games with Python before. I also used tic-tac-toe as a way to explain object-oriented programming in Beyond the Basic Stuff with Python.

The make_ttt_zine.py first creates the data structures for the tic-tac-toe boards (Full code in the git repo):

"""
Tic Tac Toe Zine Maker by Al Sweigart 2025

This program creates a `boards` list of TTT board dictionaries. The dictionaries have keys of
space strings (e.g. 'TL' for top-left). The value is either 'X', 'O', or a number. The number
is an index in `boards` to the board if the human player moves on that space (along with the
zine's response). The `boards` list contains a sort of "multiverse" of all possible TTT games.

For example, run `python -i make_ttt_zine.py` to open an interactive shell after the program
finishes. The pb() function prints human-readable form of a TTT board dictionary. Call `pb(0)` to
look at the first board. Each space has an index to examine if you make that move. E.g. if `pb(0)`
shows a board with 204 in the top-left space, `pb(204)` shows the board after you move on that
space and the zine's response move.

Git repo of this code is at: https://github.com/asweigart/tictactoe_zine
Neat website on TTT strategy: https://tictactoefree.com/tips/how-to-win-in-tic-tac-toe
"""

import random, copy, io, os
from PIL import Image, ImageDraw, ImageFont
from pypdf import PdfWriter, PdfReader
random.seed(44)  # Change this to generate other games.

OUTPUT_PDF_FILENAME = 'tictactoe_zine.pdf'
ZINE_BLUNDER_RATE = 0.25  # 0.0 makes best moves. 1.0 always makes random moves.

# Constants for the Tic Tac Toe board:
ALL_SPACES = 'TL TM TR ML MM MR BL BM BR'.split()  # Top-Left, Top-Middle, Top-Right, etc.
HUMAN_MARK = 'X'
ZINE_MARK = 'O'
EMPTY = ' '

def get_blank_board():
    """Return a new dictionary with all spaces set to None."""
    board = {}
    for move in ALL_SPACES:
        board[move] = None  # None means the space is empty.
    return board

def is_winner(player, board):
    """Returns True if `player` has three in a row on `board`."""
    b = board
    # Check all possible winning combinations:
    return (b['TL'] == b['TM'] == b['TR'] == player) or \
           (b['ML'] == b['MM'] == b['MR'] == player) or \
           (b['BL'] == b['BM'] == b['BR'] == player) or \
           (b['TL'] == b['ML'] == b['BL'] == player) or \
           (b['TM'] == b['MM'] == b['BM'] == player) or \
           (b['TR'] == b['MR'] == b['BR'] == player) or \
           (b['TL'] == b['MM'] == b['BR'] == player) or \
           (b['TR'] == b['MM'] == b['BL'] == player)

def is_full(board):
    """Returns True if the board is full with no winners."""
    for space in ALL_SPACES:
        if board[space] not in (HUMAN_MARK, ZINE_MARK):
            return False  # If any space is not occupied, the board is not full.
    # If all spaces are occupied, return True:
    return True

def get_zine_move(board):
    # If the zine is making a blunder, just make a random move instead of the best move:
    if random.random() < ZINE_BLUNDER_RATE:
        free_spaces = []
        for space in ALL_SPACES:
            if board[space] is None:
                free_spaces.append(space)
        return random.choice(free_spaces)

# Stop potential forking manuever by playing the opposite corner:
    forkable_board = get_blank_board()
    forkable_board['TL'] = HUMAN_MARK
    if board == forkable_board:
        return 'BR'
    forkable_board = get_blank_board()
    forkable_board['TR'] = HUMAN_MARK
    if board == forkable_board:
        return 'BL'
    forkable_board = get_blank_board()
    forkable_board['BL'] = HUMAN_MARK
    if board == forkable_board:
        return 'TR'
    forkable_board = get_blank_board()
    forkable_board['BR'] = HUMAN_MARK
    if board == forkable_board:
        return 'TL'
    forkable_board = get_blank_board()
    forkable_board['MM'] = HUMAN_MARK
    if board == forkable_board:
        return 'TL'  # Any corner will do to respond to the center-first move.

# Make a winning move if possible:
    for space in ALL_SPACES:
        if board[space] is None:
            # Create a test board with the zine's mark in the current space:
            test_board = copy_marks(board)
            test_board[space] = ZINE_MARK
            # Check if this move would win the game for the zine:
            if is_winner(ZINE_MARK, test_board):
                return space

# Make a blocking move if necessary:
    for space in ALL_SPACES:
        if board[space] is None:
            # Create a test board with the human's mark in the current space:
            test_board = copy_marks(board)
            test_board[space] = HUMAN_MARK
            # Check if this move would win the game for the human, and block it:
            if is_winner(HUMAN_MARK, test_board):
                return space

# Make a center move if available:
    if board['MM'] is None:
        return 'MM'

# Make a corner move if available:
    free_corners = []
    for space in ('TL', 'TR', 'BL', 'BR'):
        if board[space] is None:
            free_corners.append(space)
    # If there are any free corners, pick one at random:
    if len(free_corners) > 0:
        return random.choice(free_corners)

# Make a side move if available:
    free_sides = []
    for space in ('TM', 'BM', 'ML', 'MR'):
        if board[space] is None:
            free_sides.append(space)
    # If there are any free sides, pick one at random:
    if len(free_sides) > 0:
        return random.choice(free_sides)

assert False  # Something is wrong and `board` is full.

def copy_marks(board):
    """Return a new board that only has the X and O marks copied. Do not copy board indexes."""
    new_board = get_blank_board()  # Start with a blank board.
    for space in ALL_SPACES:
        # Copy only the X & O marks, not the indexes:
        if board[space] == HUMAN_MARK or board[space] == ZINE_MARK:
            new_board[space] = board[space]
    return new_board

def get_board_text(idx):
    """Return a list of ASCII art strings that represent the board at index `idx`."""
    b = copy.copy(boards[idx])
    for space in ALL_SPACES:
        b[space] = str(b[space]).center(3)
    VERTICAL = '   |   |   '
    HORIZONTAL = '---+---+---'
    t = []
    #t.append([VERTICAL])
    t.append('%s|%s|%s' % (b['TL'], b['TM'], b['TR']))
    t.append(HORIZONTAL) #t.extend((VERTICAL, HORIZONTAL, VERTICAL))
    t.append('%s|%s|%s' % (b['ML'], b['MM'], b['MR']))
    if is_winner(HUMAN_MARK, boards[idx]):
        t.append('-YOU WIN!--') #t.extend((VERTICAL, '-YOU WIN!--', VERTICAL))
    elif is_winner(ZINE_MARK, boards[idx]):
        t.append('-ZINE WON!-') #t.extend((VERTICAL, '-ZINE WON!-', VERTICAL))
    elif is_full(boards[idx]):
        t.append('---+TIE+---') #t.extend((VERTICAL, '---+TIE+---', VERTICAL))
    else:
        t.append(HORIZONTAL) #t.extend((VERTICAL, HORIZONTAL, VERTICAL))
    t.append('%s|%s|%s' % (b['BL'], b['BM'], b['BR']))
    #t.append(VERTICAL)
    t.append('    #' + str(idx).ljust(3) + '   ')

# Replace the characters with box-drawing characters:
    for i in range(len(t)):
        t[i] = t[i].replace('-', chr(9472)).replace('|', chr(9474)).replace('+', chr(9532))
    return t

def pb(idx):
    """Print the board at index `idx` in a human-readable format. This is for debugging."""
    print('\n'.join(get_board_text(idx)))

# Create the starting board and initialize the game state:
boards = [get_blank_board()]
now_working_on_idx = 0  # The index of the board we are currently working on.
# The number of wins/losses/ties is tracked for debugging purposes:
wins = 0
losses = 0
ties = 0

while now_working_on_idx < len(boards):
    current_board = boards[now_working_on_idx]

# Check if the current board is a winner:
    if is_winner(HUMAN_MARK, current_board) or is_winner(ZINE_MARK, current_board):
        if is_winner(HUMAN_MARK, current_board):
            wins += 1
        if is_winner(ZINE_MARK, current_board):
            losses += 1
        # To finish the current board, change all None spaces to EMPTY:
        for space in ALL_SPACES:
            if current_board[space] is None:
                current_board[space] = EMPTY
        now_working_on_idx += 1  # Start work on next tic tac toe board.
        continue

# Check if the current board is full:
    if is_full(current_board):
        ties += 1
        now_working_on_idx += 1  # Start work on next tic tac toe board.
        continue

# Add new boards with every possible move for the current board:
    for space in ALL_SPACES:
        if current_board[space] is None:
            new_board = copy_marks(current_board)
            new_board[space] = HUMAN_MARK

if not (is_winner(HUMAN_MARK, new_board) or is_full(new_board)):
                # The zine makes a move:
                new_board[get_zine_move(new_board)] = ZINE_MARK

boards.append(new_board)  # Add the new board to the list.
            current_board[space] = len(boards) - 1  # Set the space to point to the new board.
    now_working_on_idx += 1

# Print the summary of the initial set of tic-tac-toe boards:
print('Number of boards:', len(boards), 'Wins:', wins, 'Losses:', losses, 'Ties:', ties)

The program creates a list in boards with a single blank starting board. Then for each board in the list, the main part of the program adds additional boards for each possible reader move followed by the zine's move. These new boards are appended to the end of the list. The index of the new board is added to the previous board that leads to it. Eventually, no new boards are appended as they are all finished with either a win, loss, or tie.

In the get_zine_move() function that picks the zine's move, the ZINE_BLUNDER_RATE value causes the zine to sometimes make a random move instead of the best move. Perfection is boring; it's more amusing for the zine to sometimes make mistakes.

Next the boards are shuffled around randomly, updating their indexes to stay consistent. Then, duplicate boards are removed (Full code in the git repo):

# Shuffle the boards into a random order, maintaining the consistency of the indexes:
for this_idx, this_board in enumerate(boards):
    if this_idx == 0: continue  # Skip the starting board. We always want to start at index 0.

# Randomly pick another board:
    other_idx = this_idx
    while other_idx == this_idx:
        other_idx = random.randint(1, len(boards) - 1)

# Swap the two boards:
    boards[this_idx], boards[other_idx] = boards[other_idx], boards[this_idx]

# Update the indexes in all of the boards to keep the indexes consistent:
    for j in range(len(boards)):
        for space in ALL_SPACES:
            if boards[j][space] == this_idx:
                boards[j][space] = other_idx
            elif boards[j][space] == other_idx:
                boards[j][space] = this_idx

# Check for duplicate tic-tac-toe boards:
dupes = set()
for i in range(len(boards)):
    for j in range(i + 1, len(boards)):
        if boards[i] == boards[j] and i not in dupes:
            dupes.add(i)

# Remove duplicates from the boards list:
dupes_removed = 0
i = 0
while i < len(boards):
    j = i + 1
    while j < len(boards):
        # NOTE: j will always be larger than i
        if boards[i] == boards[j]:
            # Duplicate found. Delete the jth board:
            del boards[j]
            dupes_removed += 1

# Re-number all indexes that pointed to the jth board to now point to the ith board:
            for k in range(len(boards)):
                for space in ALL_SPACES:
                    if boards[k][space] == j:
                        boards[k][space] = i

# Shift all indexes greater than j down one on all boards:
            for k in range(len(boards)):
                for space in ALL_SPACES:
                    if str(boards[k][space]).isdigit() and boards[k][space] > j:
                        boards[k][space] -= 1
        j += 1
    i += 1

print('Duplicates removed:', dupes_removed)
print('Number of boards after removing duplicates:', len(boards))

# If this random seed generated more than 600 boards, then the zine will not fit in 25 pages:
assert len(boards) <= 600, 'ERROR: The number of boards must be under 600 to fit them in 25 zine pages.'

# Write the boards data to a text file for later reference/debugging if needed:
print('Writing `boards` data to ttt_data.txt...')
with open('ttt_data.txt', 'w') as fo:
    fo.write(str(boards))
print('Done.')

For random seed 44, these steps reduced the number of boards from 1,062 to 580. This fits within the number of pages I wanted for the zine.

Finally, we need code that generates PNG images of each zine page, which then fits them into one US letter-sized image for each of the four printable pages. These are then put into a single PDF. We also create a PDF that is viewable on a computer instead of meant to be printed. (Full code in the git repo)

# CREATE THE ZINE PDFs:

# Check if the required files exist:
if not os.path.exists('zine_frontcover.png'):
    sys.exit('Missing zine_frontcover.png. Get from https://github.com/asweigart/tictactoe_zine')
if not os.path.exists('zine_backcover.png'):
    sys.exit('Missing zine_backcover.png. Get from https://github.com/asweigart/tictactoe_zine')
if not os.path.exists('zine_centerfold.png'):
    sys.exit('Missing zine_centerfold.png. Get from https://github.com/asweigart/tictactoe_zine')
if not os.path.exists('zine_smartphone.png'):
    sys.exit('Missing zine_smartphone.png. Get from https://github.com/asweigart/tictactoe_zine')
if not os.path.exists('zine_magnifyingglass.png'):
    sys.exit('Missing zine_magnifyingglass.png. Get from https://github.com/asweigart/tictactoe_zine')

# Create the multi-line strings of 4x6 boards for each page:
pages_text = []  # Contains the text for each page of the zine.
pages_im = []  # Contains the PIL Image objects for each page of the zine.
pages_text.append('\n'.join(get_board_text(0)))  # The first page is just the starting board.
SEP = ' '  # The separator between boards on a page.
BOARDS_PER_ROW = 4  # NOTE: If you change this, you must also change the code.
ROWS_PER_PAGE = 6  # NOTE: If you change this, you must also change the code.
ROWS_IN_PRINTED_BOARD = len(get_board_text(0))
FONT_SIZE = 24
LEFT_RIGHT_TRIM = 0
TOP_BOTTOM_TRIM = 0
IM_WIDTH = 825 + LEFT_RIGHT_TRIM  
IM_HEIGHT = 1275 + TOP_BOTTOM_TRIM
SEPARATOR_LINE_COLOR = (200, 200, 200)  # Light gray

# Create the instruction page with the first board:

# Adjust the page text to include instructions and a pointer to the board number:
pages_text[0] = """e.g. to move on top-
right, go to board #147
               %s
""" % (chr(9660)) + \
'\n'.join(['      ' + line for line in pages_text[0].splitlines()]) + \
"""
           %s
           Board number\n\n""" % (chr(9650))

with open('ttt_page_0.txt', 'w') as fo:
    fo.write(pages_text[0])
print('ttt_page_0.txt created.')

im = Image.new('RGB', (IM_WIDTH, IM_HEIGHT), (255, 255, 255))
draw = ImageDraw.Draw(im)
font = ImageFont.truetype('Courier New Bold.ttf', FONT_SIZE * 2)
bbox = draw.textbbox((0, 0), pages_text[0], font=font)
draw.multiline_text(((IM_WIDTH - bbox[2]) // 2, (IM_HEIGHT - bbox[3]) // 2), pages_text[0], fill=(0, 0, 0), font=font)

# Add instructions to the page:
instructions = 'You are X. The zine is O.\nStart on this page at\nboard #0. Pick a space &\ngo to its numbered board.'
bbox = draw.textbbox((0, 0), instructions, font=font)
draw.multiline_text(((IM_WIDTH - bbox[2]) // 2, 40), instructions, fill=(0, 0, 0), font=font)

# Add magnifying lens advice to the page:
help = 'Text too small?\nUse your phone camera\nas a magnifying glass.'
bbox = draw.textbbox((0, 0), help, font=font)
draw.multiline_text(((IM_WIDTH - bbox[2]) // 2, (IM_HEIGHT - bbox[3] - 40)), help, fill=(0, 0, 0), font=font)

# Add the smartphone and magnifying glass images:
im.paste(Image.open('zine_smartphone.png'), (150, IM_HEIGHT - 400))
im.paste(Image.open('zine_magnifyingglass.png'), (350, IM_HEIGHT - 400))

im.save('ttt_page_0.png')
pages_im.append(im)
print('ttt_page_0.png created.')

# The remaining pages are 4x6 tic-tac-toe boards pages:
for i in range(1, len(boards), BOARDS_PER_ROW * ROWS_PER_PAGE):
    page = ''
    for y in range(ROWS_PER_PAGE):
        for row in range(ROWS_IN_PRINTED_BOARD):
            # Create a row of boards for the current page:
            page_row_text = []
            for x in range(BOARDS_PER_ROW):
                # Get the board text for the current board:
                if i + x + (y * BOARDS_PER_ROW) < len(boards):
                    page_row_text.append(get_board_text(i + x + (y * BOARDS_PER_ROW))[row])
            page += SEP.join(page_row_text) + '\n'
        page += '\n'
    # Add the board numbers to the bottom of the board:
    page += ('#' + str(i) + ' to #' + str(i + BOARDS_PER_ROW * ROWS_PER_PAGE - 1)).center(BOARDS_PER_ROW * 12 - 1) + '\n'
    pages_text.append(page)

# Write the page text to a file for later reference/debugging if needed:
    with open('ttt_page_%s.txt' % (len(pages_text) - 1), 'w') as fo:
        fo.write(page)
    print('ttt_page_%s.txt created.' % (len(pages_text) - 1))

# Create the PNG image of the page:
    im = Image.new('RGB', (IM_WIDTH, IM_HEIGHT), (255, 255, 255))
    draw = ImageDraw.Draw(im)
    font = ImageFont.truetype('Courier New Bold.ttf', FONT_SIZE)
    bbox = draw.textbbox((0, 0), page, font=font)
    draw.multiline_text(((IM_WIDTH - bbox[2]) // 2, (IM_HEIGHT - bbox[3]) // 2), page, fill=(0, 0, 0), font=font)    
    im.save('ttt_page_%s.png' % (len(pages_text) - 1))
    pages_im.append(im)

print('ttt_page_%s.png created.' % (len(pages_text) - 1))
print('Done writing page files..')

# Write the pages text to a file for later reference/debugging if needed:
with open('ttt_page_ALL.txt', 'w') as fo:
    fo.write('\n\n\n\n'.join(pages_text))

def add_separator_lines(im):
    """Add the separator lines to the zine sheet images."""
    draw = ImageDraw.Draw(im)
    draw.line([(0, IM_HEIGHT), (IM_WIDTH * 4, IM_HEIGHT)], fill=SEPARATOR_LINE_COLOR)
    draw.line([(IM_WIDTH, 0), (IM_WIDTH, IM_HEIGHT * 2)], fill=SEPARATOR_LINE_COLOR)
    #draw.line([(IM_WIDTH * 2, 0), (IM_WIDTH * 2, IM_HEIGHT * 2)], fill=SEPARATOR_LINE_COLOR)
    draw.line([(IM_WIDTH * 3, 0), (IM_WIDTH * 3, IM_HEIGHT * 2)], fill=SEPARATOR_LINE_COLOR)

# Create the sheet images, which are composed of 4x2 zine pages. Sheets are US letter landscape.

# Sheet 1 front:
im = Image.new('RGB', (IM_WIDTH * 4, IM_HEIGHT * 2), (255, 255, 255))
im.paste(pages_im[0], (0, 0))
im.paste(pages_im[25], (IM_WIDTH, 0))
im.paste(pages_im[2], (IM_WIDTH * 2, 0))
im.paste(pages_im[23], (IM_WIDTH * 3, 0))
im.paste(pages_im[4], (0, IM_HEIGHT))
im.paste(pages_im[21], (IM_WIDTH, IM_HEIGHT))
im.paste(pages_im[6], (IM_WIDTH * 2, IM_HEIGHT))
im.paste(pages_im[19], (IM_WIDTH * 3, IM_HEIGHT))
add_separator_lines(im)
im = im.transpose(Image.ROTATE_270)

im.save('sheet_1_front.png')
print('Sheet 1 front created.')

# Sheet 1 back:
im = Image.new('RGB', (IM_WIDTH * 4, IM_HEIGHT * 2), (255, 255, 255))
im.paste(pages_im[24], (0, 0))
im.paste(pages_im[1], (IM_WIDTH, 0))
im.paste(Image.open('zine_backcover.png'), (IM_WIDTH * 2, 0))
im.paste(Image.open('zine_frontcover.png'), (IM_WIDTH * 3, 0))
im.paste(pages_im[20], (0, IM_HEIGHT))
im.paste(pages_im[5], (IM_WIDTH, IM_HEIGHT))
im.paste(pages_im[22], (IM_WIDTH * 2, IM_HEIGHT))
im.paste(pages_im[3], (IM_WIDTH * 3, IM_HEIGHT))
add_separator_lines(im)
im = im.transpose(Image.ROTATE_90)
im.save('sheet_1_back.png')
print('Sheet 1 back created.')

# Sheet 2 front:
im = Image.new('RGB', (IM_WIDTH * 4, IM_HEIGHT * 2), (255, 255, 255))
im.paste(pages_im[18], (0, 0))
im.paste(pages_im[7], (IM_WIDTH, 0))
im.paste(pages_im[13].transpose(Image.ROTATE_180), (IM_WIDTH * 2, 0))
im.paste(pages_im[12].transpose(Image.ROTATE_180), (IM_WIDTH * 3, 0))
im.paste(pages_im[16], (0, IM_HEIGHT))
im.paste(pages_im[9], (IM_WIDTH, IM_HEIGHT))
im.paste(pages_im[14], (IM_WIDTH * 2, IM_HEIGHT))
im.paste(pages_im[11], (IM_WIDTH * 3, IM_HEIGHT))
add_separator_lines(im)
im = im.transpose(Image.ROTATE_270)
im.save('sheet_2_front.png')
print('Sheet 2 front created.')

# Sheet 2 back:
im = Image.new('RGB', (IM_WIDTH * 4, IM_HEIGHT * 2), (255, 255, 255))
im.paste(Image.open('zine_centerfold.png'), (0, 0))
im.paste(pages_im[8], (IM_WIDTH * 2, 0))
im.paste(pages_im[17], (IM_WIDTH * 3, 0))
im.paste(pages_im[10], (IM_WIDTH * 2, IM_HEIGHT))
im.paste(pages_im[15], (IM_WIDTH * 3, IM_HEIGHT))
add_separator_lines(im)
im = im.transpose(Image.ROTATE_90)
im.save('sheet_2_back.png')
print('Sheet 2 back created.')

# Create the PDF from the sheet images:
def image_to_pdf_bytes(image_path):
    with Image.open(image_path) as im:
        im = im.convert("RGB")  # PDF requires RGB
        buffer = io.BytesIO()
        im.save(buffer, format="PDF", resolution=300.0)  # 300 DPI for high quality
        buffer.seek(0)
        return buffer

def create_pdf_with_images(image_paths, output_pdf):
    writer = PdfWriter()

for path in image_paths:
        pdf_buffer = image_to_pdf_bytes(path)
        reader = PdfReader(pdf_buffer)
        writer.add_page(reader.pages[0])

with open(output_pdf, "wb") as f:
        writer.write(f)

create_pdf_with_images(['sheet_1_front.png', 'sheet_1_back.png', 'sheet_2_front.png', 'sheet_2_back.png'], OUTPUT_PDF_FILENAME)
print('Print PDF %s created.' % (OUTPUT_PDF_FILENAME))

# Create the PDF that can be read linearly on a computer:
writer = PdfWriter()
for page_im in [Image.open('zine_frontcover.png'), Image.open('zine_centerfold.png')] + pages_im + [Image.open('zine_backcover.png')]:
    page_im = page_im.convert('RGB')
    buffer = io.BytesIO()
    page_im.save(buffer, format="PDF", resolution=300.0) 
    buffer.seek(0)
    reader = PdfReader(buffer)
    writer.add_page(reader.pages[0])
with open('tictactoe_zine_linear.pdf', "wb") as f:
    writer.write(f)

print('Linear PDF tictactoe_zine_linear created.')
print('Done.')

Zine Design and Layout

There was a lot of trial and error involved when designing the layout of the zine. I settled on two double-sided sheets, with eight zine pages per sheet side. This would make the zine a total of 32 pages (including the front and back cover.)

I also chose to spend four zine pages for a centerfold that acts as an advertisement for the zine's git repo. This requires taking care to not cut the four zine pages of the centerfold or accidentally staple them down.

In the future, I plan on making a Python app for creating these PDFs based on the number of pages and zine page size.

Full details are available from in the git repo's README.

I forgot to bring business cards with me to PyCon, but the zines turned out to be a great substitute since they had my website and contact info on them. I ended up giving away all 150 of them by the third day of the conference. People liked them; they made for a nice souvenir that was different from the usual sticker or flyer (the centerfold was a neat kick, especially).

This was a great project that ended up taking about four days. It's given me a new interest in making zines and software tools to help others make zines. Keep an eye out for a future blog post on the topic.

Fabric.js Tutorial Part 6

2024-05-04T10:06:00-04:00

Part 5 of a tutorial series on the Fabric.js canvas/graphics library for JavaScript, we'll learn how to change the size of shapes by scaling them with the scale() method. We'll also get some more practice drawing in general. We'll draw this forest:

This is Part 6 of the Fabric.js tutorial. You can see the previous Part 5 or start at the beginning with Part 1.

In this tutorial part, we'll learn how to change the size of shapes by scaling them with the scale() method. We'll also get some more practice drawing in general. We'll draw this forest:

The full code for this star is at at https://inventwithpython.com/fabric-js-tutorial/fabric-js-forest.html or on JSFiddle. Let's examine each part individually:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fabric.js Drawing a Forest</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.min.js"></script>
</head>

<body>
  <!-- The HTML <canvas> element: -->
  <canvas id="forestCanvasId" width="200" height="200" style="border: 1px solid black;"></canvas>
</body>

This is the standard boilerplate HTML that we've used in previous tutorial parts. The <canvas> element's id is "forestCanvasId".

<script>
let canvasObj = new fabric.Canvas('forestCanvasId');
canvasObj.backgroundColor = '#F1DBC3';

let ground = new fabric.Circle({radius: 350, left: -250, top: 125, fill: '#F8F4E8'});
canvasObj.add(ground);

We'll start by setting the background color with canvasObj.backgroundColor = '#F1DBC3'; and then use a large circle for the lighter color ground with let ground = new fabric.Circle({radius: 350, left: -250, top: 125, fill: '#F8F4E8'}); We'll need to add this circle immediately to the canvas object so that it is beneath all of the trees we'll create and add later.

let branches = new fabric.Triangle({left: 10, top: 100, width: 30, height: 50, fill: '#38755b'});
let trunk = new fabric.Line([25, 140, 25, 160], {stroke: 'brown', strokeWidth: 6, originX: 'center'});
let treeGroup = new fabric.Group([branches, trunk]);
canvasObj.add(treeGroup);

The tree shape that we'll create is a simple green triangle and a wide brown line shape. To make it easier to clone, these shapes are in a single group and added the group to the canvas.

treeGroup.clone(function(clonedObj) { 
  clonedObj.scale(0.8);
  clonedObj.left = 100;
  canvasObj.add(clonedObj);
});

Here we call clone() to make a copy of the tree group, changing the size to 80% of and the left edge position of the clone before adding it to the canvas.

treeGroup.clone(function(clonedObj) { 
  clonedObj.scale(1.1);
  clonedObj.left = 120;
  clonedObj.top = 100;
  canvasObj.add(clonedObj);
});

treeGroup.clone(function(clonedObj) { 
  clonedObj.scale(0.6);
  clonedObj.left = 170;
  clonedObj.top = 110;
  canvasObj.add(clonedObj);
});
</script>
</html>

Here we finish by making two more trees with the clone() method and changing their position and size.

This is the end of the Fabric.js tutorial for now. If you'd like to see more parts to this tutorial, send Al Sweigart a message at Mastodon or email at al@inventwithpython.com saying you found the first few parts helpful. Special thanks to Hunor Márton Borbély for the SVG tutorial that inspired this Fabric.js tutorial.

Fabric.js Tutorial Part 5

2024-05-04T10:05:00-04:00

Part 5 of a tutorial series on the Fabric.js canvas/graphics library for JavaScript, where we learn about grouping, cloning, and rotating shapes.

This is Part 5 of the Fabric.js tutorial. You can see the previous Part 4 or start at the beginning with Part 1.

In this tutorial, we'll draw a star shape. Instead of writing the code to draw every part of the star, we'll instead create one of the five "shards" of the star and then group, clone, and rotate it. The final image will look like this:

The full code for this star is at at https://inventwithpython.com/fabric-js-tutorial/fabric-js-star-complete.html or on JSFiddle. Let's examine each part individually:

Drawing a Single Shard of a Star

Let's start by drawing a single shard out of two polygons:

Here is the code for drawing this shard:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fabric.js Drawing Stars</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.min.js"></script>
</head>

<body>
  <!-- The HTML <canvas> element: -->
  <canvas id="starCanvasId" width="200" height="200" style="border: 1px solid black;"></canvas>
</body>

This is the standard boilerplate HTML that we've used before, with a <canvas> element that has an id of "starCanvasId".

<script>
let starCanvasObj = new fabric.Canvas('starCanvasId');

// Create two polygons for a star shard:
let shardHalf1 = new fabric.Polygon([
  {x: 0, y: 0}, {x: 36, y: -50}, {x: 0, y: -100}], {
  left: 100, top: 0, fill: "#EDD8B7"
});

This is the polygon for the right-side triangle. The X and Y coordinates I provide here are later shifted by the left and top settings for the shape.

let shardHalf2 = new fabric.Polygon([
  {x: 0, y: 0}, {x: -36, y: -50}, {x: 0, y: -100}], {
  left: 64, top: 0, fill: "#E5C39C"
});

starCanvasObj.add(shardHalf1);
starCanvasObj.add(shardHalf2);
</script>
</html>

This is the polygon for the left-side triangle. Just to display these shards on the canvas, we call the add() method. Notice that you can select these shards individually on the canvas. In the next section, we will group these two polygons into a single shape.

Putting the Star Shard Triangles into a Group

One way to make Fabric.js shapes easier to work with is by grouping them together. For a complex drawing, you can then rotate, scale, and transform it as a single group. Notice that in the following canvas, you can click on the unified group rather than the individual shards:

Let's look at the parts of this code individually:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fabric.js Putting Shards into a Group</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.min.js"></script>
</head>

<body>
  <!-- The HTML <canvas> element: -->
  <canvas id="starCanvasId" width="200" height="200" style="border: 1px solid black;"></canvas>
</body>

<script>
let starCanvasObj = new fabric.Canvas('starCanvasId');

// Create two polygons for a star shard:
let shardHalf1 = new fabric.Polygon([
  {x: 0, y: 0}, {x: 36, y: -50}, {x: 0, y: -100}], {
  left: 100, top: 0, fill: "#EDD8B7"
});

let shardHalf2 = new fabric.Polygon([
  {x: 0, y: 0}, {x: -36, y: -50}, {x: 0, y: -100}], {
  left: 64, top: 0, fill: "#E5C39C"
});

This is the standard boilerplate HTML along with the previous code creating two polygons for the star shard.

// Create a group of the two shard halves:
let shardGroup = new fabric.Group([shardHalf1, shardHalf2], {
  centeredRotation: false, originX: 'center', originY: 'bottom'
});
starCanvasObj.add(shardGroup);

</script>
</html>

To group multiple shapes, whether Polygon, Rect, Circle, Path, or others, you can pass them in an array as the first argument to fabric.Group(). In our example, we are passing [shardHalf1, shardHalf2] to fabric.Group() to return a new Group object that contains these two shapes.

The second argument to this function is a JavaScript object of settings similar to the one you pass to shapes. In our example, we'll set centeredRotation to false because later when we rotate the group, we want it to rotate around the bottom-center point of the shape instead of the center. To specify the bottom-center point (as opposed to any other point or corner of the shape), we also set originX to 'center' and originY to 'bottom'.

This sets us up for cloning and rotating the star shard group in the next section.

Cloning and Rotating Star Shards

To create the complete star shape, we will clone the group we've created, then rotate the shard group in 72 degree increments and clone it again. The end result will be five star shard groups (you can select them in this canvas):

Let's examine each part of this code individually:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fabric.js Cloning Star Shards</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.min.js"></script>
</head>

<body>
  <!-- The HTML <canvas> element: -->
  <canvas id="starCanvasId" width="200" height="200" style="border: 1px solid black;"></canvas>
</body>


<script>
let canvasObj = new fabric.Canvas('starCanvasId');

// Create two polygons for a star shard:
let shardHalf1 = new fabric.Polygon([
  {x: 0, y: 0}, {x: 36, y: -50}, {x: 0, y: -100}], {
  left: 100, top: 0, fill: "#EDD8B7"
});

let shardHalf2 = new fabric.Polygon([
  {x: 0, y: 0}, {x: -36, y: -50}, {x: 0, y: -100}], {
  left: 64, top: 0, fill: "#E5C39C"
});

// Create a group of the two shard halves:
let shardGroup = new fabric.Group([shardHalf1, shardHalf2], {
  originX: 'center', originY: 'bottom', centeredRotation: false
});
canvasObj.add(shardGroup);

Here is the boilerplate HTML and JavaScript from the previous section. It creates the star shard and then groups it as a Group object in the shardGroup variable.

// Create an array to hold the cloned groups:
let clonedGroups = [];
for (let rotAmount of [0, 72, -72, 144, -144]) {
  shardGroup.rotate(rotAmount);

  shardGroup.clone(function(clonedObj) { 
    canvasObj.add(clonedObj);
    clonedGroups.push(clonedObj);
  });
}
canvasObj.remove(shardGroup);
</script>
</html>

Inside of a for...of loop, we rotate the shard group by calling the rotate() method at 0, 72, -72, 144, and -144 degrees. At each of these rotations, we create a duplicate of the shardGroup by calling the clone() method.

The clone() method is rather frustrating. Instead of returning the cloned object, you must pass a callback function to the method which is then called with the newlycreated clone. In our callback function, we call add() so that the cloned object (now in its rotated position) appears on the canvas.

To ensure that we'll have access to this cloned object for later use, we also add it to the clonedGroups array. This program doesn't make use of this array, but it could be handy if you wanted to later have access to the cloned shard groups.

With five clones for the five shards of the star, we don't need the original group in shardGroup anymore. We can remove it from the canvas by calling canvasObj.remove(shardGroup). This is sort of the opposite of canvasObj.add(shardGroup). (In fact, it was unnecessary to add the original shard group to the canvas in the first place. But I wanted to introduce the remove() method to compliment the add() method.)

This tutorial continues on to Part 6. Special thanks to Hunor Márton Borbély for the SVG tutorial that inspired this Fabric.js tutorial.

Fabric.js Tutorial Part 4

2024-05-04T10:04:00-04:00

Part 4 of a tutorial series on the Fabric.js canvas/graphics library for JavaScript, where we learn about drawing with paths.round color of a canvas as well as the shapes fabric.Polygon and fabric.Line.

You can see the previous Part 3 or start at the beginning with Part 1.

In this part, we'll draw shapes using SVG's language for paths. Paths are custom shapes that are ideal for creating complex vector shapes that the usual Rect, Circle, Polyline, and other shape classes cannot easily construct. Fabric.js reuses SVG's path syntax, which is helpful considering how much overlap there is between the two graphics systems.

Drawing a Hamburger Icon

We'll begin this tutorial by using paths to draw the "hamburger icon" used by many mobile apps:

Unlike a fabric.Polyline shape, paths don't have to be connected lines. And as we'll see in future tutorial parts, paths can also include curves in addition to lines.

The full code for this hamburger icon is at at https://inventwithpython.com/fabric-js-tutorial/fabric-js-path-hamburger.html or on JSFiddle. Let's examine each part individually:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fabric.js Path - Hamburger Icon</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.min.js"></script>
</head>

<body>
  <!-- The HTML <canvas> element: -->
  <canvas id="hamburgerCanvasId" width="200" height="200" style="border: 1px solid black;"></canvas>
</body>


<script>
let hamburgerCanvasObj = new fabric.Canvas('hamburgerCanvasId');

This is the HTML boilerplate that we've used in previous tutorial parts. The <canvas> element that we create has an id of 'hamburgerCanvasId'.

let hamburgerIconPath = new fabric.Path(`
  M -40 -40
  L  40 -40 
  M -40   0 
  L  40   0 
  M -40  40 
  L  40  40`, {
    stroke: '#333333', strokeWidth: 25, strokeLineCap: 'round', left: 40, top: 40
  });

The mini-language passed to fabric.Path as a string value defines a shape. The two most common "commands" in this language are the move-to and line-to commands. For example, the hamburgerIconPath we create starts by moving an imaginary cursor to the X and Y coordinates of -40, -40 with M -40 -40.

Whitespace is flexible for path commands, so we'll use the ` backtick character to make a multi-line JavaScript string. We only need a single space to separate the parts of a command (such as the M and -40) but we can put in additional spaces, indentation, and newlines for readability.

From the X, Y coordinates of -40, -40, we then have the path draw a visible line to the X, Y coordinates of 40, -40 with L 40 -40. This draws the top line of the hamburger icon. The next four commands moves the imaginary cursor to the start of the middle line (M -40 0) and draws it (L 40 0), then moves the imaginary cursor to the start of the bottom line (M -40 40) and draws it (L 40 40).

You can also use commas to separate the parts of commands: M -40,-40 instead of M -40 -40

The second argument is a JavaScript object that describes the style of the path's stroke color, width, and line cap style along with position the shape on the canvas. We've seen this before with the other Fabric.js shapes in previous tutorial parts.

hamburgerCanvasObj.add(hamburgerIconPath);
</script>
</html>

As in previous tutorial parts, the shape objects we created won't appear on the canvas until we call the add() method for them.

Drawing a Heart

For our next example, let's draw a simple heart shape by setting a large stroke width and a round line cap style. We could create this with fabric.Polyline, but let's see how a fabric.Path shape can also make a heart.

The full code for this heart path is at at https://inventwithpython.com/fabric-js-tutorial/fabric-js-path-heart.html or on JSFiddle. Let's examine each part individually:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fabric.js Path - Heart</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.min.js"></script>
</head>

<body>
  <!-- The HTML <canvas> element: -->
  <canvas id="heartCanvasId" width="200" height="200" style="border: 1px solid black;"></canvas>
</body>

This is the usual boilerplate HTML we've used before.

<script>
let canvasObj = new fabric.Canvas('heartCanvasId');
let heartPath = new fabric.Path(`
  M -30 -20 
  L   0  10 
  L  30 -20`, {
    stroke: 'black', strokeWidth: 80, strokeLineCap: 'round', left: 30, top: 40
  });

heartCanvasObj.add(heartPath);
</script>
</html>

After creating the fabric.Canvas object from the <canvas> element with id heartCanvasId. The three SVG path commands we give move the imaginary cursor the top left end of the heart (M -30 -20), then draw a line to the bottom point of the heart (L 0 10), then draw a second line segment to the top right end of the heart (L 30 -20g)

Drawing an Arrow

Next, let's draw a simple red arrow using paths. We'll break up the construction of the arrow into three examples. The first is just half of an arrow:

The full code for this heart path is at at https://inventwithpython.com/fabric-js-tutorial/fabric-js-path-heart.html or on JSFiddle. Let's examine each part individually:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fabric.js Path - Arrow 1</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.min.js"></script>
</head>

<body>
  <!-- The HTML <canvas> element: -->
  <canvas id="arrow1CanvasId" width="200" height="200" style="border: 1px solid black;"></canvas>
</body>

This is the usual HTML boilerplate we've been using. The <canvas> element has an id of "Arrow1CanvasId".

<script>
let arrow1CanvasObj = new fabric.Canvas('arrow1CanvasId');
let arrow1Path = new fabric.Path(`
  M -70 0 
  L 70 0 
  L 30 -50`, {
    stroke: '#D1495B', strokeWidth: 25, strokeLineCap: 'round', strokeLineJoin: 'round', fill: 'transparent', left: 10, top: 40
  });

arrow1CanvasObj.add(arrow1Path);
</script>
</html>

The path we draw is two simple line segments. We move the cursor into position with M -70 0 and draw the two line segments with L 70 0 and L 30 -50. The end caps of the line are rounded due to the strokeLineCap setting of 'round', but notice that the middle point of the two segments is also rounded because of the strokeLineJoin setting of 'round'. If we didn't specify the strokeLineJoin setting, it would default to 'miter' (out of possible settings 'miter', 'bevel', and 'round'.)

Here is what the arrow with a 'miter' line join looks like:

By adding M 70 0 L 30 50 to the fabric.Path string, we can complete the arrow:

This tutorial continues on to Part 5. Special thanks to Hunor Márton Borbély for the SVG tutorial that inspired this Fabric.js tutorial.

Fabric.js Tutorial Part 3

2024-05-04T10:03:00-04:00

Part 3 of a tutorial series on the Fabric.js canvas/graphics library for JavaScript, where we learn how to set the background color of a canvas as well as the shapes fabric.Polygon and fabric.Line.

This is Part 3 of the Fabric.js tutorial. You can see the previous Part 2 or start at the beginning with Part 1.

Drawing a House

Let's get more practice by drawing this house:

The full code is at https://inventwithpython.com/fabric-js-tutorial/fabric-js-house.html or on JSFiddle. Let's examine each part individually:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fabric.js House</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.min.js"></script>
</head>

<body>
  <!-- The HTML <canvas> element: -->
  <canvas id="houseCanvasId" width="200" height="200" style="border: 1px solid black;"></canvas>
</body>

This is the boilerplate HTML that we've used before in previous tutorial parts. It has a <canvas> element with an id of "houseCanvasId".

<script>
let canvasObj = new fabric.Canvas('houseCanvasId');
canvasObj.backgroundColor = 'lightblue';

To set the background color of the <canvas> element, set the backgroundColor property to an HTML color name or RGB color code. The same color settings we've applied to stroke and fill in the previous tutorials can be used for backgroundColor here.

Avoid setting the CSS background-color property of the <canvas> element when using Fabric.js, as this can causing weird rendering issues such as the background color covering up the entire canvas.

let frame = new fabric.Polygon([
  {x: -65, y: 80}, {x: -65, y: -10}, {x: 0, y: -70}, {x: 65, y: -10}, {x: 65, y:80}], {
  stroke: 'black', strokeWidth: 2, fill: 'white', left: 20, top: 40
});

let roof = new fabric.Polyline([
  {x: -75, y: -8}, {x: 0, y: -78}, {x: 75, y: -8}], {
  stroke: 'red', strokeWidth: 10, strokeLineCap: 'round', fill: 'transparent', left: 6, top: 32
});

We'll create a new fabric.Polygon shape for the white frame of the house and a red fabric.Polyline for the roof. These shapes are similar: the difference between them is that a fabric.Polygon shape automatically draws one more line from its last point to its first point. A fabric.Polyline will not do this, although both shapes will fill their interior spaces with color. This is why the red roof needs to have a fill property of 'transparent', otherwise it draws a black (the default fill color in Fabric.js) triangle.

let door = new fabric.Rect({
  left: 40, top: 130, width: 30, height: 60, stroke: 'black', fill: 'red'
});

let doorKnob = new fabric.Circle({
  radius: 3, stroke: 'black', fill: 'white', left: 45, top: 160
});

let windowFrame = new fabric.Rect({
  left: 90, top: 120, width: 40, height: 40, stroke: 'black', fill: '#fdea96'
});

The door, door knob, and window are made from the circle and rectangle shapes we've created in earlier parts of this tutorial.

let windowVerticalLine = new fabric.Line([110, 120, 110, 160], {stroke: 'black'});

let windowHorizontalLine = new fabric.Line([90, 140, 130, 140], {stroke: 'black'});

The two lines across the yellow window are created with fabric.Line shapes. The first argument to fabric.Line() is an array of four numbers for the start and end points of the line: [x1, y1, x2, y2] followed by the usual object of settings. As with the array-of-points argument to fabric.Polyline() and fabric.Polyon(), you can use the <canvas> element's coordinate system and leave the left and top arguments at their default of 0.

canvasObj.add(frame);
canvasObj.add(roof);
canvasObj.add(door);
canvasObj.add(doorKnob);
canvasObj.add(windowFrame);
canvasObj.add(windowVerticalLine);
canvasObj.add(windowHorizontalLine);
</script>
</html>

As in previous tutorial parts, the shape objects we created won't appear on the canvas until we call the add() method for them.

This tutorial continues on to Part 4. Special thanks to Hunor Márton Borbély for the SVG tutorial that inspired this Fabric.js tutorial.

Fabric.js Tutorial Part 2

2024-05-04T10:02:00-04:00

This is Part 2 of the Fabric.js tutorial canvas/graphics library for JavaScript, where we learn about Polyline shapes and styling shapes by drawing a gingerbread figure.

You can start at the beginning with Part 1.

Drawing a Gingerbread Figure

Let's learn about a new shape, polyline, and how to add styling such as rounded corners and rotation by drawing this gingerbread figure:

The full code is at https://inventwithpython.com/fabric-js-tutorial/fabric-js-gingerbread-figure.html or on JSFiddle. Let's examine each part individually:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fabric.js Gingerbread Figure</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.min.js"></script>
</head>

<body>
  <!-- The HTML <canvas> element: -->
  <canvas id="gingerbreadCanvasId" width="200" height="200" style="border: 1px solid black;"></canvas>
</body>

Again, this is the standard HTML boilerplate that we have for our page but I include it to have a complete example that is viewable in an actual web browser. Note that the ID of the <canvas> element is "gingerbreadCanvasId".

<script>
// Create a Fabric.js "Canvas" object that is tied to the HTML <canvas> element:
let canvasObj = new fabric.Canvas('gingerbreadCanvasId');

const GINGERBREAD_COLOR = '#CD803D';

let head = new fabric.Circle({
  left: 100, top: 50, fill: GINGERBREAD_COLOR, radius: 40, originX: 'center', originY: 'center'
})

Multiple shapes use the color #CD803D so let's save it to the constant GINGERBREAD_COLOR. We'll create a new fabric.Circle object for the gungerbread figure's head. Notice that because the originX and originY properties are set to 'center', the left and top settings refer to the X and Y coordinates of the shape's center point and not the top-left corner. Confusingly, we still have to use the left and top property names.

let arms = new fabric.Polyline(
  [{x: 0, y: 0}, {x: 100, y:0}], {
    stroke: GINGERBREAD_COLOR, strokeWidth: 40, strokeLineCap: 'round', fill: 'transparent', left: 100, top: 100, originX: 'center', originY: 'center'
  });

let legs = new fabric.Polyline(
  [{x: 0, y: 60}, {x: 30, y: 0}, {x: 60, y: 60}], {
    stroke: GINGERBREAD_COLOR, strokeWidth: 40, strokeLineCap: 'round', fill: 'transparent', left: 100, top: 140, originX: 'center', originY: 'center'
  });

To create the arms and legs, we'll use a new shape called polyline which represents a connected series of lines. The first argument to the fabric.Polyline is an array of objects with x and y properties.

The arms only have two points: [{x: 0, y: 0}, {x: 100, y:0}] These X and Y coordinates can be relative to the shape's own Cartesian coordinate system, and then the shape is position on the <canvas> element with the left and top properties.

You can alternatively use the <canvs> element's coordinate system (where the 0, 0 origin is the top-left corner of the <canvas> element) for the array of points and then leave the left and top properties as their default 0 and 0 values.

The legs are made from a second polyline that has three points: [{x: 0, y: 60}, {x: 30, y: 0}, {x: 60, y: 60}]

The color and thickness of the polyline is set by the stroke and strokeWidth properties in this object. Setting the stroke color to GINGEBREAD_COLOR gives us the following shapes:

Adding a strokeWidth of 40 makes these lines thicker:

However, to give the gingerbread figure a more rounded look, we set the strokeLineCap to 'round'. (It can also be set to 'square' or 'butt', with the default being 'butt'.)

Note that setting strokeLineCap only applies to the two ends and not for the middle connecting points of the polyline. The connection between the two line segments in the legs polyline can also be rounded if you set the strokeLineJoin property to 'round'. (It can also be set to 'bevel' or 'miter', with the default being 'miter'.)

It may seem odd that a polyline has a fill property, but the area that is filled in is described by the polygon shape that a polyline draws. The complete shape includes connecting the end point to the start point. By default, the fill color is black. To make the fill invisible and only draw a line, we must set fill to 'transparent'.

Later we'll use a fabric.Polygon shape, which is the same thing as fabric.Polyline but its stroke connects the last point back to the first point.

let mouth = new fabric.Rect({
  left: 100, top: 70, originX: 'center', originY: 'center', fill: 'transparent', stroke: 'white', strokeWidth: 6, width: 40, height: 10, rx: 5, ry: 5, angle: 15
});

The mouth is a white rectangle outline, but we give it rounded corners by setting the horiztonal and vertical radius of the corners with rx and ry to 5 pixels. The rectangle is also rotated counter-clockwise by 15 degrees by setting angle to 15. Note that this rotation is specified in number of degrees and not number of radians.

let leftEye = new fabric.Circle({
  left: 90, top: 40, fill: 'transparent', stroke: 'white', radius: 10, originX: 'center', originY: 'center'
});

let rightEye = new fabric.Circle({
  left: 110, top: 40, fill: 'transparent', stroke: 'white', radius: 5, originX: 'center', originY: 'center'
});

let topButton = new fabric.Circle({
  left: 100, top: 90, originX: 'center', originY: 'center', radius: 4, fill: 'black', stroke: 'black'
});

let bottomButton = new fabric.Circle({
  left: 100, top: 110, originX: 'center', originY: 'center', radius: 4
});

The last shapes are four circles for the eyes and buttons. These use the same concepts we have seen before.

canvasObj.add(head);
canvasObj.add(arms);
canvasObj.add(legs);
canvasObj.add(leftEye);
canvasObj.add(rightEye);
canvasObj.add(mouth);
canvasObj.add(topButton);
canvasObj.add(bottomButton);
</script>

Finally, none of these shapes will appear on the canvas until we call the add() method for each of them.

This tutorial continues on to Part 3. Special thanks to Hunor Márton Borbély for the SVG tutorial that inspired this Fabric.js tutorial.

Fabric.js Tutorial Part 1

2024-05-04T10:01:00-04:00

This is part 1 my tutorial series on the Fabric.js canvas/graphics library for JavaScript, where we learn about drawing basic shapes like rectangles, circles, and triangles to draw pine trees.

What is Fabric.js?

Fabric.js is a JavaScript library that makes drawing on HTML5 <canvas> elements easier than using the native Canvas API. This Fabric.js tutorial emulates the format of Hunor Márton Borbély's SVG Tutorial at svg-tutorial.com: short demonstrations that you can enter into a text editor and view in your local browser.

I dislike code snippets that you can't actually run yourself on your own computer with modification. I will always give you the complete HTML for each example that you can copy and open in your browser on your computer. There are no missing sections or "leave it to the reader" omissions. Furthermore, the Fabric.js examples on each page are live examples and not just screenshots. I also provide JSFiddle links with the example code for you to modify.

The Fabric.js website has tutorials, documentation, and a gallery of examples but you won't need to consult that site to follow this tutorial series. This tutorial does assume you have basic HTML and JavaScript knowledge.

Drawing Rectangles and Circles

Let's create a small example with red and blue rectangles on a <canvas> element that will look like this:

In Fabric.js, you draw basic shapes by creating shape objects with JavaScript code. You can also write text, load images, and apply image filters, but we'll explore that later. You can see the complete code for this example on its own page at fabric-js-rects-and-circle.html. Right-click the page and select "View Source" to view the HTML and JavaScript code. You can also view this code on JSFiddle.

Notice that you can drag the objects around the canvas as well as scale and rotate them. This feature is automatically provided by Fabric.js. To disable this, replace the fabric.Canvas() code (we'll see this in the next section) with fabric.StaticCanvas(), as in this output where you can't move the shapes around:

Notice that for objects added to the static canvas, you cannot select them and move them around.

Let's look at each part of the HTML and JavaScript individually:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fabric.js Rects and Circle</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.js"></script>
</head>

This is some standard HTML boilerplate for a basic web page header. I'm loading the Fabric.js library from a free CDN (Content Distribution Network) provided by Cloudflare, but you can put the fabric.js file on your own web host and link to it instead. This tutorial uses Fabric.js version 5.3.1. The CDN also provides a minified version for faster loading if you change the filename to fabric.min.js in this URL.

<body>
  <!-- The HTML <canvas> element: -->
  <canvas id="mainCanvasId" width="400" height="400" style="border: 1px solid black;"></canvas>
</body>

The <canvas> element is the area where the drawing takes place. You can think of it as a <img> element but its contents come from JavaScript code instead of an image file. Instead of using the native Canvas API to do the drawing, you can use Fabric.js's API. I've given this <canvas> element a width and height of 400 pixels, as well as a thin black border for easier viewing.

<script>
// Create a Fabric.js "Canvas" object that is tied to the HTML <canvas> element:
let canvasObj = new fabric.Canvas('mainCanvasId');

First, create a new Canvas object by passing fabric.Canvas() the id of the <canvas> element, 'mainCanvasId'. This is necessary since there could be multiple <canvas> elements on the web page.

// Create a Fabric.js "Rect" object that represents a rectangle:
let rectObj = new fabric.Rect({
  left: 100, top: 50, fill: 'red', stroke: 'blue', width: 80, height: 30
});

// The rectangle won't appear on the canvas until it is added:
canvasObj.add(rectObj);

We'll draw a rectangle by creating a Rect object. Pass a JS object with keys 'left' and 'top' for the X and Y coordinate of the left and top edge of the rectangle. The interior fill color for this rectangle will be red and the outline stroke will be blue. The size of the rectangle is 80 pixels wide and 30 pixels tall. (Remember that we made the total size of the <canvas> element 400 x 400.)

You won't see this rectangle on the canvas until you call the Canvas.add() method with the Rect objects.

// Create a second rectangle:
let rectObj2 = new fabric.Rect({
  left: 50, top: 100, fill: 'green', width: 50, height: 50
});

canvasObj.add(rectObj2);

We'll create a second rectangle, this time with a green fill and size of 50 pixels by 50 pixels.

// Create a circle:
let circleObj = new fabric.Circle({
  // Note that the radius is half the width of the circle.
  radius: 100, fill: '#FF00FF', left: 200, top: 200
});

canvasObj.add(circleObj);
</script>

The Circle object must be added to the Canvas object the same way the Rect objects are, or you will not see them on the canvas. Note that objects added to the canvas most recently are on top of any objects added earlier.

Next, let's create a magenta circle with a radius of 100 pixels by calling the fabric.Circle() function. The fill property in the object passed to this function is set to '#FF00FF', an HTML RGB code for maximum red, no green, and maximum blue to produce magenta. Notice that the position of the circle is set by its left and top edge location. If you want to position the circle by supplying its center X and Y coordinates, include originX: 'center', originY: 'center' in the object passed to fabric.Circle(). Somewhat confusingly, the left and top parameter names will now set the center position of the shape instead of the left and top edge.

For example, changing the code to let circleObj = new fabric.Circle({radius: 100, fill: '#FF00FF', left: 200, top: 200, originX: 'center', originY: 'center'}); will make the canvas look like this:

Note that forgetting to set either the width or height in fabric.Rect() or the radius in fabric.Circle() will cause that shape to not render on the canvas. There will be no error in the browser's developer console to indicate that an error has occured; the shape will simply not appear.

Review:

Put <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.js"></script> in your HTML file to load the Fabric.js library from a free CDN.
Create the <canvas> element with <canvas id="mainCanvasId" width="400" height="400" style="border: 1px solid black;"></canvas>
The code let canvasObj = new fabric.Canvas('mainCanvasId'); creates a Canvas object.
The code let rectObj = new fabric.Rect({ left: 100, top: 50, fill: 'red', stroke: 'blue', width: 80, height: 30 }); creates a rectangle.
The code let circleObj = new fabric.Circle({radius: 100, fill: '#FF00FF', left: 200, top: 200}); creates a circle. Instead of width and height, it has a radius.
You must call canvasObj.add(rectObj); to make a shape actually appear on the canvas; creating it is not enough.
When creating a new shape, you can set originX to left, center, or right and set originY to top, center, bottom to change which point on the shape the left and top properties set. (However, these properties will still confusingly be named left and top.)
If a shape doesn't appear on the canvas, check that you remembered to supply a width and height property (for rectangles) or a radius property (for circles). The left and top properties may also have the position of the shape outside the view of the canvas.

Project: Draw a Pine Tree

Let's draw a pine tree with the fabric.Triangle shape. We'll create this tree out of three triangles and one rectangle:

The full code is at fabric-js-pine-tree.html or on JSFiddle. Let's examine each part individually:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Fabric.js Pine Tree</title>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdnjs.cloudflare.com/ajax/libs/fabric.js/5.3.1/fabric.min.js"></script>
</head>

<body>
  <!-- The HTML <canvas> element: -->
  <canvas id="treeCanvasId" width="200" height="200" style="border: 1px solid black;"></canvas>
</body>

This is the standard boilerplate HTML for a web page. Note that the ID we use for the <canvas> element is treeCanvasId and it is a 200 x 200 pixels in size.

<script>
// Create a Fabric.js "Canvas" object that is tied to the HTML <canvas> element:
let canvasObj = new fabric.Canvas('treeCanvasId');

let branches1 = new fabric.Triangle({
  width: 80, height: 80, fill: '#234236', left: 100, top: 20
});

let branches2 = new fabric.Triangle({
  width: 100, height: 60, fill: '#0C5C4C', left: 90, top: 70
});

let branches3 = new fabric.Triangle({
  width: 110, height: 50, fill: '#38755B', left: 85, top: 110
});

First, we need a fabric.Canvas object to be the Fabric.js representation of the HTML <canvas> element. Then branches of our pine tree will be green triangles that we create by creating fabric.Triangle objects. These isosceles triangles point upwards, but we'll learn how to rotate them in the next tutorial part.

Note that the size and position are given the same way as fabric.Rect rectangles: width, height, left, and top. We don't specify a triangle's shape and size by specifying three pairs of X and Y coordinates. (For this kind of triangle, we'd use the fabric.Polygon shape that we'll cover in later tutorial parts.) We color them with different shades of green: #234236, #0C5C4C, and #38755B.

let stump = new fabric.Rect({
  width: 20, height: 30, fill: 'brown', left: 130, top: 150
});

The brown stump will be a rectangle created with a fabric.Rect object.

canvasObj.add(branches3);
canvasObj.add(branches2);
canvasObj.add(branches1);
canvasObj.add(stump);
</script>

We've created these four shape objects, but they won't appear on the canvas until after we call the add() method. I want the top branches (in branches1) to appear on top of the other triangles, so I need to add it last.

Review:

The fabric.Triangle shape draws isoceles triangles pointing upwards with let branches1 = new fabric.Triangle({width: 80, height: 80, fill: '#234236', left: 100, top: 20});
The order that the shapes are created doesn't matter, rather the first shapes added with add() will be on the bottom of the canvas underneath shapes added later.

This tutorial continues on to Part 2. Special thanks to Hunor Márton Borbély for the SVG tutorial that inspired this Fabric.js tutorial.

Make Lively Movement Animation with PyTweening's Tweening Functions

2024-02-20T12:00:00-05:00

Tweening functions allow you to easily add many different styles of natural-seeming movement to the graphics in your program. In this blog post, you'll learn about how tweening functions can make more lively movement animations using Pygame and the PyTweening third-party library. Tweening functions apply to any programming language, but this tutorial has actual Python code for you to run and experiment with. Start by installing these libraries by running pip install pygame and pip install pytweening from the terminal. Then follow along with the code examples.

We won't be looking at "spite animation" where, say, you have several frames of a walking animation that you play in a loop. Instead, we'll focus on making static images move around their window. (Though 2D images are often called "sprites" in a video game context, so that is what this tutorial will call them.) To do this, we move the sprite over a few seconds, draw the sprite to the window, pause for a few milliseconds, and then repeat. This gives the illusion that the sprite is moving around the application's window.

Moving a Sprite

Here's a Python program using the Pygame library named tweening_demo_addition.py that moves a cat image across the window to the right. The cat starts with its left side at X coordinate 50 and top side at Y coordinate 100. The program keeps adding 10 to it, moving the cat to the right by 10 pixels, until the left side is at 400. Download the cat.png file from https://inventwithpython.com/cat.png and save it to the same folder as the following program, tweening_demo_addition.py:

# Basic Pygame setup stuff:
import pygame, sys, time
from pygame.locals import QUIT, KEYUP, MOUSEBUTTONUP

pygame.init()  # Initialize the Pygame library.
BG_COLOR = (0, 255, 220)  # The RGB color for the background.
DISPLAY_SURF = pygame.display.set_mode((600, 600))  # Create a 600x600 window.
fps_clock = pygame.time.Clock()  # Frames-per-second timer.

# Get the cat image and set its position:
cat_surface = pygame.Surface((80, 80))
cat_surface.fill((250, 0, 130))  # Use a pink 80x80 square for the "cat"
# If you don't have a cat.png file, comment out this line:
cat_surface = pygame.image.load('cat.png')  # Use a cat image for the cat sprite.
cat_rect = cat_surface.get_rect()
cat_rect.left = 50  # Set left edge of cat sprite at X coordinate 50.
cat_rect.top = 100  # Set top edge of cat sprite at Y coordinate 100.

# Draw the cat and pause for a couple seconds:
DISPLAY_SURF.fill(BG_COLOR)  # Clear the window.
DISPLAY_SURF.blit(cat_surface, cat_rect)  # Draw the cat.
pygame.display.update()  # Render the screen.
pygame.event.get()  # Required on macOS to display the window, for some reason.
time.sleep(2)

debug_output = True
print('DEBUG\tLEFT\tTOP')  # DEBUG OUTPUT
while True:
    # Terminate when the user closes the window or presses a key.
    for event in pygame.event.get():  # Event handling loop.
        if event.type in (QUIT, KEYUP, MOUSEBUTTONUP):
            pygame.quit()
            sys.exit()

    if cat_rect.left < 400:
        # Move the cat to the right by 10 pixels:
        cat_rect.left += 10
        if debug_output:
            print('DEBUG\t', cat_rect.left, '\t', cat_rect.top)  # DEBUG OUTPUT
    else:
        time.sleep(1)  # Pause for a second after the animation is done. (User can't quit during this second. No biggie though.)
        cat_rect.left = 50  # Reset the cat to the start.
        debug_output = False  # Only show debug output for the first movement, then disable it.

    DISPLAY_SURF.fill(BG_COLOR)  # Clear the window.
    DISPLAY_SURF.blit(cat_surface, cat_rect)  # Draw the cat.
    pygame.display.update()  # Render the screen.
    fps_clock.tick(30)  # Run at 30 frames per second.

(If you can't download the cat.png image file and/or get the FileNotFoundError: No file 'cat.png' found in working directory error message, just add a # to the beginning of the cat_surface = pygame.image.load('cat.png') line to comment it out. The program will use a generic pink square instead.)

When you run this program, the cat sprite starts at an X coordinate of 50 (in the 600-pixel wide window) and moves to the right by 10 pixels each frame until it reaches the X coordinate 400. (The animation then resets and repeats.) The debug output from the print() calls displays the left and top attributes of the sprite's position:

DEBUG   LEFT    TOP
DEBUG    60      100
DEBUG    70      100
DEBUG    80      100
DEBUG    90      100
DEBUG    100     100
DEBUG    110     100
DEBUG    120     100
DEBUG    130     100
DEBUG    140     100
DEBUG    150     100
DEBUG    160     100
DEBUG    170     100
DEBUG    180     100
DEBUG    190     100
DEBUG    200     100
DEBUG    210     100
DEBUG    220     100
DEBUG    230     100
DEBUG    240     100
DEBUG    250     100
DEBUG    260     100
DEBUG    270     100
DEBUG    280     100
DEBUG    290     100
DEBUG    300     100
DEBUG    310     100
DEBUG    320     100
DEBUG    330     100
DEBUG    340     100
DEBUG    350     100
DEBUG    360     100
DEBUG    370     100
DEBUG    380     100
DEBUG    390     100
DEBUG    400     100

You can see that the cat's X coordinate increases by 10 for each frame while the Y coordinate stays the same. This is a straightforward way to code movement. But first, it can become tedious to program all sprite movements this way (especially when not moving perfectly horizontally or vertically). Second, the movement looks boring: there's no realistic acceleration or slow down, but rather a machine-like instant start, a constant speed, and an instant stop. We can handle the first case with a linear tweening function.

A tweening function (also called an easing function) is used to give XY coordinates "in between" a start and end point. Originally it was used in traditional cartoon animation, where an animator would draw key frames and pass them on to assistants who would draw the "in between" frames of animation. The tween function itself takes a floating-point number input between 0.0 (the start) and 1.0 (the end) called the interpolation factor and returns a number between 0.0 and 1.0. This can be used to provide a variety of movement animation effects.

Interpolation Between a Start and End Point

Let's imagine the movement from start to finish as a journey of the value in a variable named i (the interpolation factor) from 0.0 (the start) to 1.0 (the end). We can use a couple math equations to interpolate the X and Y coordinates between the start and end points:

x = start_x + (i * (end_x - start_x))

y = start_y + (i * (end_y - start_y))

With these two equations, we can get the XY coordinate of the midpoint between the start and end XY coordinates by setting i to 0.5. These equations work no matter what the start and end XY coordinates are. If you set i to 0.1, then the XY coordinates they give you will be 10% from the starting XY coordinate towards the end XY coordinate. If i is 0.0, the XY coordinates will be identical to the start_x and start_y coordinates. The same goes for setting i to 1.0: you get the end XY coordinates.

Now we don't have to worry about adding/subtracting the correct amount to the sprite's position. Instead, we can calculate each position along the path.

The following tweening_demo_interpolation.py program is similar to the previous program, except now we use the two interpolation equations and only increase the i interpolation factor value:

# You can try changing the start/end positions:
START_X, START_Y = 50, 100
END_X, END_Y = 370, 250


# Basic Pygame setup stuff:
import pygame, sys, time, random
from pygame.locals import QUIT, KEYUP, MOUSEBUTTONUP

pygame.init()  # Initialize the Pygame library.
BG_COLOR = (0, 255, 220)  # The RGB color for the background.
DISPLAY_SURF = pygame.display.set_mode((600, 600))  # Create a 600x600 window.
fps_clock = pygame.time.Clock()  # Frames-per-second timer.

# Get the cat image and set its position:
cat_surface = pygame.Surface((80, 80))
cat_surface.fill((250, 0, 130))  # Use a pink 80x80 square for the "cat"
# If you don't have a cat.png file, comment out this line:
cat_surface = pygame.image.load('cat.png')
cat_rect = cat_surface.get_rect()
cat_rect.left = START_X
cat_rect.top = START_Y
i = 0.0  # The interpolation factor starts at 0.0.

# Draw the cat and pause for a second:
DISPLAY_SURF.fill(BG_COLOR)  # Clear the window.
pygame.draw.rect(DISPLAY_SURF, (255, 255, 255), (START_X, START_Y, cat_rect.width, cat_rect.height))  # Draw white rectangle at start.
pygame.draw.rect(DISPLAY_SURF, (0, 0, 0), (END_X, END_Y, cat_rect.width, cat_rect.height))  # Draw black rectangle at end.
DISPLAY_SURF.blit(cat_surface, cat_rect)  # Draw the cat.
pygame.display.update()  # Render the screen.
pygame.event.get()  # Required on macOS to display the window, for some reason.
time.sleep(1)  # Pause at the start before moving.

debug_output = True
print('DEBUG\ti\tLEFT\tTOP')  # DEBUG OUTPUT
while True:
    # Terminate when the user closes the window or presses a key.
    for event in pygame.event.get():  # Event handling loop.
        if event.type in (QUIT, KEYUP, MOUSEBUTTONUP):
            pygame.quit()
            sys.exit()

    if round(i, 5) <= 1.0:  # round() here is necessary for a weird float rounding issue.
        # Set cat position based on the interpolation factor.
        cat_rect.left = START_X + (i * (END_X - START_X))
        cat_rect.top = START_Y + (i * (END_Y - START_Y))
        if debug_output:
            print('DEBUG\t', round(i, 3), '\t', cat_rect.left, '\t', cat_rect.top)  # DEBUG OUTPUT

        i += 0.02  # Increase the interpolation factor.
    else:
        time.sleep(1)  # Pause for a second after the animation is done. (User can't quit during this second. No biggie though.)
        i = 0.0  # Reset the interpolation factor to 0.0.
        debug_output = False

        # Uncomment the following to randomly change the start & stop positions:
        # START_X = random.randint(0, 600 - cat_rect.width)
        # START_Y = random.randint(0, 600 - cat_rect.height)
        # END_X = random.randint(0, 600 - cat_rect.width)
        # END_Y = random.randint(0, 600 - cat_rect.height)

    DISPLAY_SURF.fill(BG_COLOR)  # Clear the window.
    pygame.draw.rect(DISPLAY_SURF, (255, 255, 255), (START_X, START_Y, cat_rect.width, cat_rect.height))  # Draw white rectangle at start.
    pygame.draw.rect(DISPLAY_SURF, (0, 0, 0), (END_X, END_Y, cat_rect.width, cat_rect.height))  # Draw black rectangle at end.
    DISPLAY_SURF.blit(cat_surface, cat_rect)  # Draw the cat.
    pygame.display.update()  # Render the screen.
    fps_clock.tick(30)  # Run at 30 frames per second.

When you run this program, you'll see the same smooth, constant movement of the cat (though this time at an angle instead of perfectly horizontal.) Try editing the values of the START_X, START_Y, END_X, and END_Y variables to change the start and end position of the sprite. You won't need to change any other code; the same code works for the path from any start to any end. The program can set up random start and end points if you uncomment the code after # Uncomment the following to randomly change the start & stop positions:.

When you run the program with the start point as 50, 100 and end point as 370, 250, the debugging output is:

DEBUG   i   LEFT    TOP
DEBUG    0.0     50      100
DEBUG    0.02    56      103
DEBUG    0.04    63      106
DEBUG    0.06    69      109
DEBUG    0.08    76      112
DEBUG    0.1     82      115
DEBUG    0.12    88      118
DEBUG    0.14    95      121
DEBUG    0.16    101     124
DEBUG    0.18    108     127
DEBUG    0.2     114     130
DEBUG    0.22    120     133
DEBUG    0.24    127     136
DEBUG    0.26    133     139
DEBUG    0.28    140     142
DEBUG    0.3     146     145
DEBUG    0.32    152     148
DEBUG    0.34    159     151
DEBUG    0.36    165     154
DEBUG    0.38    172     157
DEBUG    0.4     178     160
DEBUG    0.42    184     163
DEBUG    0.44    191     166
DEBUG    0.46    197     169
DEBUG    0.48    204     172
DEBUG    0.5     210     175
DEBUG    0.52    216     178
DEBUG    0.54    223     181
DEBUG    0.56    229     184
DEBUG    0.58    236     187
DEBUG    0.6     242     190
DEBUG    0.62    248     193
DEBUG    0.64    255     196
DEBUG    0.66    261     199
DEBUG    0.68    268     202
DEBUG    0.7     274     205
DEBUG    0.72    280     208
DEBUG    0.74    287     211
DEBUG    0.76    293     214
DEBUG    0.78    300     217
DEBUG    0.8     306     220
DEBUG    0.82    312     223
DEBUG    0.84    319     226
DEBUG    0.86    325     229
DEBUG    0.88    332     232
DEBUG    0.9     338     235
DEBUG    0.92    344     238
DEBUG    0.94    351     241
DEBUG    0.96    357     244
DEBUG    0.98    364     247
DEBUG    1.0     370     250

Linear Tween

We can enhance the interpolation equations into something a bit more exciting with tweening functions. We'll start with a boring example of the linear tween function that produces the same behavior as our interpolation code. The PyTweening library It's boring because the returned output is the same as the input: pytweening.linear(0.0) returns 0.0 and pytweening.linear(1.0) returns 1.0. Run the following code to verify this:

import pytweening
i = 0.0
while i <= 1.0:
    print(round(i, 2), '\t', round(pytweening.linear(i), 2))
    i += 0.1

The output of this is:

0.0      0.0
0.1      0.1
0.2      0.2
0.3      0.3
0.4      0.4
0.5      0.5
0.6      0.6
0.7      0.7
0.8      0.8
0.9      0.9
1.0      1.0

As you can see, the output number is the same as the input. But this linear tweening function will make our animation program easy to understand at first. Later, all we need to do is swap out a different tweening function from PyTweening to get different effects.

If you look at the source of the Pytweening library, you'll notice the code for pytweening.linear() (minus the docstring) is just one line code:

def linear(n):  # type: (Union[int, float]) -> Union[int, float]
    return n

While the linear tween is the simplest of all tweening functions, the others aren't much more complicated:

def easeOutQuad(n):  # type: (Union[int, float]) -> Union[int, float]
    return -n * (n - 2)

They are very math-y, but we'll look at them in detail later. Run the following code with pytweening.easeOutQuad() instead of the previous example's pytweening.linear():

import pytweening
i = 0.0
while i <= 1.0:
    print(round(i, 2), '\t', round(pytweening.easeOutQuad(i), 2))
    i += 0.1

The output of this is:

0.0      0.0
0.1      0.19
0.2      0.36
0.3      0.51
0.4      0.64
0.5      0.75
0.6      0.84
0.7      0.91
0.8      0.96
0.9      0.99
1.0      1.0

Notice that while easeOutQuad()'s numbers are different from linear()'s numbers, note that the outputs are both 0.0 when the interpolation factor (the input) is 0.0 and 1.0 when the interpolation factor is 1.0. This is common for almost every tweening function so that puts the sprite at the starting XY position at the start of the movement and the ending XY position at the end of the movement. It's the numbers in between that give different movement behavior.

Let's swap out our interpolation code with code that uses PyTweening's tweening functions. The following is tweening_demo_pytweening.py, which has the same behavior as the previous tweening_demo_interpolation.py program but uses the PyTweening library instead:

# You can try changing the start/end positions:
START_X, START_Y = 50, 100
END_X, END_Y = 370, 250


# Basic Pygame setup stuff:
import pygame, sys, time, random, pytweening
from pygame.locals import QUIT, KEYUP, MOUSEBUTTONUP

pygame.init()  # Initialize the Pygame library.
BG_COLOR = (0, 255, 220)  # The RGB color for the background.
DISPLAY_SURF = pygame.display.set_mode((600, 600))  # Create a 600x600 window.
fps_clock = pygame.time.Clock()  # Frames-per-second timer.

# Get the cat image and set its position:
cat_surface = pygame.Surface((80, 80))
cat_surface.fill((250, 0, 130))  # Use a pink 80x80 square for the "cat"
# If you don't have a cat.png file, comment out this line:
cat_surface = pygame.image.load('cat.png')
cat_rect = cat_surface.get_rect()  # Get the position & size rectangle of the cat.
i = 0.0  # The interpolation factor starts at 0.0.
cat_rect.left = START_X
cat_rect.top = START_Y

# Draw the cat for a couple seconds before starting the animation:
DISPLAY_SURF.fill(BG_COLOR)  # Clear the window.
pygame.draw.rect(DISPLAY_SURF, (255, 255, 255), (START_X, START_Y, cat_rect.width, cat_rect.height))  # Draw white rectangle at start.
pygame.draw.rect(DISPLAY_SURF, (0, 0, 0), (END_X, END_Y, cat_rect.width, cat_rect.height))  # Draw black rectangle at end.
DISPLAY_SURF.blit(cat_surface, cat_rect)  # Draw the cat.
pygame.display.update()  # Render the screen.
pygame.event.get()  # Needed on macOS to make the window appear for some reason.
time.sleep(1)  # Pause at the start before moving.

# Run the animation:
debug_output = True
print('DEBUG\ti\tti\tLEFT\tTOP')  # DEBUG OUTPUT
while True:
    # Terminate when the user closes the window, presses a key, or clicks the mouse:
    for event in pygame.event.get():  # Event handling loop.
        if event.type in (QUIT, KEYUP, MOUSEBUTTONUP):
            pygame.quit()
            sys.exit()

    if round(i, 5) <= 1.0:  # round() here is necessary for a weird float rounding issue.
        # i is the input, ti is the tween output.
        # Uncomment one of these lines to select a different tweening function:
        ti = pytweening.linear(i)  # Same speed throughout
        # ti = pytweening.easeOutQuad(i)  # Starts fast, slows to stop
        # ti = pytweening.easeInQuad(i)  # Starts slow, accelerates, then decelerates
        # ti = pytweening.easeInOutQuad(i)  # Starts and ends slow
        # ti = pytweening.easeOutBounce(i)  # Ends with a bounce
        # ti = pytweening.easeInOutElastic(i)  # Start and end with a stretchy animation

        # Set cat position based on the tweening interpolation factor.
        cat_rect.left = START_X + (ti * (END_X - START_X))
        cat_rect.top = START_Y + (ti * (END_Y - START_Y))
        if debug_output:
            print('DEBUG\t', round(i, 3), '\t', round(ti, 3), '\t', cat_rect.left, '\t', cat_rect.top)  # DEBUG OUTPUT

        i += 0.02  # Increase the interpolation factor.
    else:
        time.sleep(1)  # Pause for a second after the animation is done. (User can't quit during this second. No biggie though.)
        i = 0.0  # Reset the interpolation factor to 0.0.
        debug_output = False  # Disable the debug output.
        # Uncomment the following to randomly change the start & stop positions:
        # START_X = random.randint(0, 600 - cat_rect.width)
        # START_Y = random.randint(0, 600 - cat_rect.height)
        # END_X = random.randint(0, 600 - cat_rect.width)
        # END_Y = random.randint(0, 600 - cat_rect.height)

    DISPLAY_SURF.fill(BG_COLOR)  # Clear the window.
    pygame.draw.rect(DISPLAY_SURF, (255, 255, 255), (START_X, START_Y, cat_rect.width, cat_rect.height))  # Draw white rectangle at start.
    pygame.draw.rect(DISPLAY_SURF, (0, 0, 0), (END_X, END_Y, cat_rect.width, cat_rect.height))  # Draw black rectangle at end.
    DISPLAY_SURF.blit(cat_surface, cat_rect)  # Draw the cat.
    pygame.display.update()  # Render the screen.
    fps_clock.tick(30)  # Pause enough to run at 30 frames per second.

The debug output from this program looks like this:

DEBUG   i   ti  LEFT    TOP
DEBUG    0.0     0.0     50      100
DEBUG    0.02    0.02    56      103
DEBUG    0.04    0.04    63      106
DEBUG    0.06    0.06    69      109
DEBUG    0.08    0.08    76      112
DEBUG    0.1     0.1     82      115
DEBUG    0.12    0.12    88      118
DEBUG    0.14    0.14    95      121
DEBUG    0.16    0.16    101     124
DEBUG    0.18    0.18    108     127
DEBUG    0.2     0.2     114     130
DEBUG    0.22    0.22    120     133
DEBUG    0.24    0.24    127     136
DEBUG    0.26    0.26    133     139
DEBUG    0.28    0.28    140     142
DEBUG    0.3     0.3     146     145
DEBUG    0.32    0.32    152     148
DEBUG    0.34    0.34    159     151
DEBUG    0.36    0.36    165     154
DEBUG    0.38    0.38    172     157
DEBUG    0.4     0.4     178     160
DEBUG    0.42    0.42    184     163
DEBUG    0.44    0.44    191     166
DEBUG    0.46    0.46    197     169
DEBUG    0.48    0.48    204     172
DEBUG    0.5     0.5     210     175
DEBUG    0.52    0.52    216     178
DEBUG    0.54    0.54    223     181
DEBUG    0.56    0.56    229     184
DEBUG    0.58    0.58    236     187
DEBUG    0.6     0.6     242     190
DEBUG    0.62    0.62    248     193
DEBUG    0.64    0.64    255     196
DEBUG    0.66    0.66    261     199
DEBUG    0.68    0.68    268     202
DEBUG    0.7     0.7     274     205
DEBUG    0.72    0.72    280     208
DEBUG    0.74    0.74    287     211
DEBUG    0.76    0.76    293     214
DEBUG    0.78    0.78    300     217
DEBUG    0.8     0.8     306     220
DEBUG    0.82    0.82    312     223
DEBUG    0.84    0.84    319     226
DEBUG    0.86    0.86    325     229
DEBUG    0.88    0.88    332     232
DEBUG    0.9     0.9     338     235
DEBUG    0.92    0.92    344     238
DEBUG    0.94    0.94    351     241
DEBUG    0.96    0.96    357     244
DEBUG    0.98    0.98    364     247
DEBUG    1.0     1.0     370     250

Instead of using the interpolation factor i variable directly in the interpolation code, this program passes i to pytweening.linear() to get the "tweened" interpolation factor for the ti variable. This ti variable is used in the familiar interpolation code instead of i.

This doesn't make a difference for a linear tween because ti is always the same as i. But now we can swap out tweening functions in the PyTweening library to select what kind of movement behavior we want. For example, let's use the pytweening.easeOutQuad() function by commenting out the ti = pytweening.linear(i) and then uncommenting the # ti = pytweening.easeOutQuad(i) line from this part of the tweening_demo_pytweening.py program:

# Uncomment one of these lines to select a different tweening function:
ti = pytweening.linear(i)  # Same speed throughout
# ti = pytweening.easeOutQuad(i)  # Starts fast, slows to stop
# ti = pytweening.easeInQuad(i)  # Starts slow, accelerates, then decelerates
# ti = pytweening.easeInOutQuad(i)  # Starts and ends slow
# ti = pytweening.easeOutBounce(i)  # Ends with a bounce
# ti = pytweening.easeInOutElastic(i)  # Start and end with a stretchy animation

With this one-line code change, you've changed the machine-like constant speed movement to a more natural, starts-fast-then-slows-to-a-stop movement. It's small details like this that can give the sprite movement a much more polished presentation. This concept is sometimes called "juice", and there is a great talk by Martin Jonasson and Petri Purho from Nordic Game Jam called "Juice It or Lose It" that explains several simple ways (including tweening functions) to improve your video games and animation.

These short videos also have great tips for adding polish to your games and animations:

Try uncommenting other lines and re-running the program to see the effect of different tweens. Notice that the easeOutBounce() tween produces output that reverses direction to give a bouncy effect, while the easeInOutElastic() function produces output that is less than 0.0 and greater than 1.0 as the animation briefly shoots past the endpoint in an elastic rubber band effect.

If you want to tightly control the value of the i interpolation factor, try the following tweening_demo_all.py program, which displays six cats using six different tweening functions from the PyTweening library. As you move the mouse cursor from the left edge of the window to the right edge, the interpolation factor goes from 0.0 to 1.0:

import pytweening

# Try changing the various tween functions here:
TWEENS = [pytweening.linear, pytweening.easeOutQuad, pytweening.easeInQuad, pytweening.easeInOutQuad, pytweening.easeOutBounce, pytweening.easeInOutElastic]


# Basic Pygame setup stuff:
import pygame, sys, time, random
from pygame.locals import QUIT, KEYUP, MOUSEBUTTONUP, MOUSEMOTION

pygame.init()  # Initialize the Pygame library.
BG_COLOR = (0, 255, 220)  # The RGB color for the background.
DISPLAY_SURF = pygame.display.set_mode((600, 600))  # Create a 600x600 window.
fps_clock = pygame.time.Clock()  # Frames-per-second timer.

# Don't change these:
START_X, START_Y = 50, 0
END_X, END_Y = 400, 0

# Get the cat image and set its position:
cats = []
for idx in range(6):  # There are six cats that will be animated:
    cat = {}
    cat['surface'] = pygame.Surface((80, 80))
    cat['surface'].fill((250, 0, 130))  # Use a pink 80x80 square for the "cat"
    # If you don't have a cat.png file, comment out this line:
    cat['surface'] = pygame.image.load('cat.png')
    cat['rect'] = cat['surface'].get_rect()  # Get the position & size rectangle of the cat.
    cat['rect'].left = START_X
    cat['rect'].top = START_Y + (idx * 100)
    cat['tween'] = TWEENS[idx]
    cats.append(cat)

i = 0.0  # The interpolation factor starts at 0.0.

font = pygame.font.Font('freesansbold.ttf', 28)

# Run the animation:
while True:
    # Terminate when the user closes the window, presses a key, or clicks the mouse:
    for event in pygame.event.get():  # Event handling loop.
        if event.type == QUIT:
            pygame.quit()
            sys.exit()
        elif event.type == MOUSEMOTION:
            mouse_x, mouse_y = event.pos
            i = mouse_x / 600  # Set i based on mouse cursor position in the window.

    for idx in range(6):
        ti = cats[idx]['tween'](i)  # i is the input, ti is the tween output.

        # Set cat position based on the tweening interpolation factor.
        cats[idx]['rect'].left = START_X + (ti * (END_X - START_X))

    DISPLAY_SURF.fill(BG_COLOR)  # Clear the window.
    for idx in range(6):  # Draw all six cats.
        pygame.draw.rect(DISPLAY_SURF, (255, 255, 255), (START_X, START_Y + (idx * 100), cats[idx]['rect'].width, cats[idx]['rect'].height))  # Draw white rectangle at start.
        pygame.draw.rect(DISPLAY_SURF, (0, 0, 0), (END_X, END_Y + (idx * 100), cats[idx]['rect'].width, cats[idx]['rect'].height))  # Draw black rectangle at end.
        DISPLAY_SURF.blit(cats[idx]['surface'], cats[idx]['rect'])  # Draw the cat.

    # Set window caption to the current i value:
    pygame.display.set_caption('Move mouse to adjust: i = ' + str(round(i, 3)))

    pygame.display.update()  # Render the screen.
    fps_clock.tick(30)  # Pause enough to run at 30 frames per second.

You can use the tweening_demo_all.py program to explore the different tweening functions in a way that you can physically control by moving the mouse.

For further information check out the PyPI page for PyTweening (which contains graphs of each tweening function) and the PyTweening source code on GitHub.

Book Review: Geometric Patterns with Creative Coding

2024-01-15T12:00:00-05:00

Geometric Patterns with Creative Coding: Coding for the Arts by Selçuk Artut. Published by Apress July 2023. 420 pages.

4 stars. A fine introduction for programmers and non-programming artists alike.

I came across Selçuk Artut’s Geometric Patterns with Creative Coding while researching several topics on computer-generated art for beginners. I admit, the single 1-star review for this book annoyed me enough to read and review. I’ve come away believing that this book certainly deserves wider and better attention than that.

This book is a decent starting point for anyone who wants to program computers to create generative art. The first several chapters of art history are slim summaries, but they give you plenty of things to look up later if you’re interested (though you can also skip these chapters entirely if you aren’t.) The real meat of the book starts about 60 pages in with the briefest introductions to programming concepts before the next 300 pages have example after example of interesting tessellations (23 in total) along with code and breakdowns of the pattern motifs.

The primary downside of this book is that it doesn’t offer a lot of hand-holding. The explanation of the programming and math concepts is sufficient, but a bit more elaboration would help some readers with coding experience. But you certainly don’t need to be a programmer or “good at math” to follow along.

This book gives back as much as you put in: you have to put aside any feelings of intimidation and be willing to dive into the examples. (You don’t even need to install anything; you can use the browser-based Processing interpreter at https://editor.p5js.org/ to run the example art programs.) The primary utility comes from the many tessellating pattern programs it offers. Take the time to understand them. Make your small modifications to the code and watch how they change the resulting artwork. They are examples to be studied rather than just read once.

This book is rather raw and unpolished. The art history chapters are the briefest introduction and the programming and math sections make it hard for the non-programmer to figure out how to apply these ideas. I give this 4 stars because I feel there’s a lot that could be improved: comments in the source code could add more context, descriptive variable names instead of single letters, links to source code and other resources for further reading. All of the projects are basic tiled patterns of lines and arcs. It misses out on exciting patterns that could be demonstrated using Bézier curves, randomness, and recursion.

However, I still think this is a good book as long as it isn’t your only resource on Processing and algorithmic art. It should be on your bookshelf whether you are a teen or an adult, a software engineer or a hobbyist. The diagrams for the patterns are clear and descriptive. The 23 patterns (along with the source code that generates them) make for great programming practice for anyone who wants to start into the world of computer art.

Additional: I highly recommend Tim Holman's CSSConf Australia talk, "Generative Art Speedrun" for a great and concise explanation on generative art concepts.

What's New in the 3rd Edition of "Automate the Boring Stuff with Python"

2023-11-09T12:00:00-05:00

The third edition is has new chapters, programming projects, and revised editing. The third party module coverage has been updated to the latest available version (including OpenPyXL). You can run pip install automateboringstuff3 to install the latest version of all modules covered in the book that are compatible with the book's code examples.

Updated June 20, 2025

Like the previous editions, the third edition is released under a Creative Commons license and will be free to read online.

Some of the new content includes:

Tips on how to use ChatGPT and other Large Language Model AIs to learn to code as well as common pitfalls to avoid.
Making your programs talk with text-to-speech libraries pyttsx3 and gTTS.
Speech recognition with OpenAI's Whisper library to create text transcriptions from audio and video files.
Doing OCR to extract text from images with PyTesseract.
Using the NAPS2 application to create PDFs from images with embedded OCRed text.

Downloading videos from YouTube and other video websites with yt-dlp.

Updated PDF operations using PyPDF and PdfMiner.
A complete introduction to SQLite and relational databases with Python's sqlite3 module.
How to compile Python scripts into executable programs with PyInstaller on Windows, macOS, and Linux.
Covering Playwright in addition to Selenium for controlling web browsers.
Sending push notifications to your phone with https://ntfy.sh
In addition to JSON and CVS formatted data, how to work with XML files as well.
Creating graphs with matplotlib.
Copying and pasting images to the clipboard with pyperclipimg.
The Humre module for making regular expressions easier to use.

If you have questions about the third edition or its content, you can post them on the /r/inventwithpython subreddit.

Using ChatGPT-4 to Review My Recursion Programming Book

2023-06-15T12:00:00-04:00

My 2022 book, The Recursive Book of Recursion (read online for free, buy direct from the publisher) covers recursive algorithms, a notoriously tricky subject for programmers and computer science students. I feel like I did a good job writing it (and my editors at No Starch Press did an incredible job editing it), but I wondered how well Large Language Models (LLMs) like ChatGPT could understand it. I ran the entire book through to see what mistakes or changes ChatGPT would make. The results were disappointing in some places but pleasantly surprising in others, so I wrote this blog post about the role AI could play in editing technical books.

Here's a summary of my findings:

ChatGPT absolutely cannot replace humans or reduce headcount. It's just a tool.
The majority of ChatGPT's feedback is useless, if not wrong.
ChatGPT is a tool for writers/technical reviewers more than editors because you need subject matter expertise to know when it gives you wrong "corrections."
But ChatGPT can uncover conceptual and logical mistakes beyond spelling and grammar, including finding bugs in source code. This is the benefit that makes it worth sifting through the garbage feedback.
ChatGPT-3.5 is not good enough to work with code. ChatGPT-4 is sometimes good enough to work with code.
I recommend making AI review a standard part of the production process. It won't make the process more efficient (if anything, it slows down the process by adding this extra step), but it will improve the quality of the final product.

I got 185 items of feedback from ChatGPT, which I (very subjectively) categorized as:

"Novel and useful feedback!" 28 items (15%) - These are actual mistakes that ChatGPT identified that require corrective action. This is the kind of feedback I want ChatGPT to give.
"Slightly helpful but disregarded edit suggestion." 26 items (14%) - This feedback is correct, but not useful enough to actually follow. It may provide an interesting thought for a human writer/editor/reviewer, but ultimately isn't actionable.
"Unhelpful feedback." 88 items (47%) - This feedback is not wrong but is meaningless or irrelevant, though it's easy to dismiss and wastes minimal time for a human editor.
"False positive!" 43 items (23%) - This is factually incorrect feedback that will send you on a wild goose chase and wastes a human editor's time while they verify that it is indeed wrong.

Further, I also have a Formatting issue category where ChatGPT's feedback was incorrect because of formatting errors introduced by copy/pasting the book text into ChatGPT. These are not ChatGPT's fault, and easy to dismiss with little wasted time. There were 54 items in this category.

Background Information and ChatGPT Transcripts

All of my programming books are available for free online under a Creative Commons license, so anyone can repeat this experiment by copy/pasting the text into ChatGPT. I've used ChatGPT-4 for this task (ChatGPT-3.5 produces mediocre results regarding code.) I'm not looking for spelling or grammar mistakes but rather conceptual errors. My paid OpenAI account (about $20 a month) lets me make 25 ChatGPT-4 queries every 3 hours and I can only enter about 15,000 characters before it complains about the input being too long.

Before each input, I prepend the following text: "The following text is from a book on Python programming. Please point out any technical errors or inaccuracies, along with any significant grammatical mistakes. Skip on summarizing the content and just list the errors you find:" I later changed this to "The following text is from a book on programming, specifically recursive functions. The book intentionally has at times a casual or conversational tone instead of a formal, academic one. Please point out any technical errors or inaccuracies, along with any significant grammatical mistakes. Skip on summarizing the content and just list the errors you find:"

The training data for ChatGPT used in this review was from September 2021.

To get the text of the book, I converted the book's .epub file to a .txt text file using Calibre, and then started copy/pasting text roughly 15,000 characters at a time. I'd always copy complete paragraphs, however the conversion to text does ruin the indentation of the code. For a more complete review, I recommend pasting the code with the original formatting. (I skipped this due to time constraints.)

Here are links to the actual conversations I've had with ChatGPT so you can see the input I gave it and the complete output it returned:

The rest of this blog post are the 239 individual feedback items ChatGPT gave me, along with my assessment of them.

AI Feedback for Chapter 1 - What is Recursion?

In this sentence: The Definition of Recursion Before we begin...

Formatting issue. This was caused by the copy/pasting from the text to the ChatGPT website, which put "The Definition of Recursion" on the same line as the first line of the paragraph. I won't count this for or against ChatGPT as a review tool.

In the Python and JavaScript programs where functions a(), b(), and c() are defined, there is a slight indentation problem...

Formatting issue. This was caused by the indentation of the code being lost when converting from the .epub ebook to a .txt text file.

In the paragraph explaining recursive functions and stack overflows, there's a small grammatical error: "Functions and stacks are both simple concepts, and we can use them together to understand how recursion works." It would be better to say: "Functions and stacks are simple concepts in themselves, and we can use them together to understand how recursion works."

Unhelpful feedback. A lot of the edit suggestions from ChatGPT are neither better or worse than the original text, but these end up being a lot of noise when trying to find problems in the text.

The explanation of the recursive function in Python and JavaScript could be misleading to beginners. Although technically accurate, it's important to note that this recursive function will lead to a "stack overflow" error because there is no base case to stop the recursion. Adding this information would provide a more complete understanding of recursion and its potential pitfalls.

Formatting issue. This suggestion was caused by the fact that I had to break up the book text into approximately 15,000 character chunks, so the previous explanation of stack overflows wasn't included in this chunk.

The phrase "Python uses the terms list and item, while JavaScript uses the terms array and element" could potentially be a source of confusion. While the terms 'list' and 'array' are used in Python and JavaScript respectively, the terms 'item' and 'element' are not language-specific and are often used interchangeably in both languages. A more accurate phrasing could be: "Python uses the term 'list' where JavaScript uses 'array' to refer to similar data structures".

Slightly helpful but disregarded edit suggestion. Eh, you could make the argument that "item" and "element" are not official terms in these languages, but documentation and developers do use these terms. Ultimately, this suggestion isn't useful enough and I disregarded it.

"But this “turtles all the way down” theory doesn’t do a good job of explaining cosmology, nor recursive functions." This should be corrected to: "But this “turtles all the way down” theory doesn’t do a good job of explaining either cosmology or recursive functions."

Unhelpful feedback. I get the feeling if I had used ChatGPT's phrasing, then ChatGPT could have easily suggestion my original phrasing.

"The constant function calls with no returns grow the call stack until all the computer’s memory allocated for the call stack is used up." This could be rephrased for better clarity: "Constant function calls with no returns cause the call stack to grow until all the computer’s memory allocated for the call stack is used up."

Unhelpful feedback. Eh, either would be fine.

In the Python examples, the function calls "shortest()" and "shortestWithBaseCase(makeRecursiveCall)" would require the function definitions to be above these calls in the actual Python script. However, it's not explicitly mentioned in the text, which could potentially confuse a beginner programmer. This is not an error per se, but it's worth mentioning for clarity and completeness.

Slightly helpful but disregarded edit suggestion. This advice isn't incorrect, but not relevant to this book as the book assumes you have a basic level of programming knowledge and would already know this. (Not knowing this isn't ChatGPT's fault though.)

AI Feedback for Chapter 2 - Recursion vs Iteration

The factorial of 0 is 1, not undefined or any other number. However, the text doesn't include this case in the factorial implementation in both the iterative and recursive methods. This is technically incorrect, as calling factorial(0) in the given code would not return the correct result, 1.

Novel and useful feedback! This was an oversight on my part as the author. I wrote the functions based on my explanation that 5! was 5 x 4 x 3 x 2 x 1, but this explanation doesn't note that mathematics defines 0! as 1. While this is no great sin for a book on recursion and I don't want to change the code, I should add a sentence describing this. I think it's interesting that while ChatGPT noticed this, ChatGPT did not complain about other kinds of invalid input such as negative, floating point, or string arguments.

Similarly, the Fibonacci sequence usually starts with 0 and 1, not 1 and 1. The definition used in this text (1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, etc.) is a variant of the sequence and should be clearly stated as such. Also, the text doesn't consider the case when nthNumber is 0 in the Fibonacci implementation.

Slightly helpful but disregarded edit suggestion. Yes, yes, I know that mathematicians use 0 and 1, but it's also valid to use 1 and 1, which is what I chose here. Heck, apparently Fibonacci himself used 1 and 2.

In the explanation of the recursive Fibonacci function, the phrase "the fibonacci() function itself is simple" is a bit misleading. Recursive functions can often appear simple due to their mathematical elegance, but they can lead to complex behavior and performance issues, as is pointed out elsewhere in the text.

Slightly helpful but disregarded edit suggestion. While I try to avoid the word "simply" when writing about technical subjects that a beginner may not find so simple, I think it's use her is fitting because I'm comparing it to the more complicated code nearby.

There's a small grammatical error in the sentence "This involves calculating number - 1 and making a recursive function, causing a new frame object to be pushed to the call stack." It should be "making a recursive function call", not "making a recursive function".

Novel and useful feedback! The phrasing I used is absolutely wrong and ChatGPT is correct: I meant to refer to a recursive function call and not a recursive function.

The text refers to .html programs. However, HTML is not a programming language. It would be more accurate to refer to these as scripts written in JavaScript, which are then embedded within an HTML document.

Novel and useful feedback! This is interesting. ChatGPT is wrong in that I'm not claiming HTML is a programming language. When I say "This code is equivalent to the following functionCalls.html program:" it's obvious that I'm referring to the JavaScript program in the functionCalls.html file. An annoying, obtuse nitpicker would point this out, but many human readers and reviewers are annoying, obtuse nitpickers. To deflect this (irrelevant) criticism, I should change the wording to "This code is equivalent to the JavaScript code in the following functionCalls.html file:". This phrasing occurs several times in the book, so I'll have to replace them all by doing a search for ".html program".

The Python and JavaScript code blocks are not consistently formatted. For example, comments are not consistently capitalized and sometimes end with a period and sometimes do not. While this doesn't affect the functionality of the code, consistency is generally good practice.

Formatting issue.

The last sentence is incomplete: "And don’t think that because a base case is reached, no more code remains to..." It should either be completed or removed.

Slightly helpful but disregarded edit suggestion. Actually the sentence is fine: "And don’t think that because a base case is reached, no more code remains to run after either recursive call." Maybe you could make a nitpick about adding a "that there's" text in there.

The base cases for Fibonacci series mentioned in the first paragraph are wrong. The base case for Fibonacci is fibonacci(0) which returns 0, and fibonacci(1) which returns 1, not fibonacci(2) and fibonacci(1) which both return 1.

Slightly helpful but disregarded edit suggestion. It's common in programming to use zero-based indexing. But that's specifically not what I'm doing here according to the description in the text.

In the Python code for the recursive factorial algorithm, it doesn't handle the case where the input is 0. The factorial of 0 is 1, but the current code doesn't have a base case for that.

Slightly helpful but disregarded edit suggestion. This is the same issue as pointed out previously: Mathematics defines 0! as 1, though my program doesn't handle that case. But I don't do complete argument validation because that makes the code more complex while not helping the reader learn about recursion. Much of writing effective programming books is knowing what technically-correct-but-not-very-relevant information to skip.

In the Python and JavaScript code for the iterative factorial algorithm, if the input is 0, the code will result in an infinite loop. It doesn't have a condition to check for this base case.

Slightly helpful but disregarded edit suggestion. This is the same issue as the previously described one.

In the Python and JavaScript code for the recursive and iterative 'findSubstring' functions, they will return incorrect results if the 'needle' string is empty. They should return 0 in this case, but currently, they return -1.

Slightly helpful but disregarded edit suggestion. While it is a programming convention that searching for an empty string "finds" it at index 0, adding code here makes is a distraction that doesn't help the reader learn about recursion. I can see why ChatGPT made this recommendation, but it's not useful to the context of this book. I'm tempted to file this as a false positive, but it is slightly-slightly helpful.

In the Python and JavaScript code for the 'exponentByIteration' function, the code doesn't handle the case where the exponent 'n' is 0. The result of any number to the power of 0 is 1, but the current code will return the wrong result.

Novel and useful feedback! Though this seems to be the same error the ChatGPT reported previously, it is in a new context with the exponentByIteration() function.

The note about the modulus operator (%) for determining whether an integer is odd or even is incorrect. Any even integer mod 2 results in 0, and any odd integer mod 2 results in 1, not the other way around.

False positive! ChatGPT is correct here. However, this is exactly what the book says too. Fortunately, the wild goose chase this suggestion led me on wasn't too long.

The sentence "The programs in this section demonstrate that it is always possible to turn any loop into an equivalent recursive function." is not grammatically incorrect, but it could be more precise. It should be "The programs in this section demonstrate that it is always possible to convert any iterative algorithm into an equivalent recursive function."

Unhelpful feedback. ChatGPT's suggestion here is correct, but I'm trying to avoid going too hard on technical jargon. I can use the term "loop" here instead of "iterative algorithm" and the phrasing would be just a little simpler to understand.

The sentence "The recursive Fibonacci algorithm also suffers from a critical weakness: it repeats the same calculations over and over." could be improved to "The recursive Fibonacci algorithm also has a critical weakness: it performs the same calculations repeatedly."

Unhelpful feedback. Whatever. Skip the five dollar words.

The sentence "This slows the overall algorithm with unnecessarily repeated calculations." could be rewritten as "This slows down the overall algorithm due to unnecessary repeated calculations."

Unhelpful feedback. Yeah, actually my phrasing is a bit better. Keep it simple.

The sentence "A dictionary storing the return address information and nthNumber local variable emulates a frame object ❷." is a bit unclear. It would be better phrased as "A dictionary, which stores the return address information and the nthNumber local variable, emulates a frame object ❷."

Unhelpful feedback. ChatGPT's phrasing kind of makes it sound like the dictionary's sole purpose is to store this info, but I'm talking about dictionary usage in a specific context.

The sentence "This is doing recursion for recursion’s sake, and since recursion is often harder to understand than iterative code, code readability deteriorates." could be improved for clarity: "This amounts to using recursion for its own sake, and since recursion is often harder to understand than iterative code, it can result in reduced code readability."

Unhelpful feedback. Yeah, I'm not saying my phrasing is simple, but it's simpler than ChatGPT's.

In the last sentence, "Those are the recursive cases, but what are the base cases?" the word "but" is not necessary. It can be rephrased as "Those are the recursive cases. What are the base cases?"

Unhelpful feedback. Nah, I don't like ChatGPT's phrasing. On a side note, ChatGPT tends to produce the kind of wording leans more towards traditional technical and academic text (it is reviewing a programming book, after all) but that's exactly the kind of wording I'm trying to avoid. Perhaps I should change the prompt to make ChatGPT inclined to more casual phrasing?

In the Python and JavaScript functions exponentWithPowerRule(a, n), there is an issue when n is 0. The while loop while n > 1: doesn't take into account the situation where the exponent n is 0. In mathematics, any non-zero number raised to the power of 0 is 1. The function as it currently stands would return a instead, which is incorrect. The function should be adjusted to return 1 when n is 0.

Novel and useful feedback! Yes, for completeness I probably should add code here. But then again, this exponent function doesn't work with (or claim to work with) negative exponents either.

"When we double-check our math, we find that 65 is indeed 7,776." There seems to be a typo in the representation of the operation. It should be "6^5" instead of "65".

Formatting issue. Copying and pasting the input text didn't capture the superscript of the "5".

"The iterative exponents function that uses the power rule has the improved performance of the recursive algorithm, while not suffering from the risk of a stack overflow." This sentence is a bit awkward. It could be rewritten for clarity, such as: "The iterative exponents function, which uses the power rule, improves performance over the recursive algorithm and avoids the risk of a stack overflow."

Unhelpful feedback. Actually, I like my phrasing a bit better.

"However, as the exponent functions we created in the previous section show, recursion can provide new insights into how to think about our programming problem." This sentence is also a bit awkward. It could be rewritten for clarity, such as: "However, as demonstrated by the exponent functions we created in the previous section, recursion can offer new insights into problem-solving in programming."

Unhelpful feedback. I like my phrasing better.

"When Do You Need to Use Recursion?" This is a heading, not a sentence, but it's phrased as a question when it would be more standard as a statement. A better heading might be "Determining When to Use Recursion" or "The Appropriate Use of Recursion".

Unhelpful feedback. Is using a question for a heading so bad?

The references to "Figure 2-4", "Figure 2-5", and "Figure 2-6" are not meaningful in this text-only format. If this is meant to be a text-only summary, these references should be removed or replaced with textual descriptions of the images.

Formatting issue. The images weren't copy/pasted to the input.

There are instances of code being referred to as "Python" or "JavaScript" when it would be more accurate to refer to them as "Python code" or "JavaScript code". This is a minor issue, but improving this could make the text clearer and more accurate.

Unhelpful feedback. Nah, less is more. 'Nuf said.

There are numerous instances where the language could be simplified for ease of reading. For example, "This chapter featured both iterative and recursive implementations for these algorithms" could be simplified to "This chapter showed both iterative and recursive versions of these algorithms."

Unhelpful feedback. Eh, I think "implementations" is a better word (or at least, not worse) in this context.

There is a degree of repetition in the text, with recursion and its merits and drawbacks being discussed multiple times in similar ways. Consolidating these points could improve the flow of the text.

Unhelpful feedback. Nope. Strategically repeating information helps with understanding. Also, this advice is vague.

The writing occasionally shifts between different perspectives (we, you), which can be confusing. Consistency in perspective can make the text clearer and more engaging.

Unhelpful feedback. Eh.

AI Feedback for Chapter 3 - Classic Recursion Algorithms

In the first paragraph, the phrase "Coding interviews (which, for lack of suitable ways to evaluate candidates, often crib notes from freshman computer science curricula) can touch upon them too." could be better written as, "Coding interviews, which often borrow from introductory computer science curriculum due to a lack of suitable ways to evaluate candidates, may also cover these topics."

Unhelpful feedback. No, my phrasing is better.

In the section titled "Summing Numbers in an Array", the text says, "Still, summing numbers in an array (or some other calculation based on processing data in a linear data structure) is a common enough recursion problem in coding interviews that it deserves our attention." This could be written more clearly as, "Despite this, summing numbers in an array, or performing some other calculation based on processing data in a linear data structure, is a common enough problem in coding interviews to warrant our attention."

Unhelpful feedback. Eh.

In the section "Reversing a String", there's an inconsistency in font formatting: ′CAT′, ′X′, ′Y′, ′A′, ′T′ use a different font compared to the rest of the text. The correct formatting should be 'CAT', 'X', 'Y', 'A', 'T'.

Novel and useful feedback! Huh, I didn't notice this. A minor but real issue. Somehow "smart" single quotes got introduced here when I meant to use straight single quotes. it doesn't really matter to people reading the book, but copy/pasting this text would copy these incorrect quotes.

In the JavaScript code snippet for "Reversing a String", modern JavaScript conventions are not followed. Instead of using var, let or const should be used for variable declaration, since var is function-scoped and could lead to unexpected behavior.

Novel and useful feedback! I did use "let" in most of the JS programs, but I did fall back on "var" for the reverse string, palindrome, Tower of Hanoi, and flood fill JS programs. I should probably also run the source code for these programs under a linter. Using "var" isn't wrong, but changing it to "let" will preemptively deflect any nitpickers.

In the phrase "Thinking about how to implement a recursive function like rev() can be difficult because it involves a chicken-and-egg problem," it would be more accurate to say "it presents a circular dependency problem" instead of "it involves a chicken-and-egg problem," which is more colloquial and may not be clear to all readers.

Unhelpful feedback. I want the more colloquial phrasing.

The phrase "Taking a leap of faith in recursion is not a magical technique that guarantees your code works bug free" is a bit awkward. It would be clearer to say "Taking a leap of faith in recursion does not guarantee that your code will be bug-free."

Unhelpful feedback. I like my phrasing better. "Leap of faith" is one of those terms that is often used in recursion lessons but is vague and magical-sounding.

In the section titled "Reversing a String", the author says, "You can’t simply pass the same argument that the recursive function received, like this:". This sentence could be clearer with some rewording, such as, "You cannot merely pass the same argument that the recursive function initially received, as shown here:"

Unhelpful feedback. Eh.

In the phrase "The leap of faith requires you to have a firm understanding of your recursive function’s arguments and return value," the term "leap of faith" is a bit informal and could be confusing to some readers. It might be clearer to say, "This approach requires a firm understanding of the arguments and return value of your recursive function."

False positive! No, "leap of faith" does have a particular meaning in the context of recursion.

The palindrome detection code won't handle spaces and capitalization properly. For example, 'race car' is a palindrome, but the code will report it as not being a palindrome because it doesn't handle spaces. Similarly, 'Racecar' is also a palindrome, but the code will report it as not being a palindrome because it doesn't handle capitalization. The same goes for the phrase 'A man, a plan, a canal . . . Panama'. In the real world, a string preprocessing step is required to handle spaces, punctuation, and capitalization.

Unhelpful feedback. I purposefully made it not handle these cases so that the code can be simpler.

The JavaScript version of the Tower of Hanoi solution doesn't seem to print the initial state of the towers before the solving process starts. This could be a potential oversight.

False positive! The JS code does in fact print the initial state.

In the sentence "The return statement in the recursive case ❹ makes use of Boolean short-circuiting, a feature of almost every programming language." it would be more accurate to say "many programming languages" instead of "almost every programming language".

Unhelpful feedback. No.

In the sentence "For n disks, it takes a minimum of 2n – 1 moves to solve." it should be written as "For n disks, it takes a minimum of 2^n – 1 moves to solve." to correctly express the exponential notation.

Formatting issue. Copy/pasting the text removed the superscript of "n".

In the sentence "The series of operations for solving a four-disk Tower of Hanoi", the figure number following the sentence is "Figure 3-5". However, in the previous paragraph, the text refers to a Figure 3-6 which isn't mentioned again. This could be a numbering error.

Formatting issue. Copy/pasting the text doesn't copy the images.

The phrase "This towerOfHanoiSolver.html program contains the equivalent JavaScript code" might be misleading as the .html extension is for HTML files, not JavaScript. It should be clarified that this is an HTML file that contains JavaScript code.

This has been addressed previously.

In the sentence "When you run this code, the output shows each move of the disks until...", it seems like an incomplete sentence. The rest of the sentence is missing.

False positive! What? The sentence is fine. This isn't even a formatting issue.

ChatGPT had this to say about the flood fill source code in Python and JavaScript:

In Python code:

In line ❶, the comment says "Create the image (make sure it's rectangular!)" but it's actually creating a list of strings, not an image.

In line ❷, there's an unnecessary indentation before the variable assignment.

In lines ❸, ❹, ❺, and ❻, the comments say "RECURSIVE CASE" but they should say "BASE CASE" since they are the conditions for the base case.

In line ❼, there's an extra indentation that shouldn't be there.

In JavaScript code:

In line ❶, the comment says "Create the image (make sure it's rectangular!)" but it's actually creating an array of arrays, not an image.

In lines ❷, ❸, ❹, ❺, and ❻, the comments say "RECURSIVE CASE" but they should say "BASE CASE" since they are the conditions for the base case.

In line ❼, there's a space before the semicolon that shouldn't be there.

In line ❽, there's a space before the closing </ pre> tag that shouldn't be there.

Unhelpful feedback. Yes, it's made up of strings but this forms and ASCII-art image. This feedback is irrelevant.

Formatting issue. The "unnecessary indentation" was caused by copy/pasting the text to ChatGPT.

False positive! ChatGPT is wrong. The recursive and base cases are correctly marked.

Formatting issue. The "extra indentation" was caused by copy/pasting the text to ChatGPT.

False positive! I double-checked that this wasn't a formatting issue. There is no "space before the semicolon".

Novel and useful feedback! There was an extra space in the </ pre> tag.

In the sentence "The following output shows the before and after images:", it should be "The following output shows the images before and after:" to correct the word order.

Unhelpful feedback. Eh.

In the sentence "If you want to see every step of the flood fill algorithm as it fills in the new character, uncomment the printImage(image) line ❶ in the floodFill() function and run the program again," the reference to line ❶ should be changed to line ❷.

Both Novel and useful feedback! and False positive!: The reference to 1 is wrong, but it should be removed entirely rather than changed to 2.

In the sentence "This means we could equally effectively use a set data structure that removes elements randomly," it should be "This means we could equally effectively use a data structure like a set that removes elements randomly."

Unhelpful feedback. No.

AI Feedback for Chapter 4 - Backtracking and Tree Traversal Algorithms

"A maze can be represented by a tree data structure, since mazes branch off into different paths, which in turn branch off into more paths." It might be worth clarifying that this representation applies to perfect mazes, where there is a single path between any two points without loops. Other types of mazes, which can include loops or cycles, may not be perfectly represented by a tree.

Formatting issue. The information here is correct, but I do go into the definition of perfect mazes later in the chapter. But this wasn't included in the 15,000 character chunk I sent to ChatGPT. This was a bit of a time waste to resolve.

"In mathematics and computer science, a graph is a collection of nodes and edges, and a tree is a kind of graph. The graph is directed because its edges have one direction: from parent to child node." This sentence might be confusing because it seems to imply that all graphs are directed. It would be better to specify that the graph we're talking about in this context (a tree) is directed.

Formatting issue. The "directed" was italicized but this was lost in the copy/paste, but I feel like this italicizing made it more obvious that it was not implying all graphs are directed. This was a bit of a time waste to resolve.

"Trees in general do not have this restriction and can have edges in both directions, including from a child node back to its parent node." This statement can be misunderstood, as trees are usually described as directed acyclic graphs, meaning they don't have edges going in both directions (from child to parent and vice versa). While it's true that trees can be represented with bidirectional edges for some algorithms, it might be worth noting that this is not the typical definition.

False positive! I have this sentence specifically in contrast with the previous sentence that says DAGs are directed. It was a waste of time to investigate this feedback.

"You can think of lists, arrays, and strings as linear trees; the root is the first element, and the nodes have only one child node. This linear tree terminates at its one leaf node." This might be confusing as well. Lists, arrays, and strings are linear structures, but calling them "linear trees" might be misleading because they don't have the hierarchical structure typically associated with trees.

False positive! Yeah, that's why I'm explaining how you can think of them as linear trees. That's the point of these sentences. It was a waste of time to investigate this feedback.

"The following preorderTraversal.py program has a preorderTraverse() function that traverses each child node first, before accessing the node’s data to print it to the screen:" The description of the preorderTraverse() function is incorrect. In a preorder traversal, the node's data is accessed first, then its child nodes are traversed, not the other way around. The actual code provided correctly implements a preorder traversal, so this seems to be a minor error in the accompanying text.

Novel and useful feedback! Yes, while the code is correct, I think there was a typo in the description that swapped these.

"When you look at the tree in Figure 4-1, notice that preorder traversal order displays the data in left nodes before right nodes, and bottom nodes before top nodes." This sentence may cause confusion, as there is no Figure 4-1 presented in the given text.

Inorder Tree Traversal: The text and code provided are misleading as they suggest that inorder traversal can be used for general trees. Inorder traversal is specific to binary trees. The code provided treats the first child as a left node and the second child as a right node. However, this is not accurate for general trees where a node can have more than two children. In general trees, there is no concept of left and right children. The code and explanation should be corrected to reflect this.

False positive! No, you can still do an inorder traversal with trees with more than two child nodes. If you access the data after traversing the first child and before traversing the last child, that's an inorder traversal.

Finding Eight-Letter Names in a Tree: The JavaScript function find8LetterName() has an extra parameter value that is not used within the function. This is a minor error and the value parameter should be removed.

Novel and useful feedback! Yep. That "value" parameter somehow got left in and should be removed.

Getting the Maximum Tree Depth: The text does not have any errors, but it ends abruptly without concluding the topic or providing any code examples. It might be useful to include an example here to properly illustrate this concept.

Formatting issue.

Regarding the description of the getDepth() function, there's a discrepancy in the definition of the depth of a leaf node. It's stated that "A leaf node (the base case) simply returns 0," but later it's said that a leaf node "by its nature has a depth of one level." The first definition is in line with the code examples provided, where a leaf node indeed returns 0. So, the second statement is technically incorrect.

Novel and useful feedback! and False positive! Yes. There is a mistake, but it should be TODO

In the Python code example for the getDepth() function, the final print statement should follow Python 3's f-string formatting or the format method for clarity and consistency. Here's the suggested revision: print(f'Depth of tree is {getDepth(root)}') Instead of: print('Depth of tree is ' + str(getDepth(root)))

Slightly helpful but disregarded edit suggestion. I don't use f-strings in my Python code in order for it to be runnable on pre-3.6 versions.

The JavaScript example for getDepth(), the HTML element "script" has an incorrect closing tag. It should be </script> but instead it is written as </ script>.

False positive! There was no space. I wasted quite a bit of time verifying this.

In the maze-solving section, the term "tree graph" is used, which could be confusing. The maze isn't strictly a tree because, unlike trees, mazes can have nodes with more than one parent. The term "graph" would be more accurate here.

Unhelpful feedback. I've already explained in this chapter that the mazes are perfect mazes.

The last print statement printMaze(MAZE) needs an explanation or context, as it might confuse the reader. Is it meant to print the solved maze or the original one?

Novel and useful feedback! This is actually really good feedback, because looking at the code this is a perfect spot where just a couple simple comments will really improve the readability of the code.

There's an incorrect Unicode character in comments marked as ❶, ❷, ❸, and ❹. They should be replaced with proper numbering or bullets if they are meant to denote specific steps or points in the code.

False positive! It's weird that ChatGPT hasn't complained about the use of the circle-numbers until now. These are fine.

In the JavaScript mazeSolver.html program, there's an incorrect closing tag </ pre> for the "pre" element. It should be </pre>.

Novel and useful feedback! Nice catch.

Grammatically, there are some long sentences that could be broken up for clarity. For example, "The nodes in this tree graph represent intersections where the maze solver could choose one of the north, south, east, or west paths to follow to the next intersection." could be restructured as "The nodes in this tree graph represent intersections. At each intersection, the maze solver could choose to follow one of the north, south, east, or west paths to reach the next intersection."

Novel and useful feedback! Yeah, actually this edit would be better.

The term "DAG" (Directed Acyclic Graph) is used without a proper introduction or definition. If it's the first time the term appears in the book, it should be introduced and defined.

Formatting issue.

In the paragraph discussing the "base case" in binary search, it might be helpful to clarify that the base case isn't only when the range of items is one item in length, but also when the search range is empty (left > right).

Novel and useful feedback! Yes, I should also add this bit of text.

For better understanding, it might be useful to clarify what the maze and visited variables are referring to in the context of the programming explanation. The paragraph seems to assume that the reader is familiar with these from a previous section or code sample.

Formatting issue. This is expained elsewhere.

The description of how recursion is used in backtracking algorithms could be explained more thoroughly. It is mentioned that "a recursive function call is analogous to traversing to a child node in a tree, while returning from a recursive function call is analogous to backtracking to a previous parent node," but it could be helpful to give a specific example of this for readers who are less familiar with these concepts.

Formatting issue. This is expained elsewhere.

In the explanation of binary search, it would be beneficial to note that binary search only works on sorted lists or arrays. This is implicit in the explanation, but could be explicitly stated for clarity.

Formatting issue. This is expained elsewhere.

In the JavaScript version of binarySearch, it uses "===" (strict equality operator) for comparison, which checks both the value and the type. This might lead to unintended results if the types are different. However, this depends on the expected types of the inputs in this specific application. In general, using "===" in JavaScript is considered good practice.

Unhelpful feedback. Meh.

When talking about the Big O Algorithm Analysis, it would be beneficial to explain what the Big O notation represents for readers unfamiliar with the concept.

Unhelpful feedback. This explanation is in a box precisely because Big O notation is too complex of a topic to go into in this book.

It is stated that a simply connected maze has a tree-like structure, but it might be helpful to explain what "simply connected" means in this context. In graph theory, a simply connected graph is a tree, i.e., a connected graph without simple cycles.

Formatting issue. This is expained elsewhere.

The text is a little confusing when it discusses printMaze(MAZE) calls being uncommented to show how the maze data structure changes as it is processed. This might be clearer if there was a specific code sample provided that showed where these function calls were placed and how they could be uncommented.

ChatGPT already mentioned this issue.

The text could benefit from more concrete examples, particularly when discussing more abstract concepts like trees, DAGs, and recursion.

Formatting issue.

AI Feedback for Chapter 5 - Divide-and-Conquer Algorithms

Technical Inaccuracy: The statement "The range halves in size for each recursive call, so it eventually becomes empty" is inaccurate. While the range does decrease in size after each recursive call, it doesn't necessarily halve. The partitioning is based on the pivot, so the size of the two resulting sub-ranges can vary.

Novel and useful feedback! I should add a minor note that the range roughly halves in size.

Typographical Error: In the Python script, the comment at line 8 refers to 'left side of items' whereas it should be 'right side of items'. The corrected line should be '# Put the pivot on the right side of items: items[i], items[right] = items[right], items[i]'

False positive! ChatGPT is completely wrong. The original text is correct in that it's the left side.

Consistency Issue: In the explanation of base case for the recursion, it's stated that "Being given a range to sort that contains zero or one item and that is already in sorted order." is the base case. However, quicksort doesn't check if a range of one item is already in sorted order because a single item is by definition sorted. This might lead to confusion and it would be better to say "Being given a range to sort that contains zero or one item."

Novel and useful feedback! Yeah, I can slightly change this wording to "and thus is already in sorted order."

Grammatical Error: In the following statement - "Someone else’s quicksort() implementation may instead use j and i, or even completely different variables", it is not clear what "j and i" refers to. If the author means to say that the positions of i and j may be swapped, then the statement could be clarified to say - "Someone else’s quicksort() implementation may instead swap the positions of i and j, or use completely different variables".

Formatting issue.

Ambiguity: In the statement - "This results in no actual change since i and j are the same index", it's not clear why having i and j as the same index will result in no change. This can be rephrased for clarity - "This results in no actual change because swapping a value with itself does not alter the array, which is the case when i and j are at the same index."

Unhelpful feedback. The other sentences clarify this, and ChatGPT's own wording is vague and unhelpful.

In the mergeSort() function, there is a bug that could cause an IndexError. The condition that checks whether an item should be appended from left or right doesn't ensure that iLeft and iRight are valid indices for their respective lists. This could lead to an IndexError if the left list is exhausted before the right list (or vice versa), but the exhausted list's index is still used to attempt to access an item. A condition to check whether iLeft or iRight have reached their list's length should be added before comparing left[iLeft] and right[iRight].

False positive! Yeah, I've done a thorough check and I think ChatGPT is just throwing stuff at the wall to see what sticks. This code can't cause an index error. That was a wild goose chase.

In the sumDivConq() function, numbers[mid:len(numbers) + 1] should be replaced with numbers[mid:]. This is because slicing in Python does not include the stop index, so adding 1 to len(numbers) does not have any effect. Additionally, if you leave out the stop index in a slice, Python will automatically include all elements until the end of the list, which is what we want here.

Slightly helpful but disregarded edit suggestion. In normal Python code this would be the conventional way to write it, but I'm trying to be more explicit so that it's in line with the equivalent JavaScript code I have. ChatGPT's suggestion is right, but isn't relevant to my particular case.

"Merging two sorted lists into a larger sorted list involves looking at the start of both smaller lists and appending the smaller value to the larger list." This sentence could be more accurately written as: "Merging two sorted lists into a larger sorted list involves looking at the start of both smaller lists and appending the smaller value to the new list."

Unhelpful feedback. Eh.

"The function divides the [8, 5] list into [8] and [5], reaches the base case, and then merges back into [5, 8]." This sentence would be clearer written as: "The function divides the [8, 5] list into [8] and [5], each of which is already sorted because it contains only one item (the base case), and then merges these back into the sorted list [5, 8]."

Slightly helpful but disregarded edit suggestion. I kind of like ChatGPT's wording, but I also kind of like how mine is shorter. Eh. I'm going to stick with mine.

"We already covered summing an array of integers in Chapter 3 with the head-tail technique." It's not an error, but this sentence would benefit from rephrasing for clarity: "In Chapter 3, we already covered the method of summing an array of integers using the head-tail technique."

Unhelpful feedback. Eh, I really don't think this suggestion is an improvement, and might even be worse.

In the section "Here are the five steps of the Karatsuba algorithm:", the fourth step is described incorrectly. It should be:

Calculate step 3 - step 2 - step 1 multiplied by 10^(n/2), where n is the number of digits.

This ensures that the middle term in the final equation is properly accounted for. The resulting value is then used for padding in step 5.

In the Python implementation, the padding in step 5 is incorrect. The lines:
step1Padding = (len(x) - halfOfDigits) + (len(x) - halfOfDigits)
step4Padding = (len(x) - halfOfDigits)
Should be replaced with:
step1Padding = 2 * (len(x) - halfOfDigits)
step4Padding = len(x) - halfOfDigits
Also, the 'left' padding in the 'padZeros' function is not necessary for the Karatsuba algorithm, as we only pad zeros to the right of the number in this case.

In the JavaScript implementation, the same errors with padding exist. Replace:
let step1Padding = (x.length - halfOfDigits) + (x.length - halfOfDigits);
let step4Padding = (x.length - halfOfDigits);
With:
let step1Padding = 2 * (x.length - halfOfDigits);
let step4Padding = x.length - halfOfDigits;

False positive! I'm really annoyed with this one because it took me a long time to verify that my code is correct. From what I can tell, ChatGPT isn't looking at my program so much as it's thinking of standard implementations of the Karatsuba algorithm and pointing out how mine is not like that. I've written my code more for simplicity though, rather than as professional code. This was a big waste of time.

Also, the description of the multiplication table generation is slightly incorrect. The text says:

"Normally, lookup tables are hardcoded directly in the source code, from MULT_TABLE[[0, 0]] = 0 to MULT_TABLE[[9, 9]] = 81."

However, in Python, accessing dictionaries with lists as keys (e.g., MULT_TABLE[[0, 0]]) will raise a TypeError because lists are mutable and cannot be hashed. This will not work unless you use a tuple (e.g., MULT_TABLE[(0, 0)]), which is the correct way to do it in Python and was done correctly in the code.

False positive! ChatGPT is looking at the JavaScript code and confusing it with Python code. Disregard its advice here.

The concept of padding zeros in the Karatsuba algorithm is somewhat misrepresented. In the Karatsuba algorithm, padding zeros means multiplying a number by 10^k where k is a certain number of digits. It's not adding zeros to a string.

False positive! Yeah, I know my code isn't standard. That's because I'm writing it for readability by students. Nobody would write a Karatsuba implementation in Python anyway because they could just use the * operator. Again, ChatGPT is complaining about how my code doesn't compare to a standard Karatsuba implementation rather than considering my code in its own context.

Finally, the paragraph mentioning HALF_TABLE is not technically incorrect, but the justification for the lookup table is somewhat misleading. While it is true that division operations might not be available in some very low-level programming or hardware situations, the vast majority of modern computing environments, including virtually all that use Python or JavaScript, support division operations.

Unhelpful feedback. Uhg.

Under "Practice Questions", the question "What is a benefit of the divide-and-conquer summing algorithm in this chapter compared to the head-tail summing algorithm in Chapter 3?" appears to refer to content that is not provided in the given text. It's not technically an error in this section, but the context is missing.

Formatting issue.

In the "Practice Projects" section, the text suggests creating a version of the Karatsuba multiplication algorithm with a lookup table for products from 0 x 0 to 999 x 999. While this is technically possible, it may not be practical due to the large amount of memory such a lookup table would consume.

Unhelpful feedback. Yeah, it's not practical. It's meant to be an academic exercise. (I think at this point ChatGPT's advice is getting on my nerves.)

The question "How is the array [0, 3, 1, 2, 5, 4, 7, 6] not properly partitioned with a pivot value of 4?" suggests that there's a problem with an array partition, but no problem is evident from the given text.

False positive! The answer is "there's a 5 before the 4, which should be to the right of the 4 if 4 was the pivot value."

The problem "Create a function that performs a linear search on a large array of integers 10,000 times." is more a computer science problem than specifically a Python problem.

Formatting issue. This is unhelpful feedback, but it's caused from the prompt I gave it. I need to change the prompt to not call this book a Python book.

AI Feedback for Chapter 6 - Permutations and Combinations

In "The Terminology of Set Theory", when explaining n multichoose k, the concept is somewhat unclear. It might be better to explain that it refers to the number of ways to select k elements from a set of n elements where repetition is allowed and order doesn't matter.

Unhelpful feedback. Uh, I kind of do explain this?

In the sentence "This makes these calculations suitable for recursion." the word "these" is used twice in close proximity, which could be considered redundant. It could be rephrased as "This makes such calculations suitable for recursion."

Unhelpful feedback. Meh.

"For example, 4 choose 2 is 6, because there are six ways to choose two elements from a set of four elements like {A, B, C, D}: {A, B}, {A, C}, {A, D}, {B, C}, {B, D}, and {C, D}." The phrasing is slightly awkward. A possible improvement would be: "For example, in '4 choose 2', there are six possible ways to select two elements from a four-element set such as {A, B, C, D}: {A, B}, {A, C}, {A, D}, {B, C}, {B, D}, and {C, D}."

Unhelpful feedback. I like my phrasing better.

"It’s surprising how quickly the number of permutations and combinations grows as we add elements to a set." This sentence is more of a personal observation than a factual statement. A more formal way to phrase this could be: "The number of permutations and combinations increases exponentially with the addition of elements to a set."

Unhelpful feedback. Wow, thanks. Any more advice on how to drain the last remnants of personality from the text?

The Python code has a lack of indentation which is crucial in Python. The if-else clauses, loops, and function definitions are not properly indented, making the code difficult to understand and likely to throw an error if run.

Formatting issue.

In the "Getting Permutations with Nested Loops: A Less-Than-Ideal Approach" section, it says "We can calculate the number of possible combinations as 54, or 5 × 5 × 5 × 5, or 625." But later in the text, it shows a nested loop generating permutations with only 3 characters ('A', 'B', 'C', 'D', 'E'), which contradicts the previous statement that the permutations should be four characters long.

False positive! ChatGPT has brain worms here. I don't even want to bother going into why this is so off the mark.

The for loop for generating permutations in Python in the "Getting Permutations with Nested Loops: A Less-Than-Ideal Approach" section is also incorrect. It says, "for a in ['A', 'B', 'C', 'D', 'E']: for b in ['A', 'B', 'C', 'D', 'E']: for c in ['A', 'B', 'C', 'D', 'E']: for d in ['A', 'B', 'C', 'D', 'E']:", which is generating 4-character permutations, but it's stated above that they are generating 3-character permutations.

False positive! Same as previous.

In the "Permutations with Repetition: A Password Cracker" section, it says, "making 6 × 6 × 6 × 6, or 64, or 1,296 possible permutations." This is inaccurate as 6 × 6 × 6 × 6 equals to 1,296, not 64.

Formatting issue. The superscript for 4 didn't copy over.

In the JavaScript function getPermsWithRep(), when the base case is reached (permLength === 0), the function returns [prefix] which is an array. But prefix is a string. It's not clear what the purpose is of returning the string in an array.

False positive! Brain worms response.

A minor grammatical error in "The function makes a recursive call to getPerms() to get all the permutations of the string in tail." It would be clearer if phrased as, "The function makes a recursive call to getPerms() to get all the permutations of the string from tail."

False positive! No, my wording makes much more sense.

There is a contradiction in the phrase "Permutations with repetition go through all possible orderings of the elements in a set, like our wedding guest seating chart example." This should mention that repetition of elements is allowed in the set, unlike the wedding guest seating example where each guest can only be seated once (no repetition).

False positive! Wow. I checked and the text with the wedding guests uses the word "without" and not "with". ChatGPT is outright misquoting what the book says. This is a flagrantly bad failure of the LLM.

It's mentioned that the function getPermsWithRep('JPB123', 4) is being called but the string 'JPB123' is of length 6, not 4. The explanation for the permLength argument says that it begins as the length of chars, which is not the case here.

False positive! ChatGPT is misunderstanding what the function requires. 4 is the length of the generated permutations, not the pool of characters to draw from (JPB123).

The algorithm for recursive permutations with repetition in the Python code doesn't explicitly handle the case when the permLength argument is greater than the length of chars, which might lead to unexpected results.

Slightly helpful but disregarded edit suggestion. Input validation isn't a priority in this context.

The algorithm for recursive permutations with repetition in the JavaScript code doesn't check if permLength is greater than the length of chars, leading to the same potential problem as in the Python code.

This is a repeat of the previous issue.

Technical error: It is mentioned, "While sets don’t have an order, we need to be consistent in using the ABCD order of the set while generating this tree." This is misleading. In Python, sets are unordered and the order of items is not maintained. Therefore, if you need to maintain order, you might have to use a different data structure like a list.

False positive! ChatGPT has misunderstood context. I'm talking about sets as in set theory, not as in the Python data structure.

Grammar error: The sentence, "The return value is an array of strings of combinations from the string chars, each of length k," uses the term "array" which is less common in Python context. It is better to use "list" instead, as that's the term used for this data structure in Python.

Formatting issue. In this book I'm using Python and JavaScript, and previously said I'd use "array" as a generic term.

Grammar error: "The second case occurs if chars is the blank string, which is an empty array since no possible combinations can be made from a blank string." Again, use the term "list" instead of "array".

Formatting issue. Same as previous.

The explanation in the paragraph about "2-combinations of 'ABC'" is a bit confusing. The explanation about 1-combination and the recursive call might need further clarification.

Formatting issue. I'll be generous and say this is because the accompanying figures aren't there, but I think ChatGPT is misreading this section.

In the Python code, 'getCombos' function is used, which uses recursion to find combinations. There's a point where it is mentioned that two arguments are passed to the recursive function call: the tail of chars and k-1 for the first call, and the tail of chars and k for the second call. This explanation may be confusing to some readers, as it's not immediately clear what 'tail' refers to. It might be helpful to explain that 'tail' refers to all characters in 'chars' except the first one (the 'head').

Formatting issue. Head-tail was explained previously.

In the JavaScript code, you're using document.write(), which is generally considered a bad practice as it may lead to vulnerabilities such as Cross-Site Scripting (XSS) attacks. It is also not standard in modern web development where DOM manipulation is done using methods like innerHTML, textContent or better, via libraries like jQuery or frameworks like React, Angular, Vue.js, etc.

Unhelpful feedback. Uhg. This is the kind of irrelevant nonsense that gets tiresome to repeatedly read.

The JavaScript code uses the method .slice() on a string. Although this is not incorrect (as slice works on strings in JavaScript), it could be a little confusing because in Python, slicing is typically used on lists, not strings. It might be worth noting this difference for readers who are new to JavaScript.

Unhelpful feedback. The reader knows that JavaScript and Python are different languages.

Technical error: In the section discussing balanced parentheses, the claim "A string has balanced parentheses if every opening parenthesis is followed by exactly one closing parenthesis." is incorrect. A string has balanced parentheses not only if every opening parenthesis is followed by a closing parenthesis, but also if every closing parenthesis is preceded by an opening parenthesis and the order of parentheses is correct, i.e., no closing parenthesis appears before an opening parenthesis corresponding to it. A more accurate definition might be: "A string has balanced parentheses if for every opening parenthesis there exists a corresponding closing parenthesis that appears later in the string, and vice versa, such that no closing parenthesis appears before an opening parenthesis corresponding to it."

Unhelpful feedback. My wording is simpler, and the word "exactly" covers this extended discussion.

The explanation about the getBalancedParens() function might be improved by providing a code snippet. This would make it easier to understand the implementation of the function.

Unhelpful feedback. No it wouldn't. And anyway, I provide the full code of the function already.

It is mentioned in the text that the getBalancedParens() function builds strings by adding either an opening or closing parenthesis. But it doesn't clarify what the criteria for adding the opening or closing parenthesis are.

Unhelpful feedback. Yes it does.

There's a small contradiction in the text. The author first writes that "the second base case happens after the two recursive cases have received the lists of balanced parentheses strings after adding an opening and/or

ChatGPT cut off it's own response here.

The document.write(<pre>"All combinations of 2 balanced parentheses:<br />"); line in the JavaScript example is not syntactically correct. It should instead be document.write("<pre>All combinations of 2 balanced parentheses:<br />");.

Novel and useful feedback! Good catch. The <pre> tag got moved outside of the double quotes somehow.

The statement that "The getBalancedParens() function ❶ requires one argument, the number of pairs of parentheses, when called by the user" is not entirely accurate. This function has default parameter values for its arguments, so technically it could be called without any arguments, and would default to pairs=undefined, openRem=undefined, closeRem=undefined, current=undefined, and indent=0.

False positive! This is completely untrue. The Python version requires the pairs argument, and the JavaScript version breaks at runtime if you don't supply it.

The JavaScript code uses the Array.prototype.push.apply() method, which is outdated and has been replaced with the spread operator (...). It would be more current to use results.push(...getBalancedParens( pairs, openRem - 1, closeRem, current + '(', indent + 1)); instead of Array.prototype.push.apply(results, getBalancedParens( pairs, openRem - 1, closeRem, current + '(', indent + 1));.

Unhelpful feedback. I'd rather use the older but simpler syntax.

The power set section describes an example of how the power set grows when new elements are added, but it mislabels the elements in bold as "new" elements. However, these are actually the subsets that include the new element, not the new elements themselves.

Formatting issue. The copied text doesn't retain the bold style.

In the Python code, powerSet = powerSet + tailPowerSet is inefficient. It would be better to use powerSet.extend(tailPowerSet) instead, to append the elements of tailPowerSet to powerSet directly, without creating a new list.

Unhelpful feedback. Simplicity of code is more important for the context of this book than performance.

The phrase "Let’s ask the three recursive algorithm questions about our power set algorithm" is awkward. It could be rewritten as "Let's consider the three questions about recursion as they apply to our power set algorithm."

Unhelpful feedback. Meh.

In "This is equivalent to the set of every possible k-combination of a set", it would be better to write "This is equivalent to the collection of all possible k-combinations of a set."

Unhelpful feedback. Eh, my wording is actually better.

The phrase "It is astronomically unlikely you’ll need to generate the power set of a set for any other reason, including the job you are interviewing for" is written in a tone that might come off as sarcastic or unprofessional. It could be rephrased more neutrally as "While generating the power set of a set is not a commonly required task in most jobs, it can still be a useful concept to understand."

Unhelpful feedback. Eh, my wording is actually better.

In the sentence "After these recursive cases is an unconditional base case that returns...", the grammar is off. It would be better to write "After these recursive cases, there is an unconditional base case that returns..."

Unhelpful feedback. Eh.

The phrase "The power sets of larger sets are similar to the power sets of smaller sets, hinting that we can create a recursive function to generate them" is a bit misleading. The similarity between power sets of larger and smaller sets doesn't hint at the need for a recursive function. Instead, it might be more accurate to say that "The structure of power sets of larger sets, which include the power sets of their smaller subsets, suggests a recursive approach to generating them."

Unhelpful feedback. Eh.

The phrase "Let’s ask the three recursive algorithm questions about our power set algorithm" is awkwardly worded and redundant. It could be rephrased as "Let's address the three key questions for our recursive power set algorithm."

Formatting issue. The "three questions" thing is something I introduce in this book, but ChatGPT doesn't pick up on this since the input is split into 15,000 character chunks.

The last sentence in the paragraph starting with "The getPower

ChatGTP's response got cut off here again, for some reason.

AI Feedback for Chapter 7 - Memoization

The passage suggests that memoization increases memory usage, which might be misleading. While it's true that memoization involves storing results for later reference, this does not always mean that overall memory usage increases significantly. Often, the increased memory usage due to memoization is offset by the savings in computational resources.

Unhelpful feedback. This is an eye-rolling level of irrelevant nitpicking.

In the section "Memoization in Functional Programming", it's stated that a function is nondeterministic if it returns different values when passed the same arguments. While this is correct, it might be useful to specify that such behavior is due to the function relying on external or unpredictable factors, not because the function itself is inherently random or unpredictable.

Slightly helpful but disregarded edit suggestion. I should probably add a sentence about this, but it doesn't strike me as too urgent.

The section "Python's functools Module" ends abruptly, not completing the explanation about @lru_cache().

Formatting issue.

Grammar: In the paragraph that begins with "Side effects are any changes...", the phrase "Any trace that a function call leaves behind after returning is a side effect" might be better stated as "Any change that a function call effects outside its own scope, which persists after the function has returned, is considered a side effect."

Unhelpful feedback. Uhg, I hate this new wording.

In the example Python and JavaScript code provided, the argument 'indent' isn't explained. A reader who's not familiar with this code might find it confusing. Its purpose (which appears to be to control indentation in printed output for clarity) should be explained.

Formatting issue. This was explained earlier in the book.

The python and JavaScript examples are a bit complicated for an introductory text and make the code look more complex than it needs to be, mostly due to the indent and indentation variables and the printing statements. These extra lines of code are unnecessary for the core function of calculating Fibonacci numbers and demonstrating memoization, and could be removed or separated out to focus on the memoization itself.

False positive! Uhg. Actually these make the output so much easier to understand for a beginner, even though it's a departure from how most programming books present code like this. Then again, most programming books are kind of terrible. ChatGPT is trying to stamp out the unique things that make this book better than other sources.

The last line "The cache can have a memory size limit set" does not specify who or what sets the limit. The sentence could be clarified, for instance: "You can set a memory size limit for the cache."

Formatting issue.

In the JavaScript example code, the HTML 'pre' tags are used, which might be unfamiliar to some readers. The text could explain their purpose.

Unhelpful feedback. Eh, this book isn't for people brand new to JavaScript.

It's said that "dynamic programming uses recursion with repeated recursive cases; these are the overlapping subproblems." This definition could be expanded to say that dynamic programming uses memoization to avoid recalculating the same subproblems, which is a key feature of the technique.

Unhelpful feedback. Yes, the book eventually covers this as well.

The python script shows the indent variable being initialized as an argument of the fibonacci function with indent=0. In the JavaScript code, indent is checked for undefined inside the function body. While these are two ways of accomplishing the same goal in two different languages, it could confuse beginners who are trying to understand the differences between Python and JavaScript.

Unhelpful feedback. This is irrelevant. But kudos to ChatGPT for recognizing that the code in two different languages does the same thing.

In the first Python code snippet, the @functools.lru_cache() decorator should be placed immediately above the function it is meant to decorate. There should not be any other code (such as import statements) between the decorator and the function.

Formatting issue.

The statement that "calculating fibonacci(99) with the recursive algorithm would take a few centuries" is an exaggeration. While calculating the 99th Fibonacci number without memoization would be very time-consuming due to the exponential number of function calls, it would not likely take centuries.

False positive! No, it would literally take 600,000 years for my laptop to calculate fibonacci(99).

The printMessage() function in the second Python code snippet doesn't return a value. The lru_cache decorator won't have any effect on this function because it doesn't have a return value to cache.

False positive! The entire point of this code example, as explained in the book, is that this is an inappropriate use of lru_cache.

The statement that "memoized functions must be pure" is not entirely accurate. While it's true that the results are most predictable when memoization is used with pure functions, it can be used with impure functions in some circumstances if the developer is aware of the potential side effects and considers them acceptable for their particular use case.

Unhelpful feedback. Uh, sure. This is an obnoxious and vague nitpick.

In the sentence "The additions to the original fibonacciByRecursion.py program from Chapter 2 have been marked in bold:", the text doesn't show any content marked in bold.

Formatting issue.

The phrase "The doNotMemoize.py program demonstrates what happens when the @lru_cache function decorator (described in the previous section) memoizes these impure functions" is misleading because it is not the decorator that memoizes, but the decorator enables memoization. It could be rephrased as: "The doNotMemoize.py program demonstrates what happens when we use the @lru_cache decorator on these impure functions."

Unhelpful feedback. This is such a nitpick that I'm pretty sure it's technically wrong.

The term "nondeterministic function" may confuse some readers. While technically accurate, the explanation might be clearer if it were phrased something like: "In functions whose output isn't predictable (such as a function that returns the current time)..."

Formatting issue. The definition of nondeterministic function was in a previous chunk.

The term "impure functions" might also be a bit confusing. It could be better defined as "functions that are non-deterministic or that have side effects, meaning they change the state outside of the function."

Formatting issue. The definition of impure function was in a previous chunk.

The phrase "Memoized functions must be pure—that is, they must be deterministic" may lead to some confusion. It could be more accurate to say, "For best results, functions to be memoized should ideally be pure—that is, they should be deterministic".

Formatting issue.

The phrase "a programming paradigm that makes heavy use of recursion" can be misleading. While functional programming does often make use of recursion, this is not its defining characteristic. It could be better defined as "a programming paradigm that avoids changing state and mutable data."

Unhelpful feedback. This is a nitpick, and also the suggested wording would make the book worse.

AI Feedback for Chapter 8 - Tail Call Optiization

This statement "Many implementations of popular programming languages don’t even offer tail call optimization as a feature. These include interpreters and compilers for Python, JavaScript, and Java." is somewhat inaccurate. It's true for Python and Java, but not completely for JavaScript. ES6 does include proper tail call (PTC) semantics. As of my knowledge cutoff in 2021, however, its support across different JavaScript environments is uneven.

Unhelpful feedback. From my actual testing, mainstream browsers do not support TCO.

In the JavaScript code for the factorial function, the syntax function factorial(number, accum=1) is incorrect. JavaScript does not support default parameter values like Python does. Instead, the proper way to define a default value for a function parameter in JavaScript is to use an if statement inside the function to check if the parameter is undefined and if so, assign a default value.

False positive! JavaScript literally does support default parameters.

"The Java compiler since version 8 also doesn’t support tail call optimization." This implies that earlier versions of Java did support tail call optimization, which is not true. Java, regardless of the version, does not natively support tail call optimization.

Novel and useful feedback! Huh, I'm not sure where I heard that Java previosly supported TCO. But looking it up now, I think ChatGTP is right about this.

It would be useful to clarify the statement "The lack of tail call optimization is not unique to Python." While it is true that Python does not natively support tail call optimization, there are third-party libraries like recur.tco that provide support for this feature.

Slightly helpful but disregarded edit suggestion. Sure, okay. But this isn't relevant to the discussion here.

The statement "Recall from Chapter 1 that all recursive algorithms can be implemented with a stack and a loop. Since tail call optimization removes the need for a call stack, we are effectively using recursion to simulate a loop’s iterative code." could be misleading for beginners. The statement seems to imply that tail call optimization is equivalent to iterative loops. However, it's not entirely accurate - tail call optimization allows a recursion to behave more like an iterative loop, but they are not equivalent.

Unhelpful feedback. It's a metaphor.

AI Feedback for Chapter 9 - Drawing Fractals

Code execution errors in the JavaScript sections of the book. The JavaScript code is meant to execute the isOddTailCall function, but it mistakenly calls the isOdd function instead. The correct JavaScript code should look like:
document.write(isOddTailCall(42) + "<br />");
document.write(isOddTailCall(99) + "<br />");

Novel and useful feedback! Good catch here.

The function isOddTailCall in both Python and JavaScript versions does not handle negative inputs. While the text explicitly states that the functions are designed to handle only positive integers, it's typically good practice to include error handling for unexpected inputs.

Unhelpful feedback. It's just an example.

The book describes the use of tail recursion to prevent stack overflows and then says that Python and JavaScript might optimize tail recursion to prevent stack overflows. As of my knowledge cutoff in September 2021, neither Python nor JavaScript optimizes tail recursion. The book should clarify that the availability of tail call optimization depends on the specific implementation of these languages and that the most common implementations (CPython for Python and V8 for JavaScript) do not support it.

Formatting issue. The book says this elsewhere.

There's an incomplete sentence at the end of the text, it reads "You’ll form a shape that, if you’re familiar with...". The sentence should be completed or removed.

Formatting issue.

The book asserts that recursion can fail due to stack overflows while iterative solutions can't. This isn't always accurate. While it's true that recursion often presents a greater risk of stack overflows, iterative solutions can also cause stack overflows if they result in a call stack that exceeds its limits, such as with unbounded recursion.

Unhelpful feedback. Oh my god, this is technically true but is SUCH a nitpick.

While more of a matter of style, the sentence "Recursion can produce elaborate fractal art using surprisingly few lines of code." could be rephrased to avoid the use of the term "surprisingly" which could be considered subjective.

Formatting issue. I should update the prompt to tell ChatGPT that this book sometimes takes a casual conversational tone and that's fine.

There's a missing space in the sentence "As a technique, recursion is not automatically better or more sophisticated than iterative solutions." There should be a space between "iterative" and "solutions".

Formatting issue.

The explanation of recursion in the context of isOdd() and isOddTailCall() could be made clearer. It's possible for a reader to misinterpret the alternating true/false nature of the functions.

Unhelpful feedback. How can it be made clearer? This seems like ChatGPT is throwing stuff at the wall.

In the code section where the Sierpiński Triangle is drawn, there is a mistake in the import statement. It is written as "import turtle turtle.tracer(100, 0)". However...

Formatting issue.

In the same code block, the comment "# Return the x, y coordinate in the middle of the four given parameters." in the midpoint() function is technically inaccurate. It's not in the middle of the four parameters, but the midpoint between the two points defined by these four parameters.

Slightly helpful but disregarded edit suggestion. Eh, if I caught this earlier in the writing process I'd go with this suggestion.

The recursive drawing of the Sierpiński Triangle is done by calling drawTriangle() recursively inside the same function. However, these recursive calls are made after the drawing of the initial triangle. Since the turtle operations are synchronous, the output will not fully align with the described behavior. The smaller triangles will be drawn first because of the depth-first nature of the recursion. It's not incorrect, but it might cause confusion to learners.

Slightly helpful but disregarded edit suggestion. I kind of see what ChatGPT is getting at, but it's really not a significant issue.

In the code snippet drawing the Sierpiński Carpet, the import statement is incorrect. It should be...

Formatting issue.

In the fractal tree section, the script calls variables LEFT_ANGLE, LEFT_DECREASE, RIGHT_ANGLE, RIGHT_DECREASE without defining them first, and later on, these variables are defined inside a while True loop, which is not recommended. They should be defined before calling drawBranch().

Unhelpful feedback. Nah, this is a fake "best practice" but in ChatGPT's defense, is the same sort of bogus best practice an annoying human programmer would bring up in code review.

The random.seed(seed) call should be placed inside the while True loop, right before setting LEFT_ANGLE, LEFT_DECREASE, RIGHT_ANGLE, RIGHT_DECREASE. Otherwise, the random.seed(seed) call will only affect the random number generation once, instead of on each iteration of the loop.

False positive! Uh, the random.seed(seed) call is, in fact, inside the while loop. ChatGPT's advice is right, but it misread the code.

In the line "You can also set the DRAW_SOLID constant to False and run the program.", it should be "You can also set the DRAW_SOLID constant to False and run the program." to properly highlight code syntax. This is not necessarily a grammatical error but improves readability for programmers.

Formatting issue. Weird. I think ChatGPT's output had the DRAW_SOLID name in monospace but that was lost when I copy/pasted this to this HTML file for this blog post. Anyway, the initial code was in monospace.

The python source code for kochSnowflake.py is missing the typical python executable script directive or shebang at the top (#!/usr/bin/env python3). While it's not strictly necessary, especially if you're running the code directly in an interactive Python environment, it's a good practice to include it for scripts meant to be run at the command line.

Unhelpful feedback. Weird that ChatGPT didn't complain about this for any of the other Python programs. It's not necessary and a distraction in this context.

The python code import turtle turtle.tracer(10, 0) in both kochSnowflake.py and hilbertCurve.py should be separated into two lines for correct syntax...

Formatting issue.

There is an incorrect statement in the book. It is mentioned, "Each time you create a new bump, you are increasing the curve’s length from three b / 3 lengths to four b / 3 lengths, or 4b / 3." This statement is technically incorrect because it implies that the length of the curve was initially 3 * b/3 which is b. After the transformation, it implies the length of the curve is 4b/3, but in reality, the length of the curve has increased to 4/3 * b.

False positive! Uh, the initial length was 3 * b/3. And also, 4b/3 is the same as 4/3 * b. This advice was a waste of time.

In the code for the Koch Snowflake, the function drawKochSnowflake is called only once at the end of the script with hardcoded parameters. This makes the code less reusable. It would be better to place the function call inside a main function, and then call that main function in a standard Python idiom:
    if __name__ == "__main__":
        main()

Unhelpful feedback. It's weird that ChatGPT didn't complain about this for any other Python program. Anyway, it's not really a necessary best practice to follow for the context of this book.

There's a minor grammatical error in the sentence "A space-filling curve is a 1D line that curves around until it completely fills a 2D space without crossing over itself." It should be "A space-filling curve is a 1D line that curves around to completely fill a 2D space without crossing over itself."

Slightly helpful but disregarded edit suggestion. Meh.

The phrase "To learn more about drawing with Python’s turtle module, I’ve written a simple tutorial at https://github.com/asweigart/simple-turtle-tutorial-for-python." should be rephrased for clarity and correctness. It should say, "For more information on drawing with Python's turtle module, refer to the simple tutorial I've written at https://github.com/asweigart/simple-turtle-tutorial-for-python."

Slightly helpful but disregarded edit suggestion. Meh.

The sentence "The 3Blue1Brown YouTube channel has excellent animations of fractals, particularly the “Fractals Are Typically Not Self-Similar” video at https://youtu.be/gB9n2gHsHN4 and the “Fractal Charm: Space-Filling Curves” video at https://youtu.be/RU0wScIj36o." could be more concise. It should say, "For excellent animations of fractals, see the “Fractals Are Typically Not Self-Similar” and “Fractal Charm: Space-Filling Curves” videos on the 3Blue1Brown YouTube channel, available at https://youtu.be/gB9n2gHsHN4 and https://youtu.be/RU0wScIj36o respectively."

Slightly helpful but disregarded edit suggestion. Meh.

AI Feedback for Chapter 10 - File Finder

Technical Error: The hasEveryVowel function checks if the file name contains all the vowels (a, e, i, o, u), but the text states at one point that "We use a return statement with a lengthy expression that evaluates to True if name contains a, e, i, o, or u, indicating the file matches the search criteria." This should instead be "a, e, i, o, and u". The use of 'or' is incorrect in this context.

Novel and useful feedback! Actually, this is a good point.

Technical Suggestion: This is not necessarily an error, but the program could be improved for efficiency. Currently, the script is case insensitive only for vowel search (via the hasEveryVowel function) and not for even byte size search. Depending on the requirements, you might want to ensure case insensitivity across the board or at least mention this distinction in the text.

Slightly helpful but disregarded edit suggestion. Yeah, but performance isn't a priority in the context of these teaching examples.

Grammar Error: In the section "Finding the Files with an Even Number of Bytes", there is an inconsistency in tense. The sentence "This gives you the powerful capability to write code for any search criteria you want." should be "This will give you the powerful capability to write code for any search criteria you want." to maintain future tense as in the preceding and following sentences.

Unhelpful feedback. I'm not sure this is actually valid.

Grammar Error: In the section "The Recursive walk() Function", the text reads "The walk() function also recursively calls itself for each subfolder in the base folder it’s searching." This would read more clearly if it said "The walk() function also recursively calls itself for each subfolder in the base folder it is searching." This issue is about formality and readability, as "it's" can be less clear in formal writing.

Formatting issue. I should change the prompt to tell ChatGPT that this book isn't strictly written in a formal academic style.

Grammar Error: In the section "Finding Information About the File’s Name", the sentence "Enter the following into Python’s interactive shell." should end with a colon (:) instead of a period since it introduces a block of code.

Slightly helpful but disregarded edit suggestion. Yes, but there's a sentence that follows it, which is why there's a period there. Maybe I should have added the followup sentence as a parenthetical instead? Either way, it'd be wrong to follow ChatGPT's advice here.

Grammar Suggestion: While not technically wrong, the phrase "since browser-based JavaScript has no way to access the folders on your computer" might be better worded as "because browser-based JavaScript cannot access the folders on your computer" for clarity.

Slightly helpful but disregarded edit suggestion. Eh, I disagree.

Clarity Suggestion: In the section "The Complete File-Search Program", the text is unclear about what Figure 2-6 is. It's a minor point but could confuse readers who haven't seen this figure.

Formatting issue. The figures can't be included in the input to ChatGPT.

Python Code: In the 'visit' function, the 'hasVisited' variable is used, but it is not declared or passed as an argument. 'hasVisited' should be a global variable, or passed into 'visit' as an argument.

False positive! hasVisited is, in fact, a global variable.

When adding the nextIntersection to hasVisited, it should be added after the visit(nextX, nextY) recursive call, to avoid marking locations as visited before actually visiting them.

False positive! Making this change would introduce a bug in the program. ChatGPT is getting confused by the name of the variable.

JavaScript Code: The provided code snippet is incomplete, making it difficult to identify potential issues.

Formatting issue.

JavaScript traditionally uses camelCase for variable names and function names, not snake_case as is more common in Python.

False positive! The JS code here does use camelCase.

"While the time.localtime() function returns a struct_time object in the local time zone, the time.gmtime() function returns a struct_time object in the UTC or Greenwich Mean time zone." Here, "Greenwich Mean time" should be "Greenwich Mean Time."

In the sentence "The algorithm works by visiting a starting space in the maze and then recursively visiting a neighboring space." a comma is required after "maze".

Unhelpful feedback. Good point. Counterpoint: no it doesn't.

"The interaction between these os.path functions (which return Unix epoch timestamps) and time functions (which return struct_time objects) can be confusing." The word "these" should be replaced with "the".

Unhelpful feedback. No, "these" refers to the functions just used in the previous example.

In the sentence "After the walk() function returns a list of files matching your search criteria, you may want to rename, delete, or perform another operation on them." a comma is required after "criteria".

False positive! There is literally a comma already there. ChatGPT even has the comma when it's quoting it.

"Calling os.unlink() permanently deletes the file, which can be dangerous if a bug in your program causes the function to delete the wrong file." This sentence is a bit awkward. It could be rephrased as "It can be dangerous to permanently delete a file using os.unlink() if a bug in your program causes the function to delete the wrong file."

Slightly helpful but disregarded edit suggestion. Meh.

"To install this module, run run python -m pip install --user send2trash from the command prompt on Windows or run run python3 -m pip install from the terminal on macOS or Linux." The word "run" is unnecessarily repeated here.

Novel and useful feedback! Good catch.

"The search criteria are implemented as match functions, which are passed to the walk() function." The phrase "are implemented as match functions" should be replaced with "is implemented as a match function" for better clarity.

Unhelpful feedback. "Criteria" is plural.

"Chapter 4 described a recursive algorithm that solves mazes, but another recursive algorithm generates mazes." A comma is needed after "mazes".

False positive! Again, ChatGPT says a comma is necessary where there is already a comma and ChatGPT is quoting that comma.

"Let’s begin by taking a look at the complete Python and JavaScript source code for the program, which uses the recursive backtracking algorithm for maze generation." The phrase "Let's begin by taking a look" could be rephrased as "Let's start by examining".

Unhelpful feedback. Meh.

In JavaScript, to check if an array contains another array, the provided code is using JSON.stringify(hasVisited).includes(JSON.stringify([x, y - 2])) etc. This is not the most efficient or reliable way to do it because it depends on the serialization of the arrays, and the order of the elements matters. A better approach would be to use a suitable data structure or function to do this operation.

Unhelpful feedback. In the context of professional JS code, yes, but not for this book.

The statement "Unfortunately, JavaScript doesn’t have a way to set the seed value explicitly and will generate different mazes each time we run the program" is not accurate. While it's true that JavaScript's Math.random() does not support seeding directly, you can implement a pseudorandom number generator (PRNG) with a seed.

Unhelpful feedback. Cool. Yeah. Okay. I'll just reimplement my own PRNG. Thanks, ChatGPT. Great advice.

When explaining the maze data structure in JavaScript, the book mentioned that JavaScript objects are used as dictionaries. While this is generally correct, it's worth noting that JavaScript actually has a Map object that is more similar to Python's dictionaries, because it preserves the key insertion order.

Unhelpful feedback. Correct but not relevant.

In the sentence "If all the neighboring spaces have already been visited, the algorithm is at a dead end and backtracks to an earlier visited space to visit its unvisited neighbors," the phrase "an earlier visited space to visit its unvisited neighbors" is awkward and can be simplified for clarity. A better phrase might be "an earlier visited space to explore any unvisited neighbors."

Novel and useful feedback! Actually, yeah I like this phrasing.

In the sentence "The Python code continues by setting a few more constants," the word "constants" should be replaced with "variables" because in Python, there are no constants; the term "constant" is generally used for a variable whose value does not change. Although Python does not enforce this, it's just a naming convention in Python to have constants in all capital letters.

Unhelpful feedback. Correct but not relevant. Really not relevant.

In the sentence "This string notes whether this space is a blocking wall or a passable empty space in the maze," the term "notes" can be replaced with "indicates" or "denotes" for clarity.

Unhelpful feedback. Meh.

"After this, we add the x, y coordinates of nextX and nextY to the hasVisited list or array before making the recursive call for this neighboring space." - This sentence lacks context for the variables nextX and nextY. If this is part of a longer passage, it may be fine, but standalone, it's confusing. A code snippet or a description about how nextX and nextY are calculated would be useful.

Formatting issue.

"When no neighbors exist, the base case simply returns to an earlier location." - This sentence is slightly misleading. A base case in recursion refers to a condition that stops the recursion, not an action that's taken when a condition is met. It would be better to say something like "When no unvisited neighbors exist, the recursive function returns, which effectively moves the algorithm back to a previous location."

Formatting issue. ChatGPT is correct in general, but is wrong here because this chunk of text didn't have the earlier context.

"We can represent a well-connected maze with no loops as a DAG—that is, a tree data structure." - This sentence is not technically correct. A DAG, or Directed Acyclic Graph, is not a tree. While all trees (where each node has at most one parent) are DAGs, not all DAGs are trees. A maze with no loops could be represented as a tree, but once you have multiple possible paths from the start to a specific point (which is common in many mazes), it is better represented as a DAG but not specifically a tree.

Novel and useful feedback! Okay, so ChatGPT is misunderstanding here, but only because it turns out I'm using the term "well-connected maze" which isn't a real term. I need to replace it with "simply connected maze" which is a real term. And I also need to search the rest of the book for "well-connected maze" as well. So ChatGPT did help me find a mistake in the text.

"Incidentally, mathematicians have proven that even the hardest 15-puzzle can be solved in 80 moves." - While this statement is true, it would be better if it included a reference to support this fact.

Slightly helpful but disregarded edit suggestion. Huh, I thought I saw this on Wikipedia but it isn't there. I did find it in the paper "Large-Scale Parallel Breadth-First Search" by Richard E. Korf and Peter Schultze. I'm not going to add this here, but I should probably update Wikipedia.

"Just as you can turn a maze into a DAG, you can convert a 15-puzzle into a tree graph" - The phrasing "turn a maze into a DAG" and "convert a 15-puzzle into a tree graph" could be confusing, because it could be interpreted as saying that the maze or puzzle is being altered in some way, rather than just being represented or modeled as a DAG or tree.

Unhelpful feedback. Meh.

In Python Code: The solve function contains the following code snippet:
if solved:
    displayBoard(board)
    for move in solutionMoves:
        print('Move', move)
        makeMove(board, move)
        print() # Print a newline.
        displayBoard(board)
The purpose of solving the puzzle is defeated here because we are making the moves again after we have already solved the puzzle. If we want to display the board after every move, we should maintain a list of board states and use that for printing. The list would contain the state of the board after every move made.

False positive! Oh god, this is terrible advice. One: we don't want to display the board after move because that'd be a ton of useless output that would make hte program unworkably slow. It'd also eat up tons of memory for no reason required by this program.

"Clever algorithms are available for solving 15-puzzles, but we could also just recursively explore the entire tree graph until we find a path from the root node to the solution node." - The use of "just" here seems to downplay the complexity of the task. It might be better to say "alternatively" or "also".

Unhelpful feedback. Meh.

"The root node is the starting state of the 15-puzzle. The solved-state node is the one in which the tiles are ordered correctly." - For clarity, it might be better to combine these two sentences: "The root node represents the starting state of the 15-puzzle, while the solved-state node corresponds to the correctly ordered tiles."

Unhelpful feedback. Meh.

"Because it is possible to

ChatGPT cut off it's output here for some reason.

AI Feedback for Chapter 13 - Fractal Art Maker

In the drawFractal() function, there's a base case that stops recursion when the size of the shape is less than 1. This could potentially be misleading or confusing to some readers as in many graphics systems, you can draw shapes that are less than a pixel in size and they will simply not be visible. The base case could perhaps be better described as stopping when the shapes are too small to be visible, rather than when their size is less than 1.

Unhelpful feedback. Meh.

In the first Python code snippet of drawFilledSquare(size, depth): size = int(size), there's an error due to incorrect indentation. It should be...

Formatting issue.

The description of the turtle's movement to the top-right corner of the square is incorrect. The code provided does not move the turtle to the top-right corner but to the top-left corner of the square. Here's the correct version:
# Move to the top-left corner before drawing: 
turtle.penup() 
turtle.backward(size // 2)  # Move to the left
turtle.left(90) 
turtle.forward(size // 2)  # Move upwards
turtle.right(90)  # Now facing the right direction to start drawing
turtle.pendown()

False positive! This is weird. Both the code and the text talk about the top-right corner, but ChatGPT just decided this was wrong and that the book actually wants to use the top-left corner. The suggested code does work to move the turtle to the top-left corner, but I do not want to move it to the top-left corner. I want to move it to the top-right corner. What a weird suggestion to make.

In the triangle drawing section, there's an incorrect statement that says "to begin drawing the line on the right side, the turtle must turn 90 degrees right to face rightward, then an additional 60 degrees to face the bottom-right corner of the triangle." This is wrong, as the turtle needs to turn 150 degrees right in total to face the bottom-left corner of the triangle, not the bottom-right corner. So, the corrected code and explanation should be:

# Move the turtle to the top of the equilateral triangle:
height = size * math.sqrt(3) / 2
turtle.penup()
turtle.left(90) # Turn to face upward.
turtle.forward(height * (2/3)) # Move to the top corner.
turtle.right(150) # Turn to face the bottom-left corner.
turtle.pendown()

False positive! Again, this is completely wrong.

Also, when talking about the angleChange value in the context of the fractal generation, the text doesn't mention that this value is in degrees, which might lead to confusion. This clarification could be added for completeness.

Novel and useful feedback! I mention degrees later, but yeah I should have added this sooner too.

"The for loop assigns an individual specification dictionary in the specs list to the loop variable spec on each iteration of the loop." The sentence can be a bit clearer. Suggested change: "On each iteration of the loop, the for loop assigns an individual specification dictionary from the specs list to the loop variable, spec."

Unhelpful feedback. Meh.

"The get() dictionary method calls pull the values for the sizeChange, xChange, yChange, and angleChange keys from this dictionary..." The phrase "method calls pull" is a bit confusing. Suggested change: "The get() method calls extract the values for the sizeChange, xChange, yChange, and angleChange keys from this dictionary..."

Unhelpful feedback. Meh.

"The shapeDrawFunction, specs, and maxDepth arguments are passed to the recursive drawFractal() call unchanged." This sentence is grammatically correct, but could use some rewording for clarity. Suggested change: "The arguments: shapeDrawFunction, specs, and maxDepth, are passed unchanged to the recursive drawFractal() call."

Unhelpful feedback. Meh.

"Finally, with the turtle in the correct position and heading for the next shape, we make the recursive call to drawFractal():" The use of "we" in technical documents is often considered informal. Suggested change: "Finally, once the turtle is in the correct position and heading for the next shape, a recursive call to drawFractal() is made:"

False positive! This is actually worse, since it changes the text to passive voice.

"The Glider fractal here has additional Gliders drawn inside each of its five cells." The capitalization of "gliders" seems inconsistent with the rest of the text. Suggested change: "The glider fractal here has additional gliders drawn inside each of its five cells."

Unhelpful feedback. Meh.

"The squares are created slightly higher or lower than their previous square and rotated either 10 or -10 degrees." Suggested change for clarity: "The squares are created slightly higher or lower than the previous square and are rotated by either 10 or -10 degrees."

Unhelpful feedback. Meh.

"The center of these smaller triangles is size * math.sqrt(3) / 6 units from the center of the previous triangle." The phrase "size * math.sqrt(3) / 6 units" may be clearer with parentheses to indicate the intended order of operations. Suggested change: "The center of these smaller triangles is (size * math.sqrt(3) / 6) units from the center of the previous triangle."

Unhelpful feedback. Meh.

"These shapes are drawn with a size of 600:" This sentence is a bit confusing as the code below it shows shapes drawn with a size of 400, not 600. If 400 is the correct size, the sentence should read: "These shapes are drawn with a size of 400:"

Novel and useful feedback! Good catch. This should be 400 instead of 600. I think this was a copy/paste mistake when I was editing the text.

AI Feedback for Chapter 14 - Droste Maker

A potential area of confusion might be the term 'base case' in the context of recursion. This term is correctly used but it might be helpful to define or explain what a 'base case' is at the beginning of the chapter for those who are not familiar with the term. The 'base case' in a recursive function is a condition that stops the function from calling itself ad infinitum.

Formatting issue. This was explained previously in the book.

As a minor point, you could consider clarifying that the magentaColor variable is a tuple, which is a type of collection in Python that is ordered and immutable. This could be a useful point of learning for readers who are less familiar with Python.

Slightly helpful but disregarded edit suggestion. Meh.

Misunderstanding of aspect ratio: The book states, "Because the aspect ratio is the width divided by the height, images with large aspect ratios are taller than they are wide, and those with small aspect ratios are wider than they are tall." This is incorrect. The aspect ratio is indeed the width divided by the height, but images with a larger aspect ratio are wider, not taller.

Novel and useful feedback! Good catch.

Code snippet about resizing the image: It seems you are resizing the image to be equal or larger in both dimensions (width and height) than the magenta area. This would potentially distort the image as you are not respecting the aspect ratio. You should keep the same aspect ratio while making sure that either the width or height is equal or larger than the magenta area, not both.

False positive! The code snippet has an if-else statement, so it's doing one or the other, not both.

"We need to resize the base image to cover the entire magenta area and no more." – This sentence is awkward. "And no more" can be removed for clarity.

Unhelpful feedback. Meh.

"We call the resize() method once to produce a new Pillow Image object resized to match either the width of the base image or the height of the base image." – This sentence could be rephrased for clarity. It currently implies that the resized image is the same width or height as the base image, which could lead to confusion.

Unhelpful feedback. Meh.

"However, the resized image itself could have magenta pixels, and if so, these will now become part of the base image, as in the top-right image of Figure 14-2." – The reference to a figure (Figure 14-2) that hasn't been mentioned before could cause confusion. If this figure isn't relevant, the sentence can be rephrased to improve clarity.

Formatting issue. The figure isn't included in ChatGPT's input.

Book Review: Python Distilled

2023-03-28T12:00:00-04:00

Python Distilled by David Beazley. Published by Pearson September 2021. 352 pages.

5 stars. Python Distilled has a perfectly suited title: This book is for experienced programmers who want to learn Python and need the Python programming language's core syntax, standard library, and Pythonic idioms. However, if you're a developer who wants to add Python to your toolbox, I recommend Python Distilled as one of the first books you should read.

Beazley endorses the view that programming should be kept simple by using simple syntax, and it shows in this book. But don't think that Python Distilled is afraid to dive into the advanced features of the Python language. And at 350 pages, the book strikes a good balance between giving you the information you need without overwhelming you with every nook and cranny of the language.

While the title might make you think the information is densely packed, I didn't have any trouble reading through the chapters. The book is well-paced.

If you're a complete beginner to programming, I'd recommend starting with a different book. But Python Distilled could easily be the second book on your list once you have some experience. For a comparable book, Python Distilled is similar in its aim as The Quick Python Book by Naomi Ceder. After reading this book, I'd recommend moving on to Fluent Python by Luciano Ramahlo, Effective Python by Brett Slatkin, Python in a Nutshell by Martelli, Ravenscroft, Holden, and McGuire, and Serious Python by Julien Danjou.

Book Review: Python in a Nutshell

2023-03-28T12:00:00-04:00

Python in a Nutshell, 4th Edition by Alex Martelli, Anna Ravenscroft, Steve Holden, Paul McGuire. Published by O'Reilly February 2023. 735 pages.

5 stars. Python in a Nutshell is an excellent book for professional developers who have some experience with Python but want to take the leap to being a senior Python developer, Python in a Nutshell is required reading.

This is not a book for beginners new to programming, and I’d be hesitant to say that programmers experienced in other languages should use this book to learn Python (but if you’re the bold adventurous sort, have at it.) But if you want to fill out your Python knowledge and go beyond a developer who “kinda sorta” knows Python and copies and pastes Python code from Stack Overflow without much thought, this is a book you need to read.

In a way, the title is a bit misleading. “In a nutshell” gives you the idea that this book is small, but it’s actually over 700 pages long. Rather, this book is compact: it doesn’t waste time covering the basics and is quite dense with useful information.

The density of this book sometimes works against itself; there were quite a few times I had to carefully parse out the words and could have really used some example code to demonstrate the concepts. I understand why the authors skipped it: not everyone will need the additional explanation for every concept, and providing these examples would have doubled the page count. (For example, the object-oriented chapter led me to take quite a few breaks to test out what I had learned in the Python interactive shell just to make sure I understood what I read.) Suffice it to say, the information in the book is useful and accurate. It’s worth the time it sometimes takes to parse through the difficult concepts.

Other times though, it’s a breeze. There’s quite a wide range of topics covered in this book, and I feel like they do a good job going deep enough into each one without losing the big picture. And quite frankly: a lot of the information in this book just plain isn’t easy to find online. Without this book, you’d be chasing endless search result links to blog posts of varying quality, all while still missing out of several topics. The real value of Python in a Nutshell is that it gathers all of this knowledge into one well-written book.

Other books similar to Python in a Nutshell include Fluent Python by Luciano Ramahlo, Effective Python by Brett Slatkin, and Serious Python by Julien Danjou. I recommend reading all of these books though; while they have some overlap they complement rather than replace each other. If you’re experienced in a different language but want to learn Python, Python Distilled by David Beazley is a good book to read first for general Python information, and then followed up by Python in a Nutshell.

Even as a software engineer with years of experience in Python myself, I kept finding little nuggets of information that has filled in gaps of my Python knowledge that I didn’t know I had. Again, it’s not a book for total beginners but don’t let that scare you off. As long as you have the basics of programming concepts and are generally comfortable writing Python code, go ahead and get started with Python in a Nutshell.

How to Install Pygame on Windows, macOS, and Linux

2023-01-27T12:00:00-05:00

If you know how to run pip (Python's package installer) from a terminal window, run:

pip install pygame

If you don't know how to use pip in the terminal, then you can install in Python's interactive shell (or REPL) by running:

import subprocess, sys; subprocess.run([sys.executable, '-m', 'pip', 'install', 'pygame'])

(This is the way pipfromrepl installs Python packages from the interactive shell.)

This process works on Windows, macOS, and Linux for Python versions 3.6 to 3.10. Note that as of January 2023, the Pygame maintainers haven't updated Pygame to work on Python 3.11 or 3.12. However, there is a .whl "wheel" file available to install Pygame on Python 3.11 on Windows. Either run this from a Command Prompt or Windows Terminal window:

pip install https://inventwithpython.com/pygame/pygame-2.1.2-cp311-cp311-win_amd64.whl

Or run this from the interactive shell:

import subprocess, sys; subprocess.run([sys.executable, '-m', 'pip', 'install', 'https://inventwithpython.com/pygame/pygame-2.1.2-cp311-cp311-win_amd64.whl'])

You can test to see if Pygame was installed successfully by importing it from the interactive shell. If no error message appears, the installation was successful:

>>> import pygame >>>

This blog post will be updated as new versions of Python and Pygame are made available.

Python Linter Comparison 2022: Pylint vs Pyflakes vs Flake8 vs autopep8 vs Bandit vs Prospector vs Pylama vs Pyroma vs Black vs Mypy vs Radon vs mccabe

2022-11-19T12:00:00-05:00

I'm giving a talk on static code analysis tools at PyCon 2023. Here's the slidedeck. I'll be updating this blog post as I learn more information.

As you can tell from the lengthy title, there are many linting tools for Python. Some of them have near-identical names as each other. In November 2022, I upgraded my text editor to Sublime Text 4 and then took the opportunity to spend a few hours reviewing all of the Python linters I could find. After personally reviewing all of them, I've selected the following as must-haves: Pyflakes, Mypy, and Black. If you'd like additional tools, I also liked: Radon, Pyroma, and docformatter. I'm using Python 3.12.0. I don't care for my linter to point out when I stray from the certain dictates in the PEP 8 document, and my linter choices reflect that. You might have different needs and values than I, so in this blog post I give my reasoning and views for each linter.

You can skip most of this discussion by using an IDE such as PyCharm Community Edition and Microsoft Visual Studio Code, which already have integrated linters set up for you. But this blog post is good if you want to customize your development environment.

Linter is an overly broad term for a tool that examines your source code without running it (aka static code analysis) in order to point out possible issues. This early warning system speeds up your development, as you can fix them early in the development process rather than wait for QA or users to point them out. The term linter comes from how dryer lint traps can remove small bits of fluff from clothing. I've broken up these tools into the following categories:

Type checkers verify that your program follows their own type annotations (aka type hints). (Mypy, Pyright, Pyre, Pytype)
Error linters point out syntax errors or other code that will result in unhandled exceptions and crashes. (Pylint, Pyflakes, Flake8)
Style linters point out issues that don't cause bugs but make the code less readable or are not in line with style guides such as Python's PEP 8 document. (Pylint, Flake8)
Packaging linters point out issues related to packaging your code for distribution on PyPI with properly formatted descriptions, versions, and meta data fields. (Pyroma)
Security linters point out possible security vulnerabilities in your code. (Bandit, Dodgy)
Code formatters change the style of your code (mostly revolving around proper whitespace) without affecting the behavior of the program. (Black)
Dead code linters remove commented-out code from your program, since this practice should be skipped in favor of proper version control. (Vulture, eradicate)
Docstring linters/formatters point out (and may correctly format) style issues in docstrings that aren't in line with Python's PEP 257 document. (pydocstringformatter, docformatter)
Complexity analyzers point out code that is so complex that they can affect readability. (mccabe, Radon)

Many of these Python packages include other Python packages, as explained in this table:

This Package...	...Includes These Packages
flake8	Pyflakes, pycodestyle, mccabe
autopep8	pycodestyle
Pylama	pycodestyle, pydocstyle, Pyflakes, mccabe, Pylint, Radon, eradicate, Mypy, Vulture
Prospector	Pylint, flake8 (including Pyflakes, pycodestyle, mccabe), dodgy, isort, pydocstyle, pep8-naming

Disqualified Packages

Out of the running immediately is PyChecker because it hasn't been updated since 2003, so I skipped evaluating it. The same goes for Pylava, a fork of Pylama that hasn't been updated since September 2020. I'd just use the original Pylama instead.

Mypy (Type Checker)

Mypy is not a linter but rather a static type checking tool. You should install and use it no matter what Python linter you use. Mypy examines the type hints (aka type annotations) you put on your functions and variables and ensures the rest of the program correctly follows them. It's a great way to find bugs early. I wrote a blog post on Python type hints if you need to learn more. Mypy was the first static type checker for Python and has been suitable for my needs; I haven't evaluated the others: Pyright from Microsoft, Pyre from Facebook (installed with pip install pyre-check and not pip install pyre), and Pytype from Google.

Pyflakes (Error Linter)

From the Pyflakes project page:

Pyflakes makes a simple promise: it will never complain about style, and it will try very, very hard to never emit false positives. Pyflakes is also faster than Pylint. This is largely because Pyflakes only examines the syntax tree of each file individually. As a consequence, Pyflakes is more limited in the types of things it can check. If you like Pyflakes but also want stylistic checks, you want flake8, which combines Pyflakes with style checks against PEP 8 and adds per-project configuration ability.

Pylint (Error and Style Linter)

From the Pylint project page:

Pylint is a static code analyzer for Python 2 or 3. Pylint analyses your code without actually running it. It checks for errors, enforces a coding standard, looks for code smells, and can make suggestions about how the code could be refactored.

Pylint has extensive documentation.

You can see the kinds of code smells that Pylint points out in this example output:

example.py:609:35: C0103: Argument name "n" doesn't conform to snake_case naming style (invalid-name)
example.py:642:15: R1701: Consider merging these isinstance calls to isinstance(PAUSE, (float, int)) (consider-merging-isinstance)
example.py:655:4: R1705: Unnecessary "elif" after "return", remove the leading "el" from "elif" (no-else-return)
example.py:670:12: R1705: Unnecessary "else" after "return", remove the "else" and de-indent the code inside it (no-else-return)
example.py:675:12: W0707: Consider explicitly re-raising using 'except Exception as exc' and 'raise ImageNotFoundException from exc' (raise-missing-from)
example.py:686:20: C0209: Formatting a regular string which could be a f-string (consider-using-f-string)
example.py:771:17: W0212: Access to a protected member _position of a client class (protected-access)
example.py:1038:0: R0913: Too many arguments (7/5) (too-many-arguments)
example.py:1168:47: E1306: Not enough arguments for format string (too-few-format-args)
example.py:1418:0: R0914: Too many local variables (17/15) (too-many-locals)
-----------------------------------
Your code has been rated at 3.42/10

I prefer Pyflakes to Pylint, though running pylint --errors-only cuts out the style suggestions and gives me output similar to Pyflakes. Pylint tends to be slower than Pyflakes and flake8 as well as give more false positives. I'd use Pylint if you want to be especially thorough with your code.

pycodestyle (Style Linter)

From the pycodestyle project page:

pycodestyle is a tool to check your Python code against some of the style conventions in PEP 8. This package used to be called pep8 but was renamed to pycodestyle to reduce confusion.

pycodestyle is included with flake8, autopep8, Pylama, and Prospector.

Black (Code Formatter)

Black is not a linter but rather a code formatter that changes spacing and other cosmetic aspects of your source code without changing the behavior of your program. You should install it and use it no matter what Python linter you use. I prefer to run it with the command-line arguments black -l 120 -S yourScript.py so that it formats yourScript.py with a line length of 120 (the default is 88) and doesn't change the quotes for your strings (I like using single quote string but Black formats them into double quote strings.) I cover it in Chapter 3 of my free book, Beyond the Basic Stuff with Python

autopep8 (Style Linter and Formatter)

autopep8 uses pycodestyle to detect style issues and then automatically correct them. I've personally preferred the way Black formats code over pycodestyle.

pyupgrade (Style Linter)

I'm wary of pyupgrade. On the one hand, it seems to update Python syntax to more modern syntax that later versions of Python use. On the other hand, the documentation is spotty and there's no way to see what changes it would make before it makes them. The project does seem to be maintained with regular releases, though I'd want to carefully evaluate it before recommending it to others.

mccabe (Complexity Analysis)

mccabe is not a traditional Python linter, but rather measures cyclomatic complexity. Cyclomatic complexity (also called McCabe complexity after its creator in 1976) measures the number of linearly independent paths through some source code. Functions and methods with a score greater than 10 are generally considered "too complicated" and should be simplified. In this case, simplification means using shorter functions and removing duplicate code. Take the cyclomatic complexity score with a grain of salt; if anything, just use the score as an indicator of what parts of your source code might need a second look at. Don't use the score as a hard rule for what needs to be simplified; you'll end up with a program with overloaded with tiny functions that are far more unreadable than what it was before.

mccabe is installed with flake8, Pylama, and Prospector.

After installing, run the program with python -m --min 10 mccabe example.py. Some example output of functions and methods with a minimum score of 10 would look like the following:

TryExcept 182 10
646:0: '_normalizeXYArgs' 13
826:0: '_normalizeButton' 10
1418:0: '_mouseMoveDrag' 11
1899:0: '_tokenizeCommandStr' 19
2025:0: '_runCommandList' 21

Ooof, I should take a look at that _runCommandList function I wrote and see if I can simplify it.

Radon (Complexity Analysis)

Radon includes the mccabe package to perform cyclomatic complexity measurement, but also has options for measuring LOC ("lines of code"), the Halstead metrics (based on number of operators and operands to calculate the "difficulty" of understanding the code), and a Maintainability Index (using the same metrics formula used by the Microsoft Visual Studio IDE). How these metrics are calculated is given in the documentation.

For example, I ran these Radon measurements on some of my code, and the output looks like this:

C:\Users\Al\Desktop\lintercmp>radon cc C:\github\pyautogui\pyautogui\__init__.py
\github\pyautogui\pyautogui\__init__.py
    F 2025:0 _runCommandList - D
    F 1418:0 _mouseMoveDrag - C
    F 1899:0 _tokenizeCommandStr - C
    F 646:0 _normalizeXYArgs - C
    F 826:0 _normalizeButton - B
    F 1733:0 displayMousePosition - B
--SNIP--
    F 2157:0 getInfo - A
    C 28:0 PyAutoGUIException - A
    C 38:0 FailSafeException - A
    C 48:0 ImageNotFoundException - A

C:\Users\Al\Desktop\lintercmp>radon raw C:\github\pyautogui\pyautogui\__init__.py
\github\pyautogui\pyautogui\__init__.py
    LOC: 2163
    LLOC: 821
    SLOC: 1048
    Comments: 154
    Single comments: 117
    Multi: 593
    Blank: 405
    - Comment Stats
        (C % L): 7%
        (C % S): 15%
        (C + M % L): 35%

C:\Users\Al\Desktop\lintercmp>radon hal C:\github\pyautogui\pyautogui\__init__.py
\github\pyautogui\pyautogui\__init__.py:
    h1: 19
    h2: 329
    N1: 268
    N2: 524
    vocabulary: 348
    length: 792
    calculated_length: 2831.7901243143224
    volume: 6686.811248712193
    difficulty: 15.130699088145896
    effort: 101176.1288634933
    time: 5620.89604797185
    bugs: 2.2289370829040647

C:\Users\Al\Desktop\lintercmp>radon mi C:\github\pyautogui\pyautogui\__init__.py
\github\pyautogui\pyautogui\__init__.py - B

You'll need to peruse the documentation to figure out what exactly means, as it isn't very readable (funny enough). I wouldn't say Radon is as necessary as a type checker or error linter, but it can provide useful information on the general size of your code. Be sure not to confuse metrics with actual quality.

flake8 (Error & Style Linter, Complexity Analysis)

Flake8 is a bundle of Pyflakes, pycodestyle, and mccabe and merges the output of these programs together. It's like Pylint but with the mccabe package included as well. Use this if you want to run these several tools at the same time.

Pylama ("Kitchen Sink")

Pylama is the kitchen sink, containing several linters and other tools: pycodestyle (style linter), pydocstyle (docstring linter), Pyflakes (error linter), mccabe (complexity analysis), Pylint (error and style linter), Radon (complexity analysis), eradicate (dead code linter), Mypy (type checker), Vulture (dead code linter).

I'm not sure how practical it is to have all of these tools run on your source code, and it definitely needs fine tuning to limit the false positives. But if you looked at this blog post and wanted to download all of these tools in one package, Pylama does this. Pylama and Prospector are similar "kitchen sink" packages, but as of November 2022 seem to require different versions of their bundled packages and can't both be installed at the same time.

Prospector ("Kitchen Sink")

Prospector is also a bundle of several tools, outlined in their documentation. Installing Prospector installs Pylint (error and style linter), pycodestyle (style linter), Pyflakes (error linter), mccabe (complexity analysis), dodgy (security linter), and pydocstyle (docstring linter). There are also other packages you can optionally install as well. Like Pylama, Prospector is useful to install if you want several different tools to run with one command. Pylama and Prospector are similar "kitchen sink" packages, but as of November 2022 seem to require different versions of their bundled packages and can't both be installed at the same time.

Bandit (Security Linter)

Bandit can detect some security issues in your Python code, as listed on their website. In my limited testing, I found that it's mostly false positives but I can see this as a good sanity test. You'll want to create your own .bandit configuration file that skips the B601 test that alerts you to the use of assert statements (by far the most common "security issue" that Bandit pointed out.) I haven't found any other such security linters for Python.

Dodgy (Security Linter)

Dodgy is "designed to detect things such as accidental SCM diff checkins, or passwords or secret keys hard coded into files." This might be nice to have, but the project hasn't been updated since December 2019 and I couldn't get it to trigger anything. I stored valid credit card numbers in variables, had a variable named "password", but nothing seemed to raise any warnings from Dodgy. The README also claims "This is a very early version with minimal functionality right now, but will be improved over time." I don't see Dodgy as a necessary tool.

When my source code cleared with no issues, Dodgy still outputted the following:

{
  "warnings": []
}

Most tools output nothing when there are no issues to keep from polluting the output stream with unnecessary text.

Pyroma (Packaging Linter)

If you've seen projects on PyPI that say "The author of this package has not provided a project description" then you've seen a project that would benefit from Pyroma. From the Pyroma project description:

Pyroma rhymes with aroma, and is a product aimed at giving a rating of how well a Python project complies with the best practices of the Python packaging ecosystem, primarily PyPI, pip, Distribute etc, as well as a list of issues that could be improved.

The project description lists what Pyroma checks for. While they are all fairly basic, they're easy to miss when putting together a package for uploading to PyPI. I haven't found any other "packaging linters," so Pyroma is a must-have for me when I intend distribute your code.

Vulture (Dead Code Linter)

Vulture detects unused variables, functions, and methods. It generated a high number of false positives for me, so I find its usefulness limited.

eradicate (Dead Code Linter/Remove)

eradicate can find (and also remove) commented out code. I had trouble getting it to run on Windows: the -m doesn't work, forcing you to enter the full name of the eradicate Python script (which confusingly doesn't end in .py), and you can't run eradicate on a folder of files or pass a wildcard to have it run on multiple files. I also don't necessarily agree that commented-out code has no place if you use source control. Personally, I'd pass on eradicate.

autoflake (Dead Code Linter)

autoflake is extremely limited and has a poor choice of name: It removes unused standard library imports and unnecessary pass statements. That's it. The name comes from the fact that it uses Pyflakes to do this.

I'd pass on this. Pyflakes, flake8, or the other linters can already point out unused imports, so a dedicated package to do this seems redundant to me.

docformatter (Docstring Formatter)

From the project description:

docformatter automatically formats docstrings to follow a subset of the PEP 257 conventions. Below are the relevant items quoted from PEP 257.

For consistency, always use triple double quotes around docstrings.
Triple quotes are used even though the string fits on one line.
Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description.
Unless the entire docstring fits on a line, place the closing quotes on a line by themselves.

docformatter also handles some of the PEP 8 conventions.

Don’t write string literals that rely on significant trailing whitespace. Such trailing whitespace is visually indistinguishable and some editors (or more recently, reindent.py) will trim them.

pydocstringformatter (Docstring Formatter)

From the project description:

A tool to automatically format Python docstrings to follow recommendations from PEP 8 and PEP 257. This project is heavily inspired by docformatter.

It seems to be much less popular than docformatter, though both are currently maintained. Continued from the description:

As such, the biggest difference between the two is that pydocstringformatter fixes some of the open issues we found in docformatter. In general, the output of both formatters (and any other docstring formatter) should be relatively similar.

pydocstyle (Docstring Linter)

pydocstyle seems to be another docstring linter.

isort (Style Linter for Import Statements)

isort is bundled with Prospector. From the project description:

"isort is a Python utility / library to sort imports alphabetically, and automatically separated into sections and by type."

This is interesting, but I could also see it occassionally causing problems when the order of import statements does matter for some subtle reason. I'd use it as a linter, but not as something that automatically formats the order of import statements.

I Want To Help Everyone And I Will Fail

2022-11-15T12:00:00-05:00

I like to program computers. An army of a million file clerks wouldn't be as productive as my laptop running the right code. And my house only has one bathroom so the line would be quite long too.

I like to teach other people to program. As productive as I can be with a computer, I can write a book that enables thousands of others to become equally productive. It's a lot of work to write one of my books, but once done it costs me about $15 a month in web hosting fees to share it with thousands of people, anywhere in the world.

And my readers can contact me. You can contact me. My email address is al@inventwithpython.com.

And readers do contact me. A lot. Currently I have 1,254 unread messages, some going back years. I get emails that only say, "My program doesn't work." I've written a blog post on how to effectively ask for programming help, and sometimes I'm so busy all I can do is just reply with a link to it.

Sometimes readers ask more than just a question, but are basically asking me to write software for them. Sometimes readers ask me how they can "learn programming" and if I could be their tutor. The answer can literally fill several books, and I have written these books. I reply telling them that I'm unfortunately too busy to provide individual help. (At least, unless they're willing to pay me several thousand U.S. dollars. I assume they aren't able to do that, so I don't mention it.)

The thing is, though, I want to write that software with them. I want to provide them with individual tutoring over Zoom. I want to provide a five-page response to their question and give them advice. I want to help everyone and I will fail to do so.

I'm getting older. I started writing programming books in 2009. There's no way I could reach as many people except by writing books and putting them for free online. I'm one person, and I make a much better author than classroom instructor or remote tutor. (I always support teachers and teachers unions because no book or online course could ever substitute them.)

I can't even tell the readers who email me this; likely you've found this because I sent you a link to this instead of typing it up again. Or maybe you've emailed someone else entirely, and they've pointed you to this blog post. I've found that writing a public blog post instead of an individual reply email is much more effective. Still, my blog post drafts folder has over a hundred blog posts I've started but haven't finished.

I hope you're not offended by my lack of individual response. I want to encourage you that, no matter what current frustration or confusion you're experiencing at this point in your programming journey, others have experienced it too and have successfully moved on to the next challenge. I may not have enough time to help you in particular, but I have an unlimited amount of sincerity in my belief in you.

Thank you for your email. I'm sorry for the delay in my response. I'm afraid that my schedule is too busy to provide individual guidance, but I wish you good luck and hope you keep up your efforts.

Installing Brython to Get Python in Your Browser

2022-10-31T12:00:00-04:00

JavaScript is not the only programming language you can run in the browser. Brython is a Python interpreter implemented in JavaScript so you can run Python code in your browser. This lets you have a Python interactive shell without having to install Python. You can also write Python code to interact with the DOM and create browser apps just like you could with JavaScript. The primary downside is that a browser must download about 6 megabytes of JavaScript files before it can run, which can be a significant delay. This blog post guides you through setting up Brython.

To "install" Brython, download the zip file from the Brython release page on GitHub: https://github.com/brython-dev/brython/releases/. (As of October 2022, this is Brython-3.11.0.zip)

Inside this zip file is brython.js and brython_stdlib.js. To get an interactive shell in a webpage, create a .html file with a text editor and copy/paste the following code:

<!doctype html>
<html>
<head>
    <script type="text/javascript" src="brython.js"></script>
    <script type="text/javascript" src="brython_stdlib.js"></script>
    <style>
    .codearea {
        background-color:#000;
        color:#fff;
        font-family:'Oxygen Mono', Consolas, 'Liberation Mono', 'DejaVu Sans Mono', monospace;
        font-size:14px;
        overflow:auto
    }
    </style>
</head>

<body onload=brython({"debug":1}) ><!-- remove the 1 to leave debug mode -->
    <noscript>Please enable Javascript to view this page correctly</noscript>

    <textarea id="code" class="codearea" rows="20" cols="100"></textarea>

    <script type="text/python3">
        from interpreter import Interpreter

        # Start an interactive interpreter in textarea with id "code"
        Interpreter("code")
    </script>
</body>
</html>

Open this .html in your browser to view the interactive shell:

The Brython zip file you downloaded also has a demo.html file that showcases many examples of Python code that can interact with the Document Object Model (DOM). Instead of putting JS code inside of a <script type="text/python"> tag, you put Python code inside of a <script type="text/python"> tag.

You can also install Brython as a module to your Python installation using pip. Run pip install brython. This installs a brython-cli script. When you run brython-cli install, the script creates the following files in the current directory:

README.txt
brython.js
brython_stdlib.js
demo.html
index.html
unicode.txt

If you run python -m http.server to run a web server on your computer, then open your browser to the address http://localhost:8000 you will see the contents of index.html rendered in the browser. Right-click the web page and select View Source (or open index.html in a text editor) to view the Python code being run by Brython:

<!doctype html>
<html>

<head>
<meta charset="utf-8">
<script type="text/javascript" src="brython.js"></script>
<script type="text/javascript" src="brython_stdlib.js"></script>
</head>

<body onload="brython(1)">
<script type="text/python">
from browser import document

document <= "Hello"
</script>
</body>

</html>

To create client-side web apps that run in the browser, you'll have to learn Brython's API for interacting with the DOM. This is explained in detail in the Brython documentation.

You can also check out this PyCon 2014 talk by Susan Tan, Python in the Browser: Intro to Brython

17 Online Python IDEs and Interactive Shells/REPLs

2022-10-30T12:00:00-04:00

Installing Python is easy, but maybe you're on a smartphone/tablet, are on a library computer that doesn't let you install software, or can't install Python for some other reason. This article has a list of 17 free Python interpreters and interactive shells (also called REPLs) that you can access from a web browser.

There are some downsides to using a browser-based Python interpreter. You won't be able to read or write files with the open() function or make network connections. You might not be allowed to have long-running programs or programs that use a lot of memory. And you won't be able to install third-party modules such as NumPy, Pandas, Requests, PyAutoGUI, or Pygame (though some will have these modules pre-installed.) Some other Python features might be disabled; you'll have to check with them individually. Some of these require you to sign up for a free account. You can use 10 Minute Email to create disposable email accounts if you don't want to deal with spam.

However, you'll still be able to practice writing Python code. The game, simulation, and digital art projects in my book The Big Book of Small Python Projects will still work in these online interpreters. You'll also be able to enter the text-based game projects from Invent Your Own Computer Games with Python and the encryption and code-breaking projects from Cracking Codes with Python.These books are free to read online through a Creative Commons license.

Here's a curated list of browser-based Python interpreters. This isn't a hastily put together clickbait blog post; I've examined each of these and listed them in order of my personal preference.

Python Tutor

https://pythontutor.com/

My favorite browser-based Python file editor is Python Tutor. Python Tutor offers a built-in debugger that lets you execute one line at a time and inspect how the program executes. Not only that, but it also records the state of the program at each step, so you can also step backwards. This is a feature most debuggers don't have.

The Python Tutor site also has Java 8, JavaScript ES6, and C/C++ (with the gcc 9.3 compiler). It also has Python 2.7, TypeScript 1.4, and Ruby 2.2, though these are unsupported. The main downside is that there is a limit to the runtime for your programs (since the programs are run on their servers before returning the output to your browser), however you won't hit this for most learning exercises when you're just starting.

Python Anywhere

https://www.pythonanywhere.com/

PythonAnywhere is one of the most popular browser-based interpreters. You must sign up first, but free accounts are available. You'll be able t to store your Python scripts, or just use their IPython interactive shell without having to log in. Their service allows you to read and write files to a virtual hard drive, and they have many popular Python third-party modules already installed. They have several different Python versions available, and PythonAnywhere is also used for the interactive shell on the Python.org website.

Replit

https://replit.com/

Replit requires you to sign up for a free account to use it. The user interface is a bit complicated, as they have several features including a help system to navigate the site. The site also has online compilers for C, C++, Java, JavaScript, and several other languages.

Replit also has a mobile app for programming on smartphones and tablets.

Futurecoder.io

https://futurecoder.io/

Futurecoder.io looks similar to Code Academy in that it has a curriculum of lessons along with a REPL. However, you can also use the REPL on its own and the site doesn't have ads or require signing up.

Brython

https://brython.info/tests/console.html?lang=en

Brython is Python that you can run in your browser the way web browsers run JavaScript. The normal client-side things you can do in a web page with JavaScript can be done with Brython. This means you can run programs without limits on memory or runtime since they'll be running on your own computer. The downside is that your browser must first download the 6 megabyte Brython code whenever it loads the web page.

You can avoid this by downloading Brython and running it off of your computer. This way you won't need an internet connection after downloading Brython. First, download Brython-3.11.0.zip from the Brython release page on their GitHub account (or whatever the latest version you see on that page). Unpack the Brython-3.11.0 folder inside the zip. Create a new text file named console.html (or any name with a .html extension you choose) and put the following text into it:

<!doctype html> <html> <head> <script type="text/javascript" src="brython.js"></script> <script type="text/javascript" src="brython_stdlib.js"></script> <style> .codearea { background-color:#000; color:#fff; font-family:'Oxygen Mono', Consolas, 'Liberation Mono', 'DejaVu Sans Mono', monospace; font-size:14px; overflow:auto } </style> </head> <body onload=brython({"debug":1}) > <noscript>Please enable Javascript to view this page correctly</noscript> <textarea id="code" class="codearea" rows="20" cols="100"></textarea> <script type="text/python3"> from interpreter import Interpreter # Start an interactive interpreter in textarea with id "code" Interpreter("code") </script> </body> </html>

When you open this .html file on your computer, you'll have a working Python interactive shell.

Google Colab

https://colab.research.google.com/

Your Google or GMail account can give you access to a Jupyter Notebooks-style REPL with generous memory and runtime limits.

Trinket

https://trinket.io/

Trinket is an education-focused site. You need to sign up for a free account to use it, but their interactive shell also supports Turtle, Matplotlib, and other modules that many online REPLs don't.

Python Fiddle

http://pythonfiddle.com/

Python Fiddle is a bare bones editor that lets you create and run Python scripts. Their user interface is a bit unwieldy, but it is rather straightforward.

Programiz

https://www.programiz.com/python-programming/online-compiler/

Programiz has a simple file editor. It can't write files and the programs have a limited runtime. The website also has compilers for C, C++, Java, C#, JavaScript, and a sandbox for SQL databases and HTML/CSS.

Ideone

https://ideone.com/

Ideaone has a rich editor and supports several programming languages besides Python (even older languages like Pascal, Fortran, Prolog, and Cobol, and esoteric programming languages like Brainfuck and Intercal). There's only the editor that lets you write and run programs (with a 5 second runtime limit), but no interactive shell. I think Ideaone is better if you want to practice in less popular languages, rather than use it on a common basis for Python.

SymPy Live Shell

https://live.sympy.org/

A Jupyter Notebooks-style REPL with a small user interface that is fine for casual examples. It uses JupyterLite to run JupyterLab entirely in your browser rather on their servers.

OnlineGDB

https://www.onlinegdb.com/online_python_interpreter

A decent editor that has a nice user interface without being too overwhelming. The runtime and memory limits seem quite generous too. I'd recommend this one.

W3Schools Python Shell

https://www.w3schools.com/python/python_compiler.asp

W3Schools has a straightforward Python editor with basic syntax highlighting. It has a runtime limit of about 10 seconds, though it doesn't report an error if your program goes over it. It's fine for simple examples.

Python Principles Online Python Interpreter

https://pythonprinciples.com/online-python-interpreter/

A simple file editor, but I had trouble getting it to run anything more than a toy example.

Online Python Beta

https://www.online-python.com/

A simple and straightforward Python editor that runs the code on their back-end. Good for toy examples.

TutorialsPoint

https://www.tutorialspoint.com/execute_python_online.php

A simple and straightforward editor with generous runtime limits.

RexTester

https://rextester.com/l/python3_online_compiler

This looks like a hobbyist project with a minimal editor and 5 second runtime limit. There are compilers for other languages, but the website is hard to navigate.

Portable Python

https://portablepython.com/ (NOT RECOMMENDED

This isn't a browser-based REPL, but rather a .exe file to run Python on Windows without having to install anything. However, the page hasn't been updated since 2013 (and Python 3.2), and the download pages don't use HTTPS. I recommend against using this software due to the possibility of malware.

Visual Studio Code Online

https://vscode.dev/

Visual Studio Code is an Electron app, meaning that it can run as a regular desktop app or a browser-based app. The browser version is a bit limited, and navigating this online IDE has a steeper learning curve than the other online interpreters. Still, if you're willing to dive into it or already have experience with Visual Studio Code, you can use this browser-based version.

SoloLearn

https://code.sololearn.com/#py

SolorLearn has an editor (but not a REPL) for over a dozen languages including Python. Use the "Online Compiler" menu item at the top of the page. However, any inputs have to be specified in advanced, so you can't really use it to make interactive programs such as games. I don't really recommend it.

PixelPad

https://pixelpad.io/

PixelPad doesn't have a REPL but does have an editor along with a few example games. However, when I noticed that you can't call time.sleep() so I get the feeling that you'll very quickly bump into walls when you try to do more than it's set of tutorials tells you. I don't really recommend it.

Computer Science Circles

https://cscircles.cemc.uwaterloo.ca/console/

A simple file editor with no REPL. However, the UI is awkward to use and you have to specify all inputs in advanced. I don't recommend it.

Reeborg's World

http://reeborg.ca/reeborg.html

A turtle-like, grid-based world where you move robots around in your browser using their Python library. This might be good for a beginner programmer to learn coding concepts, but it's not set up to run Python code in general.

61A Code

https://code.cs61a.org/

I couldn't get this to actually run a simple Hello, World program. I don't recommend it.

Edited Feb 5, 2023 to add Futurecoder.io, SoloLearn, PixelPad, Computer Science Circles, Reeborg's World, and 61A Code.

How Computers Store Data with Binary Numbers

2022-10-29T12:00:00-04:00

Programming and hacking in movies often involves streams of ones and zeros flowing across the screen. This looks mysterious and impressive, but what do these ones and zeros actually mean? You're probably aware that binary numbers (numbers written using only the two digits, zero and one) have something to do with computers but don't know why.

The answer is economics: binary is the simplest number system and it can be implemented with relatively inexpensive components for computer hardware. Binary, also called the base-2 number system, can represent all of the same numbers that our more familiar base-10 decimal number system can. Decimal has ten digits, 0 through 9. The following table shows the first 24 numbers in decimal and binary:

Decimal	Binary	Decimal	Binary
0	0	12	1100
1	1	13	1101
2	10	14	1110
3	11	15	1111
4	100	16	10000
5	101	17	10001
6	110	18	10010
7	111	19	10011
8	1000	20	10100
9	1001	21	10101
10	1010	22	10110
11	1011	23	10111

Think of the number systems as a mechanical odometer: when you reach the last digit, it resets back to zero while incrementing the next digit. In decimal the last digit is 9 and in binary the last digit is 1. The decimal number after 9 is 10 and the decimal number after 999 is 1000. Similarly, the binary number after 1 is 10 and the binary number after 111 is 1000. Although "10" in binary doesn't mean the same quantity as "ten" in decimal, but rather two. And "1000" in binary doesn't mean the same quantity as "one thousand" in decimal, but rather eight. You can view an interactive binary and decimal odometer at https://inventwithpython.com/odometer

Representing binary numbers with computer hardware is simpler than decimal because there are only two states to represent. For example, spinning-disc hard drives have microscopic spots that can be magnetized or not magnetized. Blu-Ray discs and DVDs have smooth "lands" and indented "pits" etched on the surface of the disk that will or won't reflect the disc player's laser, respectively. Circuits can have electric current flowing through them or no electric current. Even the spaces on paper punch cards for mid-20th century computers have a hole punched in them or no hole. These various hardware standards all have ways of representing two different states. On the other hand, it'd be expensive to create high-quality electronic components that are sensitive enough to detect the difference between ten different voltage levels with reliable accuracy. It's more economical to use simple components, and two binary states is as simple as you can get.

These binary digits are called bits for short. A single bit can represent two numbers, and eight bits (or one byte) can represent 2^8 or 256 numbers. This ranges from 0 to 255 in decimal and 0 to 11111111 in binary. This is similar to how a single decimal digit can represent ten numbers (0 to 9), an eight-digit decimal number can represent 10^8 or one hundred million numbers. Files on your computer are measured in how many bytes they take up:

A kilobyte is 2^10 or 1,024 bytes.
A megabyte is 2^20 or 1,048,576 bytes.
A gigabyte is 2^30 or 1,073,741,824 bytes.

The text of Shakespeare's Romeo and Juliet is about 135 kilobytes. A high-resolution photo is about 2 to 5 megabytes. A two-hour movie can be anywhere from 1 to 50 gigabytes depending on picture quality. Hard drive manufacturers and internet service providers will often use kilobyte, megabyte, and gigabyte to mean a flat one thousand, one million, or one billion because it allows them to overexaggerate how much capacity they provide. The reason corporations can blatantly lie about their numbers this way is because that's how the world works.

Once there is a way to represent binary numbers, you can represent numbers in any number system. You don't need to know the math behind converting from base-2 to base-10 and vice versa to write Python scripts that automate boring stuff. Python has functions to perform this math for you: calling bin(42) returns the string '0b101010'. The '0b' prefix is a convention for marking the number as in binary, instead of meaning "one hundred one thousand ten" in decimal. Meanwhile, calling int('101010', 2) converts binary-to-decimal and returns the integer 42. The 2 argument tells the int() function that '101010' is a base-2 binary number.

The ones and zeros of binary can not only represent any integer but also any form of data. Text can be stored on computers as binary numbers by assigning each letter, punctuation mark, or symbol a unique number. One early such scheme for this was ASCII, the American Symbolic Code for Information-Interchange. In ASCII, a capital letter "A" is represent by the number 65 (or 1000001 in binary), a "?" question mark is represented by the number 63, and the numeral 7 is represented by the number 55. The string 'Hello' is stored as the numbers 72, 101, 108, 108, and 111. When combined one after the other, this appears as a stream of binary: 10010001100101110110011011001101111.

Wow! Just like in those hacker movies!

However, these don't make sense without knowing how many digits are in each number. Representing 'Hello' in decimal as 72101108108111 is confusing because you wouldn't know if the first letter was represented by 7, 72, or 721. We can solve this by always using three digits for each letter and adding the leading zeros where needed: 72 becomes 072. The fifteen digits of 072101108108111 can be evenly split up into five groups of three digits each to represent the five letters. The same can be done in binary, where one byte (or eight bits) represents each letter. With the leading zeros, 'Hello' becomes 0100100001100101011011000110110001101111, as shown in this figure:

Large numbers can be tedious to write in binary, so programmers often view binary information in base-16 or hexadecimal. The numerals of hexadecimal (or simple, hex) range from 0 to 9, and then continue with the first six letters A to F like in the following table:

Decimal	Hexadecimal	Binary	Decimal	Hexadecimal	Binary
0	0	0	12	C	1100
1	1	1	13	D	1101
2	2	10	14	E	1110
3	3	11	15	F	1111
4	4	100	16	10	10000
5	5	101	17	11	10001
6	6	110	18	12	10010
7	7	111	19	13	10011
8	8	1000	20	14	10100
9	9	1001	21	15	10101
10	A	1010	22	16	10110
11	B	1011	23	17	10111

The single hex digit A represents the number ten, B represents eleven, and so on up to F, which represents 15. After this, we add another hexadecimal digit: the hexadecimal number 10 represents decimal 16. Python's hex() and int() functions convert between decimal and hexadecimal. Enter the following into the interactive shell:

>>> hex(42)  # Convert decimal to hex
'0x2a'
>>> int('0x2a', 16)  # Convert hex to decimal
42
>>> int('0x2A', 16)  # Convert hex to decimal
42
>>> int('2A', 16)  # Convert hex to decimal
42

The hex() function returns strings with a '0x' prefix to mark it as a hexadecimal number. The 16 argument tells the int() function that '2a' is written in base-16 hexadecimal.

The 'Hello' string can be shown in 40 binary digits, 0100100001100101011011000110110001101111, or more compactly with 10 hexadecimal digits, 48656c6c6f. This form is more convenient for programmers to read, and software called hex editors can display the binary data of a file this way.

ASCII was developed before the internet made international communication commonplace. It doesn't have numbers reserved for, say, Chinese characters. It's not just an encoding for English, but American English: the number 36 for the "$" dollar sign but no number for the British pound symbol. These issues were solved with Unicode Standard. Specifically, the UTF-8 encoding of the Unicode Standard uses one to four bytes to represent any possible character. UTF-8 is also backwards compatible with ASCII: 65 is a capital A in ASCII and UTF-8.

Python's ord() function takes a single-character string and returns the integer of its assigned Unicode code point. Python's chr() function does the opposite, taking an integer and return a single-character string of that number's assigned Unicode character. In this way, all text can be represented as numbers, and all numbers can be stored on computer hardware in binary form.

Engineers need to invent a way to encode each form of data as numbers. Photos and image are broken up into a two-dimensional grid of colored squares called pixels. Each pixel can use three bytes to represent how much red, green, and blue its color contains. Chapter 19 of Automate the Boring Stuff with Python covers image data in more detail. But for a short example, the numbers 255, 0, and 255 could represent a pixel with the maximum amount of red and blue but no green, resulting in a purple pixel.

Sound is made up of waves of compressed air that reach our ears, which our brains interpret as audio sensation. We can graph the intensity and frequency of these waves over time. The numbers of this graph can then be converted to binary numbers and stored on a computer, which can later control speakers to reproduce the sound. This is a simplification, but this is how binary numbers are stored in audio files such MP3s.

The data for several images combines with audio data to store videos. All forms of information can be encoded into numbers, converted into binary numbers, and then stored on computer hardware. There is, of course, a great deal more to it than this, but this is how ones and zeros represent the wide variety of data in our information age.

Is Python Compiled or Interpreted?

2022-10-10T12:00:00-04:00

The short answer is: Python is interpreted.

There is no separate compile step after writing Python code and before running the .py file.

The Python interpreter software you download from python.org is called CPython because it's written in C.

Python can be compiled into a binary executable with a tool like Py2Exe (on Windows), py2app (on macOS), or BeeWare (all OSes including mobile).

Funny enough, there's also PyPy, a Python interpreter written in Python.

When you run a Python program, the interpreter first compiles it to bytecode and then runs the bytecode. So you could say that Python is compiled.

Bytecode is a set of basic instructions that virtual machine (VM) software runs just like machine code is a set of basic instructions that a CPU runs.

The benefit of bytecode is that interpreter VMs on different operating systems can run the same programs. (Though operating systems were originally written to run the same programs on different computer hardware.)

Python is technically not compiled nor interpreted, because Python is a language and you can write an interpreter or a compiler for any language.

Still, most languages are considered either "compiled" or "interpreted" because they are most commonly implemented with a compiler or interpreter. In this sense, C++ is compiled and Python is interpreted.

A programming language that is interpreted is often called a scripting language, but Java interprets bytecode and isn't considered a scripting language.

A high-level language used to be any language with an abstraction layer over machine code or assembly. C used to be considered a high-level language, but is now considered a low-level or bare-metal language because it is less abstract than languages like Java, Python, or JavaScript.

Transpilers compile source code in one programming language into source code in another programming language. TypeScript is a popular transpiler that compiles source code written in the TypeScript language (which adds type safety features) into JavaScript source code so that it can be run by the JavaScript interpreter in web browsers.

There's also Just-In-Time (JIT) compilation, where a bytecode interpreter analyzes which parts of the program run the most frequently and then compiles those parts to machine code for faster execution.

Java code is compiled by the Java compiler. But it compiles to bytecode, which is interpreted by the Java VM. Still, Java is considered a compiled language rather than an interpreted language or scripting language.

As software developers add more layers of abstraction, these definitions become looser and more ambiguous. It's probably not worth it to spend time arguing over them.

If you'd like to learn how compilers work, I'd recommend first learning recursion by reading my free book The Recursive Book of Recursion and then taking a compilers course such as Dr. Aiken's online compilers course.

How to Run Pip From The Python Interactive Shell

2022-08-25T12:00:00-04:00

UPDATE March 22, 2023: I now recommend using the one-liner import pip; pip.main(['install', 'MODULE_NAME_HERE']) module to install modules from the interactive shell rather than the instructions in this blog post. This code is easier to remember and works on Python versions 2.7 and 3.5+. The only downside is that it doesn't work on Python 3.4, in which case, use the instructions below. Here in 2023, however, the number of students working from 3.4 is near nonexistent so this is unlikely to be an issue.

Installing Python modules with the pip tool is surprisingly hard to describe to beginners learning to code. There are several potential issues: multiple Python installations, virtual environments, PATH environment variable settings. You have to introduce command-line terminals and file system navigation, and the differences between Windows and Mac/Linux. However, there is a line of code you can run from the interactive shell to handle all this for you: import pip; pip.main(['install', 'MODULE_NAME_HERE'])

Alternatively, you can run the following code from the interactive shell (that is, the thing with the >>> prompt):

import sys, subprocess; subprocess.run([sys.executable, '-m', 'pip', 'install', '--user', 'MODULE_NAME_HERE'])

If you're running the interactive shell from a virtual environment and you get an error like ERROR: Can not perform a '--user' install. User site-packages are not visible in this virtualenv., then remove the --user option:

import sys, subprocess; subprocess.run([sys.executable, '-m', 'pip', 'install', 'MODULE_NAME'])

It's generally not advisable to run code that some website tells you to without understanding what it does, so let's break down each section.

import sys, subprocess;

This imports the sys and subprocess built-in modules so that we can access the sys.executable variable and subprocess.run() function. These modules are in Python's standard library, so they are always already installed with Python.

The semicolon makes Python consider it the "end of the line" so that we can fit two Python instructions on the same line.

subprocess.run(

This function call simulates running a command from the Terminal or Command Prompt window, except it's now done from Python code.

sys.executable,

The sys.executable variable contains the file path of the Python interpreter that is currently running the interactive shell. This is especially useful if you have multiple Python installations or virtual environments and want to run the current Python interpreter you are using.

'-m', 'pip', 'install', 'MODULE_NAME'])

When you run the Python interpreter with the -m option, you are running a module (in our case, the standard pip module) as a script. Running python -m pip is the same thing as running the pip tool itself. The 'install', 'MODULE_NAME' options tells pip to download and install a module from the online Python Packaging Index. Your computer needs to be connected to the internet when you run these instructions.

After running these instructions, you should see the output from pip in the window. For example, when I installed the pyrect module the interactive shell looked like this:

>>> import sys, subprocess; subprocess.run([sys.executable, '-m', 'pip', 'install', 'pyrect'])
Collecting pyrect
  Using cached PyRect-0.2.0.tar.gz (17 kB)
  Preparing metadata (setup.py) ... done
Building wheels for collected packages: pyrect
  Building wheel for pyrect (setup.py) ... done
  Created wheel for pyrect: filename=PyRect-0.2.0-py2.py3-none-any.whl size=11196 sha256=5b7fb5f14167a70c955fff3bb14eecfa557f07747f27a03b5c63834173a58f49
  Stored in directory: c:\users\al\appdata\local\pip\cache\wheels\25\80\fa\27bb4a1c2e21f64ec71390489d52e57b7cc8afbe79bd595c5e
Successfully built pyrect
Installing collected packages: pyrect
Successfully installed pyrect-0.2.0
CompletedProcess(args=['C:\\Users\\Al\\.virtualenvs\\deleteme-NM1HlCaN\\Scripts\\python.exe', '-m', 'pip', 'install', 'pyrect'], returncode=0)

To verify that the module installed correctly, run import MODULE_NAME. If no error message appears, the module has been successfully installed.

If you're teaching a Python class or running a Python workshop, using this Python code is a great way to avoid confusion when you need them to install a third-party module from PyPI. If you want to go into more detail about the command-line, environment variables, and similar topics, you can read Chapter 2 of my free book, Beyond the Basic Stuff with Python.

Introducing Humre: Human-Readable Regular Expressions

2022-08-23T12:00:00-04:00

Regular expressions (aka regexes) are a mini-language to specify a pattern of text to look for. However, regex syntax is composed of various punctuation marks that can be hard to remember. Humre is a Python module that gives a more human-readable syntax that works better with code editing tools. You can install Humre just like any other Python module with pip install humre and the full documentation is available in the git repo's README file.

For example, if you want to find an American phone number, you can use the regex string r'\d{3}-\d{3}-\d{4}' (the r makes it a raw string that automatically escapes the backslashes) to search for a 3 numeric digit characters for the area code (the \d{3}), then a dash (the -), followed by three digits, a dash, and four digits. But r'\d{3}-\d{3}-\d{4}' is not an intuitive way to convey this. Humre fixes this by providing functions and constants with readable names. The equivalent Humre code for an American phone number is:

exactly(3, DIGIT) + '-' + exactly(3, DIGIT) + '-' exactly(4, DIGIT)

Humre's constants are strings and Humre's functions return strings, so the above expression evaluates to the same string: r'\d{3}-\d{3}-\d{4}'

Consider this regex code using Python's re module for an American phone number with optional parentheses around the area code:

>>> import re
>>> regexStr = r'(\d{3})|(\(\d{3}\))-\d{3}-\d{4}'
>>> patternObj = re.compile(regexStr)
>>> patternObj.search('My number is (415)-555-5555.')
<re.Match object; span=(13, 27), match='(415)-555-5555'>

The regex string is hard to read, especially with those escaped parentheses mixed in with the

>>> from humre import *
>>> regexStr = either(group(exactly(3, DIGIT)), group(OPEN_PAREN, exactly(3, DIGIT), CLOSE_PAREN)) + '-' + exactly(3, DIGIT) + '-' + exactly(4, DIGIT)
>>> regexStr
'(\\d{3})|(\\(\\d{3}\\))-\\d{3}-\\d{4}'
>>> patternObj = compile(regexStr)
>>> patternObj.search('My number is (415)-555-5555.')
<re.Match object; span=(13, 27), match='(415)-555-5555'>

The Humre code produces the same regex string except using more readable code. Humre is not a reimplementation of a regular expression engine; it's a wrapper that adds readable names to standard regex syntax.

Python's re module has "verbose mode" which allows you to use multiline strings with comments. This can make your regex strings easier to read, but they are still strings and won't benefit from advanced features your IDE provides, such as:

Your editor's parentheses matching works.
Your editor's syntax highlight works.
Your editor's linter and type hints tool picks up typos.
Your editor's autocomplete works.
Auto-formatter tools like Black can automatically format your regex code.
Humre handles raw strings/string escaping for you.
You can put actual Python comments alongside your Humre code.
Better error messages for invalid regexes.

The README on Humre's git repository has full documentation, but here's a general introduction. I still recommend all programmers learn standard regex syntax, as you'll need that knowledge to read other people's (non-Humre) code and diagnose any bugs you accidentally write with the Humre module.

Creating Basic Regex Strings with Humre

Humre functions return strings, so that instead of remembering the regex syntax for matching between 3 and 5 letter X's with 'X{3,5}', you can write the code between(3, 5, 'X'). To avoid having to prefix humre. in front of every function call, I recommend importing the Humre module with from humre import *.

Because Humre functions take string arguments and return strings, you can compose them together. For example, if you want to put the 3-to-5-letter-Xs inside of a regex group, you can write group(between(3, 5, 'X')).

Humre functions also accept a variable number of string arguments and concatenates them together for your convenience. The code group('Z', between(3, 5, 'X')) adds a letter Z to the start of the group, and this is equivalent to the code group('Z' + between(3, 5, 'X')).

The exception to this is the either() function, which is used for the regex alternation pipe character '|'. If you wanted to match "cat" or "dog" with the regex 'cat|dog', you would need to call Humre's either('cat', 'dog') function. The two string arguments are not concatenated together for either().

Humre also provides constants for common regex strings, such as DIGIT for r'\d' and OPEN_PAREN for r'\('. These manage escaping for you.

A full list of Humre functions and constants is available in the README documentation.

Experimenting with what strings Humre returns is easy to do in the interactive shell if you want to explore what Humre is doing:

>>> from humre import *
>>> exactly(3, 'X')
'X{3}'
>>> >>> zero_or_more('X')
'X*'
>>>
>>> group(DIGIT)
'(\\d)'
>>> group(either(exactly(3, DIGIT), 'cat'))
'(\\d{3}|cat)'
>>> either(exactly(3, DIGIT), group('cat'))
'\\d{3}|(cat)'

Humre's Convenience Functions

You don't need to keep typing out quotes and + operators to join strings. Humre's join() function offers an easier way to join strings together. The following humre.join() function and ''.join() method calls are equivalent:

>>> ''.join(['Hello', 'World'])
'HelloWorld'
>>> from humre import *
>>> join('Hello', 'World')
'HelloWorld'

Humre also provides a compile() function which wraps the standard re.compile() function. This is so that you don't need to mix your Humre and re code. The following code produces equivalent pattern objects:

>>> import re
>>> re.compile(r'\d{3}')
re.compile('\\d{3}')
>>> from humre import *
>>> compile(exactly(3, DIGIT))
re.compile('\\d{3}')

Because Humre functions concatenate multiple string arguments together, if you want to pass regex flags (such as re.IGNORECASE) you need to use humre.compile()'s flags keyword argument instead. The following code produces equivalent pattern objects:

>>> import re
>>> re.compile('Hello', re.IGNORECASE)
re.compile('Hello', re.IGNORECASE)
>>> from humre import *
>>> compile('Hello', flags=re.IGNORECASE)
re.compile('Hello', re.IGNORECASE)

Note that this means running from humre import * overwrites Python's built-in compile() function. However, most applications don't call this function. If yours does, you can import Humre with import humre or import individual Humre functions and constants instead.

Human-Readable Error Messages

Typos in your Humre code give much better error messages than the standard re module does. For example, if you make a typo and ask for between 5 and 3 occurrences of the letter X (instead of between 3 and 5), the re module produces this unwieldy error:

>>> import re
>>> re.compile('X{5,3}')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Users\Al\AppData\Local\Programs\Python\Python311\Lib\re\__init__.py", line 227, in compile
    return _compile(pattern, flags)
           ^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\Al\AppData\Local\Programs\Python\Python311\Lib\re\__init__.py", line 294, in _compile
    p = _compiler.compile(pattern, flags)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\Al\AppData\Local\Programs\Python\Python311\Lib\re\_compiler.py", line 743, in compile
    p = _parser.parse(p, flags)
        ^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\Al\AppData\Local\Programs\Python\Python311\Lib\re\_parser.py", line 980, in parse
    p = _parse_sub(source, state, flags & SRE_FLAG_VERBOSE, 0)
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\Al\AppData\Local\Programs\Python\Python311\Lib\re\_parser.py", line 455, in _parse_sub
    itemsappend(_parse(source, state, verbose, nested + 1,
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\Al\AppData\Local\Programs\Python\Python311\Lib\re\_parser.py", line 672, in _parse
    raise source.error("min repeat greater than max repeat",
re.error: min repeat greater than max repeat at position 2

That's quite a lot of text to read through. The same mistake in Humre provides a more direct, detailed error message:

>>> from humre import *
>>> between(5, 3, 'X')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "c:\github\humre\src\humre\__init__.py", line 439, in between
    raise ValueError('minimum argument ' + str(minimum) + ' must be less than maximum argument ' + str(maximum))
ValueError: minimum argument 5 must be less than maximum argument 3

Unicode Letter Support

It's common to write [A-Za-z] for a character class to match all letters, but this suffers from the problem of not matching letters with accent marks or non-English letters. Humre's LETTER character class looks like '[A-Za-zªµºÀ-ÖØ-öø-ˁˆ-ˑˠ-ˤˬˮͰ-ʹͶ-ͷͺ-ͽͿΆΈ-ΊΌΎ-Ρ... and matches all letters. The definition of "letter" in this case is based on Python's isalpha() string method.

Massive Regexes Are Easier with Humre

The benefits of Humre compound as your regular expressions get larger. Let's compare a massive regex used in Python packaging code to its equivalent Humre code.

Here's the massive regular expression in verbose mode:

_version_regex_str = r"""
(?P<version>
    (?:
        # The identity operators allow for an escape hatch that will
        # do an exact string match of the version you wish to install.
        # This will not be parsed by PEP 440 and we cannot determine
        # any semantic meaning from it. This operator is discouraged
        # but included entirely as an escape hatch.
        (?<====)  # Only match for the identity operator
        \s*
        [^\s]*    # We just match everything, except for whitespace
                  # since we are only testing for strict identity.
    )
    |
    (?:
        # The (non)equality operators allow for wild card and local
        # versions to be specified so we have to define these two
        # operators separately to enable that.
        (?<===|!=)            # Only match for equals and not equals
        \s*
        v?
        (?:[0-9]+!)?          # epoch
        [0-9]+(?:\.[0-9]+)*   # release
        (?:                   # pre release
            [-_\.]?
            (a|b|c|rc|alpha|beta|pre|preview)
            [-_\.]?
            [0-9]*
        )?
        (?:                   # post release
            (?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*)
        )?
        # You cannot use a wild card and a dev or local version
        # together so group them with a | and make them optional.
        (?:
            \.\*  # Wild card syntax of .*
            |
            (?:[-_\.]?dev[-_\.]?[0-9]*)?         # dev release
            (?:\+[a-z0-9]+(?:[-_\.][a-z0-9]+)*)? # local
        )?
    )
    |
    (?:
        # The compatible operator requires at least two digits in the
        # release segment.
        (?<=~=)               # Only match for the compatible operator
        \s*
        v?
        (?:[0-9]+!)?          # epoch
        [0-9]+(?:\.[0-9]+)+   # release  (We have a + instead of a *)
        (?:                   # pre release
            [-_\.]?
            (a|b|c|rc|alpha|beta|pre|preview)
            [-_\.]?
            [0-9]*
        )?
        (?:                                   # post release
            (?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*)
        )?
        (?:[-_\.]?dev[-_\.]?[0-9]*)?          # dev release
    )
    |
    (?:
        # All other operators only allow a sub set of what the
        # (non)equality operators do. Specifically they do not allow
        # local versions to be specified nor do they allow the prefix
        # matching wild cards.
        (?<!==|!=|~=)         # We have special cases for these
                              # operators so we want to make sure they
                              # don't match here.
        \s*
        v?
        (?:[0-9]+!)?          # epoch
        [0-9]+(?:\.[0-9]+)*   # release
        (?:                   # pre release
            [-_\.]?
            (a|b|c|rc|alpha|beta|pre|preview)
            [-_\.]?
            [0-9]*
        )?
        (?:                                   # post release
            (?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*)
        )?
        (?:[-_\.]?dev[-_\.]?[0-9]*)?          # dev release
    )
)
"""

And here's the equivalent code with Humre:

from humre import *

SEPARATOR = chars('-_' + PERIOD)
OPT_SEPARATOR = optional(SEPARATOR)

def version_template(fn):
    return ''.join([
    zero_or_more(WHITESPACE),
    optional('v'),
    optional(noncap_group(one_or_more(chars('0-9')), '!')), # epoch

one_or_more(chars('0-9')), fn(noncap_group(PERIOD, one_or_more(chars('0-9')))), # release

optional(noncap_group( # pre release
        OPT_SEPARATOR,
        group(either('a', 'b', 'c', 'rc', 'alpha', 'beta', 'pre', 'preview')),
        OPT_SEPARATOR,
        zero_or_more(chars('0-9')),
    )),
    optional(noncap_group( # post release
        either(
            noncap_group('-', one_or_more(chars('0-9'))),
            noncap_group(OPT_SEPARATOR, group_either('post', 'rev', 'r') + OPT_SEPARATOR + zero_or_more(chars('0-9')))
        )
    ))
])

EQ_NE_VERSION_TEMPLATE = version_template(zero_or_more)
COMPATIBILITY_VERSION_TEMPLATE = version_template(one_or_more)

DEV_RELEASE = optional(noncap_group(OPT_SEPARATOR, 'dev', OPT_SEPARATOR, zero_or_more(chars('0-9'))))  # dev release

_version_regex_str = named_group('version',
    either(
        noncap_group(
            # The identity operators allow for an escape hatch that will
            # do an exact string match of the version you wish to install.
            # This will not be parsed by PEP 440 and we cannot determine
            # any semantic meaning from it. This operator is discouraged
            # but included entirely as an escape hatch.
            positive_lookbehind('==='), # Only match for the identity operator
            zero_or_more(WHITESPACE),
            zero_or_more(nonchars(WHITESPACE)) # We just match everything, except for whitespace
                                               # since we are only testing for strict identity.
        ),
        noncap_group(
            # The (non)equality operators allow for wild card and local
            # versions to be specified so we have to define these two
            # operators separately to enable that.
            positive_lookbehind(either('==', '!=')), # Only match for equals and not equals

EQ_NE_VERSION_TEMPLATE,

# You cannot use a wild card and a dev or local version
            # together so group them with a | and make them optional.
            optional(noncap_group(
                either(
                    PERIOD + ASTERISK, # Wild card syntax of .*
                    DEV_RELEASE +
                    optional(noncap_group(PLUS, one_or_more(chars('a-z0-9')), zero_or_more(noncap_group(SEPARATOR, one_or_more(chars('a-z0-9')))))) # local
                )
            ))
        ),
        noncap_group(
            # The compatible operator requires at least two digits in the
            # release segment.
            positive_lookbehind('~='), # Only match for the compatible operator

COMPATIBILITY_VERSION_TEMPLATE,

DEV_RELEASE,
        ),
        noncap_group(
            # All other operators only allow a sub set of what the
            # (non)equality operators do. Specifically they do not allow
            # local versions to be specified nor do they allow the prefix
            # matching wild cards.
            negative_lookbehind(either('==', '!=', '~=')), # We have special cases for these
                                                           # operators so we want to make sure they
                                                           # don't match here.
            EQ_NE_VERSION_TEMPLATE,

DEV_RELEASE,
        )
    )
)

print(_version_regex_str)

While both are a lot to take in, the Humre code benefits from not being in a multiline string. This means your IDE can match parentheses, your linter can spot typos, and your automatic code formatting tools can clean up your Humre code for you.

Full Documentation

This is a broad introduction to Humre. The full documentation is available in the git repo's README file.

Which Al Sweigart Python Books Should I Start Reading?

2022-08-22T12:00:00-04:00

I've been writing programming books for beginners since 2009. All of them are free to read online at InventWithPython.com Many people email me asking which of my books they should read, so I wrote this guide to help beginners get started with my free learning materials.

"I am interested in coding and I just want to get started learning to code."
"I like playing or want to make video games."
"I'm interested in hacking and cybersecurity."
"I'm a beginner but not a complete beginner and I'm tired of doing the same "Hello, world" tutorials."
"I love Minecraft and want to get into coding."
"I want to get my kids into programming."
"I'm super ambitious about learning to code and I want to read all of your books! What order should I read them?"
"What are your books for complete beginners?"

Before I dive into the details, another common question about learning to program is "What programming language should I learn?" The answer is almost every case is Python. Python has a gentle learning curve, readable syntax, but is also a serious language used by professionals. Many people say it doesn't matter which language you start with, and they are sort of right. Picking another language to learn as your first programming language isn't a "wrong" choice, but Python is so versatile and free of common speed bumps in other languages that I strongly recommend it.

"I am interested in coding and I just want to get started learning to code."

Automate the Boring Stuff with Python, 2nd Edition (read free online, buy print book) is my most popular programming book. The first half covers the basics of programming and the Python langauge, while the second half goes into software modules that help you with practical tasks such as updating Excel spreadsheets, sending text and email notifications, extracting text from PDFs, scraping data from web sites, and many other tasks. This book skips the technical details of computer science and algorithms and focuses on getting you to write practical programs to automate boring tasks on your computer.

It's also a good general programming guide for complete beginners.

Automate the Boring Stuff with Python is free to read on my website AutomateTheBoringStuff.com. This book is ideal for:

Adults and teens who want to learn to code.
Hobbyists, office workers, academic researchers, and administrators, who use a computer as part of their job.
People who find themselves buried in spreadsheets and PDFs as part of their job.
Adults interested in changing careers to software engineering but want a small taste to start.

I've also created a 50-video Udemy course that follows most of the content in this book. The first 15 videos are free to watch on YouTube.

After finishing Automate, I recommend moving on to Beyond the Basic Stuff with Python or reading Eric Matthes' Python Crash Course.

"I like playing or want to make video games."

Invent Your Own Computer Games with Python (read free online, buy print book) is for complete beginners and teaches programming by making simple text-based games (and, at the end, graphical games with the Pygame software library). Making Games with Python & Pygame (read free online, buy print book) follows up with the source code to several graphical games such as Tetris and Snake and Connect Four. The Big Book of Small Python Projects (read free online, buy print book) follows up with 81 text-based game, simulation, and animation projects.

The game projects in these books aren't like modern video games with 3D graphics, but the simplified video games are fun projects while you learn the basics of programming.

These books are ideal for:

Complete beginners who want to learn to program using fun video game projects.
People looking for small programming project ideas.
People who want to learn the Pygame 2D graphical game library.

"I'm interested in hacking and cybersecurity."

Cracking Codes with Python (read free online, buy print book) covers classic ciphers and how to break them cryptanalysis techniques. You'll learn to write Python programs that implement various ciphers (Caesar cipher, transposition cipher, Vigenere cipher, the RSA algorithm, and more) and also write programs that can crack these codes.

This book is good for:

People new to hacking and cybersecurity.
People who want to get better at math and programming as part of their tech career.
Beginner cryptographers.
People who don't want a cybersecurity career, but want to learn Python and are intrigued by ciphers.

"I'm a beginner but not a complete beginner and I'm tired of doing the same "Hello, world" tutorials."

Some people say that to improve your coding skills, you should read the source code for open source projects. I disagree with this advice: open source code might not be well documented, could use advanced techniques, and is generally a "drinking from a fire hose" way to learn more about coding. I wrote The Big Book of Small Python Projects (read free online, buy print book) to include the source code to projects that are short and simple, but still offer an example of how programming concepts are applied to actual programs.

Beyond the Basic Stuff with Python (read free online, buy print book) covers some intermediate and advanced Python techniques, but also general best practices when it comes to software development such as how to write functions, how to name variables, programming jargon, and source control using Git and GitHub.

These books are ideal for:

People who feel "stuck" doing beginner tutorials they already understand but find advanced tutorials too difficult.
People who want ideas for small programming projects to work on.
People looking for the next step in learning to code with Python.

"I love Minecraft and want to get into coding."

Coding with Minecraft (read free online, buy print book) teaches you how to program using the ComputerCraft mod for Minecraft. ComputerCraft adds programmable robots to your Minecraft world, and you can program to mine, build, farm, craft, solve mazes, and more. ComputerCraft uses the Lua scripting language rather than Python.

This book is ideal for:

Kids (and parents) who like Minecraft and want to get into programming.
Teachers or instructors who run after school coding clubs.

Also check out Programming with Minecraft.

"I want to get my kids into programming."

Scratch 3 Programming Playground (read free online, buy print copy) cover's the Scratch programming environment tool. Scratch is a free, graphical programming environment from MIT. It teaches 8- to 16-year-olds programming by snapping code blocks together to form complete programs. You can learn more about what Scratch is and read information for parents.

Also check out Coding with Minecraft (read free online, buy print book).

I also have a free Udemy course that covers Scratch, although as of 2022 it still covers version 2 of the Scratch editor instead of the current version 3.

"I'm super ambitious about learning to code and I want to read all of your books! What order should I read them?"

If you want to read all of these books, here's the order to tackle them:

Automate the Boring Stuff with Python for basic programming concepts.
Invent Your Own Computer Games with Python for detailed tutorials for making game projects.
The Big Book of Small Python Projects for experience creating a wide variety of programming projects.
(Optionally) Making Games with Python & Pygame if you want to continue making games.
(Optionally) Cracking Codes with Python if you want to learn Python for cipher projects.
Beyond the Basic Stuff with Python to learn intermediate and advanced software development skills.
The Recursive Book of Recursion to learn computer science by exploring recursive programming techniques.

"What are your books for complete beginners?"

To recap, here are my books for those with no programming experience:

There are more free resources than ever to learn to code. Good luck on your programming journey!

New Book: The Recursive Book of Recursion by Al Sweigart

2022-08-09T12:00:00-04:00

My new programming book, the Recursive Book of Recursion, is released in August 2022. The book covers several classic recursive algorithms and breaks down recursion's fearsome reputation as a programming technique. The book has the code for its numerous programs in both Python and JavaScript. When you buy it direct from the publisher, No Starch Press, you'll receive a DRM-free ebook copy with your print book order.

Here's the contents of the book:

Part 1: Understanding Recursion

Chapter 1: What Is Recursion? - Explains recursion and how it is the natural result of the way programming languages implement functions and function

calls. This chapter also argues that recursion isn’t nearly the elegant, mystical concept many claim it is.

Chapter 2: Recursion vs. Iteration - Dives into the differences (and many similarities) between recursive and iterative techniques.

Chapter 3: Classic Recursion Algorithms - Covers famous recursive programs such as the Tower of Hanoi, the flood fill algorithm, and others.

Chapter 4: Backtracking and Tree Traversal Algorithms - Discusses a problem for which recursion is particularly suited: traversing tree data structures, such as when solving mazes and navigating a directory.

Chapter 5: Divide-and-Conquer Algorithms - Discusses how recursion is useful for splitting large problems into smaller subproblems and covers

several common divide-and-conquer algorithms.

Chapter 6: Permutations and Combinations - Covers recursive algorithms involving ordering and matching, as well as the common programming problems to which these techniques are applied.

Chapter 7: Memoization and Dynamic Programming - Explains some simple tricks to improve code efficiency when applying recursion in the real world.

Chapter 8: Tail Call Optimization - Covers tail call optimization, a common technique used to improve the performance of recursive algorithms, and how it works.

Chapter 9: Drawing Fractals - Tours the intriguing art that can be programmatically produced by recursive algorithms. This chapter makes use of turtle graphics for generating its images.

Part 2: Projects

Chapter 10: File Finder - Covers a project that searches through the files on your computer according to custom search parameters you provide.

Chapter 11: Maze Generator - Covers a project that automatically generates mazes of any size using the recursive backtracker algorithm.

Chapter 12: Sliding-Tile Solver - Covers a project that solves sliding-tile puzzles, also called 15-puzzles.

Chapter 13: Fractal Art Maker - Explores a project that can produce custom fractal art of your own design.

Chapter 14: Droste Maker - Explores a project that produces recursive, picture-in-picture images using the Pillow image-manipulation module.

How Many Recursive Cases and Base Cases Does a Recursive Function Need?

2022-03-20T12:00:00-04:00

All recursive functions need at least one recursive case and at least one base case. A recursive case is the set of circumstances where a recursive function calls itself. A base case is the set of circumstances where a recursive function returns without calling itself. Here's a simple recursive factorial function with one base case and one recursive case:

def factorial(n):
    if n == 1:
        # BASE CASE
        return 1
    else:
        # RECURSIVE CASE
        return n * factorial(n - 1)

When you call factorial(5), it returns

If a recursive function has zero recursive cases, it never calls itself and is not a recursive function. The following buggy factorial function has a base case but no recursive case:

def factorialNoRecursiveCase(n):
  if True:
      # BASE CASE
      return 1

When factorialNoRecursiveCase(5) is called, it returns 1. The trouble is, it returns 1 for every argument.

If a recursive function has zero base ases, it never returns and only recurses. This will eventually cause a stack overflow (unless some other . The following buggy factorial function has a recursive case but no base case:

def factorialNoBaseCase(n):
  if True:
      # RECURSIVE CASE
      return n * factorialNoBaseCase(n - 1)

When factorialNoBaseCase(5) is called, it causes a RecursionError: maximum recursion depth exceeded error.

There is one more requirement for a correctly working recursive function: the recursive function calls must eventually get closer to a base case. Otherwise, the base case is never reached and it will be as though no base case exists, causing a stack overflow. The following buggy factorial function has a recursive case and a base case but never reaches the base case:

def factorialNoReachBaseCase(n):
    if n == 1:
        # BASE CASE
        return 1
    else:
        # RECURSIVE CASE
        return n * factorialNoReachBaseCase(n + 1)  # Adds one instead of subtracts one!

When factorialNoReachBaseCase(5) is called, it never reaches the base case and causes a RecursionError: maximum recursion depth exceeded error.

When writing your own recursive functions, you should ask yourself three questions:

What is the base case?
What arguments are passed to the recursive function call?
Does the argument get closer to the base case?

If you'd like to learn more about recursion, check out my book, The Recursive Book of Recursion" from No Starch Press.

Bootstrap 5 Boilerplate Code for New Web Pages

2022-03-11T12:00:00-05:00

Here's the boilerplate that you can copy and paste when creating a new web page with Bootstrap 5.1.3. This comes from the Bootstrap documentation, with some modification to load the icon library as well:

<!doctype html>
<html lang="en">
  <head>
    <!-- Required meta tags -->
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!-- Bootstrap CSS -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-1BmE4kWBq78iYhFldvKuhfTAU6auU8tT94WrHftjDbrCEXSU1oBoqyl2QvZ6jIW3" crossorigin="anonymous">

    <!-- Bootstrap Icon library -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.8.1/font/bootstrap-icons.css" integrity="sha384-He3RckdFB2wffiHOcESa3sf4Ida+ni/fw9SSzAcfY2EPnU1zkK/sLUzw2C5Tyuhj" crossorigin="anonymous">

    <title>TITLE_GOES_HERE</title>
  </head>
  <body>
    <div class="container">
      <div class="row">
        <div class="col">
MAIN_CONTENT_GOES_HERE
        </div>
      </div>
    </div>

    <!-- Bootstrap Bundle with Popper -->
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.3/dist/js/bootstrap.bundle.min.js" integrity="sha384-ka7Sk0Gln4gmtz2MlQnikT1wXgYsOg+OMhuP+IlRH9sENBO0LRn5q+8nbTov4+1p" crossorigin="anonymous"></script>
  </body>
</html>

I created this for my own use whenever I start a new Bootstrap web page. Feel free to edit as needed. I'll also try to update this page as new versions of Bootstrap come out.

Make Fractals in Python Turtle with the FractalArtMaker Module

2022-03-09T12:00:00-05:00

Fractal Art Maker has been upgraded and is now covered in this new blog post.

How to Use Python 3.11's New TOML Parser, tomllib

2022-02-23T12:00:00-05:00

TOML Parser To Be Included In Python 3.11

The Python language steering council has accepted PEP 680, which adds a TOML parser to the Python standard library. This means in Python 3.11, you'll be able to import tomllib and have a module that can parse TOML files.

But what are TOML files and why is a TOML parser being added to Python? This blog explains what TOML files look like, how they're used, and the Python code that lets you parse them.

TOML stands for Tom's Obvious, Minimal Language. It is a way to structure data in a text file, much like what JSON, XML, and YAML files do. The TOML standard is set up so that it's easy for humans to write TOML files in a text editor for use as configuration files. The syntax is very similar to .ini files on Windows. Here's an example TOML file:

# My Dungeons & Dragons character.
name = "Mordnilap"
class = "Magic user"
maxHP = 14
currentHP = 2

inventory = ["apple", "enchanted staff", "healing potion"]

cursed = false

[spells]
# The integers represent how many times a day they can be cast.
fireball = 3
featherFall = 2

TOML files are designed to easily and unambiguously be parsed into a dictionary data structure. With the TOML parser that will be in Python 3.11, you'll be able to parse this text and turn into the following Python dictionary:

{'class': 'Magic user',
 'currentHP': 2,
 'cursed': False,
 'inventory': ['apple', 'enchanted staff', 'healing potion'],
 'maxHP': 14,
 'name': 'Mordnilap',
 'spells': {'featherFall': 2, 'fireball': 3}}

Python already has standard library modules for parsing XML and JSON text (with the xml and json modules, respectively.) There are third-party modules for parsing TOML files, but Python 3.11 will include one in the standard library so that all Python programs can access it without the additional step of installing a third-party TOML parsing module.

As you can see in the example TOML file above, TOML is a great format for structuring data for configuration files. It doesn't have same column-and-row format that an Excel spreadsheet or CSV file would use though.

In Python 3.11, the TOML module will be named tomllib, since a third-party module named toml already exists. The TOML module in 3.11 will be based on the existing toml third-party module.

Writing Python Code with tomllib

You don't have to wait for Python 3.11 to be released to use it today. You can install the third-party toml package with the pip tool by running pip3 install --user toml in a Terminal window on macOS and Linux, or by running pip install --user toml in a Command Prompt window on Windows. (Don't run this from the Python interactive shell; that doesn't work.)

Much like how the json module has functions named load() and loads() (which is pronounced "load s" or "load string", not "loads"), the toml third-party library (and future tomllib module in Python 3.11) has load() and loads() functions.

For example, say we had the Dungeons & Dragons text above in a TOML file named dnd_character.toml. We could read into our Python program with the following code:

import tomllib  # import tomllib in Python 3.11
import pprint

with open('dnd_character.toml') as fileObj:
  content = fileObj.read()
  dnd_char = tomllib.loads(content)
pprint.pprint(dnd_char)

The output of this program from the pprint "pretty print" module is as follows:

{'class': 'Magic user',
 'currentHP': 2,
 'cursed': False,
 'inventory': ['apple', 'enchanted staff', 'healing potion'],
 'maxHP': 14,
 'name': 'Mordnilap',
 'spells': {'featherFall': 2, 'fireball': 3}}

The toml.loads() function takes a string that we pulled out of a text file named dnd_character.toml. This string could have come from anywhere (say, downloading it off the web with the Requests module). But since reading it from a .toml file is so common, the tomllib.load() function can accept the file object directly:

import tomllib  # import tomllib in Python 3.11
import pprint

with open('dnd_character.toml', 'rb') as fileObj:
  dnd_char = tomllib.load(fileObj)
pprint.pprint(dnd_char)

Note that the file object you pass to tomllib.load() has to be open in "read binary" mode, and not just the default "read text" mode, so you need to pass 'rb' as the second argument to the open() function.

Unlike the json module's dumps() function, there is no tomllib.dumps() function that can create text for TOML files. This is because while JSON is meant to be human-readable and read and written by programs, TOML files are meant to be used for configuration files. These files are often read and written by humans, but only read by software. There is a third-party module called toml-w that has a tomli-w.dumps() function for writing TOML-structured text. The dumps() function won't be a part of the tomllib module in the Python 3.11 standard library though.

Writing TOML Files in a Text Editor

We've covered how your Python programs can read in TOML files. But when you write TOML by hand, you'll need to know the syntax of the TOML format. Fortunately, Tom's Obvious, Minimal Language has an obvious, minimal format that's easy to remember. (For full details, you can read the documentation on the TOML website.)

TOML files can have comments which are ignored by parsers. They look like Python comments: beginning with a # and extending to the end of the line. Blank lines are also allowed and ignored in TOML files.

The basic key-value pairs are written like Python assignment statements, with the key and value separated by an equal sign:

name = "Mordnilap"
class = "Magic user"
maxHP = 14
currentHP = 2

The tomllib.loads() function takes the above TOML and returns the following Python dictionary:

{'name': 'Mordnilap', 'class': 'Magic user', 'maxHP': 14, 'currentHP': 2}

TOML has a few standard data types common to most programming languages, such as strings enclosed in single or double quotes (like 'Mordnilap') and integers (like 14).

TOML also has floating point numbers with decimal points (like 3.1415 or -42.0) and lowercase Boolean values true and false. Note that true and false are written differently in TOML than Python's True and False. TOML isn't a Python-specific format, but a general format that can be parsed by many programming languages. In this case, the lowercase true and false is similar to JavaScript and JSON's way of writing Boolean values.

Dates and times are also first-class values in TOML; they have a specific format (detailed in RFC 3339) and you don't need to write them as strings enclosed in quotes. There are a few different ways of writing them. For dat and timestamps that include the time zone, you can use the Z suffix to mean UTC. Or you can specify an offset from UTC:

odt1 = 1979-05-27T07:32:00Z  # UTC time zone
odt2 = 1979-05-27T00:32:00-07:00  # UTC minus 7 hours

The tomllib.loads() function takes the above TOML and returns the following Python dictionary:

{'odt1': datetime.datetime(1979, 5, 27, 7, 32, tzinfo=datetime.timezone.utc),
 'odt2': datetime.datetime(1979, 5, 27, 0, 32, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=61200)))}

You can also have arrays in TOML, such as our example's inventory = ["apple", "enchanted staff", "healing potion"] producing the Python dictionary {"inventory": ["apple", "enchanted staff", "healing potion"]}. Arrays can also include other arrays.

Instead of dictionaries, TOML has tables which can be formed under a square-bracketed table headers:

[Mordnilap]
class = "Magic user"
maxHP = 14
currentHP = 2

[Bilbo]
class = "Fighter"
maxHP = 16
currentHP = 16

The tomllib.loads() function takes the above TOML and returns the following Python dictionary:

{'Bilbo': {'class': 'Fighter', 'currentHP': 16, 'maxHP': 16},
 'Mordnilap': {'class': 'Magic user', 'currentHP': 2, 'maxHP': 14}}

You can also use dotted notation to create these dictionaries. The following TOML produces an identical dictionary to the previous example:

Mordnilap.class = "Magic user"
Mordnilap.maxHP = 14
Mordnilap.currentHP = 2

Bilbo.class = "Fighter"
Bilbo.maxHP = 16
Bilbo.currentHP = 16

But you can also use more compact inline tables in TOML:

Mordnilap = { "class" = "Magic user", "maxHP" = 14, "currentHP" = 2 }
Bilbo = { "class" = "Fighter", "maxHP" = 16, "currentHP" = 16 }

There's several other aspects to the TOML syntax which you can read in the TOML documentation, but I hope this blog post has given you a good introduction to this helpful tool that will be part of the Python standard library as the tomllib module as of version 3.11.

Downloading Web Pages and Files in Python 3 and 2 Without the Requests Module

2022-02-21T12:00:00-05:00

I created a Python module called whatismyip that allows Python programs to easily figure out what their internet protocol (IP) address is. It works by connecting to one of several public websites that return this information, such as https://icanhazip.com/.

Because it was a module to be included in other programs, I wanted it to have as few dependencies as possible. Normally I would use the requests module to download these web pages, but I wanted to stick to just the Python standard library. Here's how I used only the standard library on Python 3 and 2 to download the HTML of a webpage:

import sys

if sys.version_info[0] == 3:  # Python 3
    from urllib.request import Request, urlopen
elif sys.version_info[0] == 2:  # Python 2
    from urllib2 import Request, urlopen

# Supply a user-agent header of a common browser, since some web servers will refuse to reply to scripts without one.
# 'https://ifconfig.me' is a website that returns simple info about your request. Replace this with the page you want to download.
requestObj = Request('https://ifconfig.me/all', headers={'User-agent' : 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:97.0) Gecko/20100101 Firefox/97.0'})
responseObj = urlopen(requestObj)

# To figure out how to decode the downloaded binary data to text, we need to get the character set encoding:
if sys.version_info[0] == 3:  # Python 3
    charsets = responseObj.info().get_charsets()
    if len(charsets) == 0 or charsets[0] is None:
        # Character set encoding could not be determined.
        charset = 'utf-8'  # Use the utf-8 encoding by default.
    else:
        # Use the first character set encoding listed. (It's often the only one.)
        charset = charsets[0]
elif sys.version_info[0] == 2:  # Python 2
    charset = responseObj.headers.getencoding()
    if charset == '7bit':
        # Even though getencoding() returns '7bit', this is an unknown encoding to decode(). '7bit' is the same as 'ascii'
        charset = 'ascii'

content = responseObj.read().decode(charset)
print(content)  # The HTML of the web page.

And here is code for downloading a binary file (such as a .png image or .zip file) from a URL:

import sys

if sys.version_info[0] == 3:  # Python 3
    from urllib.request import Request, urlopen
elif sys.version_info[0] == 2:  # Python 2
    from urllib2 import Request, urlopen

# Replace https://inventwithpython.com/images/cover_automate2_thumb.jpg with the file you want to download.
url = 'https://inventwithpython.com/images/cover_automate2_thumb.jpg'

# Supply a user-agent header of a common browser, since some web servers will refuse to reply to scripts without one.
requestObj = Request(url, headers={'User-agent' : 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:97.0) Gecko/20100101 Firefox/97.0'})
responseObj = urlopen(requestObj)

content = responseObj.read()
# Replace foo.jpg with the local filename you want to use:
filename = url.split('/')[-1]  # Use the filename from the url.
with open(filename, 'wb') as fileObj:
    fileObj.write(content)

The urllib module in Python 2 was the original downloading module in the Python standard library added in Python 1.2. The urllib2 module in Python 2 had additional features and was added in Python 1.6. In Python 3, there is a new module just called urllib. There are also third-party modules named urllib3 and requests (which uses urllib3) but these aren't in the Python standard library nor will they be added to it.

I Like Al Sweigart's Books, What Can I Read to Get Into Game Programming?

2022-02-18T12:00:00-05:00

I got an email from a reader:

Sir I am very much happy with your book. Can you please tell me other books so that I can learn how to make larger games in other programming languages?

First I recommend my own free books, since I've written a few different ones:

Invent Your Own Computer Games with Python - For beginners with no programming experience. This book goes into simple text-based games and has a brief introduction to 2D graphics with the Pygame library.
Make Your Own Games with Python & Pygame - For those with basic Python experience, this book has several example game programs with 2D graphics.
The Big Book of Small Python Projects - For those with basic to no Python experience, this book has 81 small programming projects (mostly games, some simulation and digital art projects).

The /r/learnprogramming subreddit has an FAQ (Frequently Asked Questions) section on how to get started making video games.

Beyond these basic Python books, learn the Unity game engine (and the C# programming language) or the Godot game engine (and the Python-like GDScript language, though the engine also works with C#, C++, or Rust). Both of these game engines let you make games with 2D and 3D graphics for Windows, Linux, and macOS. But you can also make games for web browsers and mobile platforms like Android and iOS (iPhones). You can write your game once and create programs for all of these platforms. Unity also has the ability to make VR and AR games.

Of the two, I recommend beginners look at Godot first because it is free and simpler than the Unity ecosystem. I've looked into both of these engines a little, but I don't do development in either of these engines, nor in C# or GDScript. But here are some resources I've found:

For Unity, first watch the 18-minute video "How I learned Unity without following tutorials" from the excellent YouTube channel Game Maker's Toolkit. No matter what languages or engines you learn, you should watch the GMTK videos as they're great explanations of video game design principles.

You can download Unity for free.

For Godot, first read through the Godot FAQ. The /r/godot subreddit is also good place to ask questions.

I recommend reading my Python books on simple projects and then working in Godot. It's easy to get carried away with ideas for a grand video game, but remember that the major professional video games can have budgets over $100 million. These video games are just like major movie productions. You should aim for making simple games first, even ones that you couldn't sell. It's much better to have a dozen completed small projects than one never-finished large project. Good luck!

What Kind of Computer Do I Need to Learn Programming?

2022-02-03T12:00:00-05:00

You don't need to buy a new computer to learn programming. It's a common misconception that you need a powerful computer to program. This guide will give you some hints to guide you in the right direction.

Desktop, Laptop, or Mobile

Laptops are probably a better option, as you'll be able to take them with you to libraries, classes, or while you travel. Desktops are cheaper and less fragile in general. One thing to keep in mind if you want to learn to program is that mobile devices such as a tablet or especially a smartphone aren't ideal to learn to program on. I've never met a professional software developer who programs on a tablet or smartphone. The lack of a real keyboard and the small screen size is a large hinderance. Even developers who write mobile apps do so on a laptop or desktop.

Operating System

Windows, macOS, or Linux are fine options for developing software. Any of these platforms can be used for web app development. Though if you want to write desktop applications for a particular operating system, you should program on that operating system: write Windows apps on a Windows machine, write macOS apps on a macOS machine, write Linux apps on a Linux machine.

If you want to do mobile app development, you can use any of these three operating systems for Android development, but it's best to use a macOS machine to write iOS apps for iPhones.

If you want to create video games, any operating system is fine but Windows has the largest share of gamers (especially games from indie or large corporate game companies).

Windows 7 or later is fine for programming. Windows XP is, at this point, may give you difficulty finding compatible software for.

Buying Used Computers

Here's a few used computers I found on craigslist or eBay with specs that are more than powerful enough for programming:

"Dell OptiPlex 9010 i5 4GB 250GB Desktop SFF Tower PC w/Keyboard, Mouse" $99
"Old Win7 desktop (500gb hd/4gb ram/intel E5400 @2.7ghz x2 cpu)" $45
"HP Pavilion a6457c desktop with Acer monitor" $45
" HP 15 Laptop 250GB SSD Core i5 12GB RAM" $240
"Lenovo 15.6" Laptop Intel Core i3, 8GB RAM, 500GB SSD" $230

Any of these machines are more than powerful enough for programming. Working desktops can easily be found for $100 or less. Laptops are a bit more expensive, but workable laptops can be had for under $300.

Keep in mind that you should buy working computers. If a computer is being sold for cheap because it's missing a hard drive, memory, or some other component, it's unlikely to be worth your time to find a compatible part for it. Make sure to test the computer before accepting it. The computer should be able to turn on and let you, say, open a web browser or some other basic task. The main component of a used laptop that is likely to be faulty is the battery, which might not be able to keep charge for very long. And ideally, you should reinstall the operating system on the computer to wipe any previous malware or viruses that are inadvertantly installed.

For desktops, you'll need a monitor. Having a larger monitor makes a desktop far more useful than a slightly faster CPU or a little bit more memory. You can also get used monitors, but check for any "dead pixels" by opening a "dead pixel test" website such as this one and put the browser into full screen mode (often by pressing F11). Having a second monitor for your desktop or laptop is also a great help to your productivity, but make sure there is a second monitor port on the desktop to plug the second monitor into. Almost every laptop will have an additional monitor port to plug a second monitor into while you use the laptop's connected screen as the first monitor.

Every computer since around 2007 is a 64-bit computer. It's incredibly unlikely you'll find a still-functioning 32-bit computer, but before buying a very old machine make sure it is a 64-bit computer or else you may have problems running modern software on it.

More Information

The r/learnprogramming subreddit has an FAQ with additional information for what kind of operating system and what kind of computer you should get for programming.

If you are getting a Windows computer, I highly recommend checking out the Ninite.com website, which provides you with a no-hassle installer to install several common and free Windows applications.

Book Review: Make Python Talk

2022-01-13T12:02:00-05:00

Ebook free with print book purchase from No Starch Press.

Mark H. Liu’s “Make Python Talk” is a solid book for anyone who wants to leverage the power of the Python programming language to add speech capabilities to their programs. The chapters cover third-party libraries for speech recognition and text-to-speech in an engaging way. This book is more than a dry reference for these libraries, but also contains several example projects demonstrating how you can use these speech features in a variety of contexts. You don’t have to have computer science expertise to add these advanced features to your own projects; Liu’s book presents these speech software libraries with clarity and ease.

If you’ve stumbled through the documentation for Python’s speech libraries but are still unsure of how to actually make effective use of them, I recommend you give Make Python Talk a look.

Amazon review link

Book Review: Serious Python

2022-01-13T12:01:00-05:00

Ebook free with print book purchase from No Starch Press.

Serious Python by Julien Danjou is an excellent book for those who have gone through the "hello world" tutorials or those coming to Python from other programming languages, and want a book that teaches you not just how to write code, but how to write code the pythonic way.

You won't find chapters on mere syntax in this book: it expects that you've already covered the basics and want to move your Python skills to the next level. This covers a lot of ground that other Python books don't, and I'm glad I have it on my digital bookshelf.

Chapter 1 covers laying out the files and folders for your Python project. This chapter was great, even for an experienced software developer like myself. I always threw everything into "src" and "docs" folders, but didn't quite understand how Python projects were formatted and, more importantly, why. And while I had heard about semantic versioning before, this book pointed out a couple things that I've been doing wrong with my version numbering for my entire career.

Chapter 2 covers modules and importing, which is especially helpful from other languages that have similar, but distinct, ways of importing code.

Chapter 3 covers not just documentation, but Python-specific documentation: the Sphinx tool, ReStructured Text, Sphinx extensions like autodoc and autosummary, and the warnings module. These are things I had been ignorant about for years while I was writing Python code, and it's great to find all this information in one place.

Chapter 4 covers timestamps and time zones, and this is not just important Python information, but important programming information. Most programmers only learn about basic time/date-related functions and stop there. Time zones and the Olsen database and how to *properly* handle them are often ignored, resulting in subtle and hard-to-debug problems in software. Chapter 4 brings all of these issues to light, along with easy-to-miss Python modules that make working with dates and timezones manageable.

Chapter 5 covers packaging and distributing Python code, which is especially complex given Python's history of various and overlapping package management tools. I wish there had been more information in this chapter, but it does act as a good introduction to a topic that you'd ordinarily only find out about piecemeal over a career.

Chapter 6 covers unit testing (with pytest), fixtures, and mocks. It also covers code coverage.py tool for measuring the effectiveness of your unit tests.

Chapter 7 covers decorators and static/class/abstract methods. This was a great chapter for me in particular, because it's a topic that I've been getting by on by copy/pasting decorator code from other projects and, while that worked, I didn't have a full understanding of *why* the code worked until I read this chapter. The same applies to static and class methods in Python, which are easy to misuse.

Chapter 8 covers functional programming concepts. While Python isn't a functional programming language, it does have many features that support (and benefit from) writing code in a functional style. For anyone who doesn't know about functional programming, or was burned before when trying to learn the topic, this is a must-read chapter.

Chapter 9 is the only chapter that I feel like isn't absolutely required reading. It's nice to have a chapter on abstract syntax trees (especially since Python comes with the ast module to help navigate Python code), but it isn't relevant to most programmers. Still, I'd rather read this chapter than try to find out about the topic from some random web tutoiral.

Chapter 10 covers performance and optimization, explaining not just the cProfile module but also the dis module for disassembling Python bytecode for analysis. While this might not be directly necessary for most performance improvements, it does give a good introduction to the idea that Python bytecode isn't mystical at all; and you can directly compare how different bits of Python code are compiled to bytecode. There's also a hefty list of need-to-know, Python-specific tricks to writing faster code.

Chapter 11 and 12 cover process and databases, respectively. I wish these chapters were longer, but like many of the short sections, they provide a good introduction to several concepts that many programmers are unaware of, so they are worth a read-through.

Chapter 13 covers a few miscellaneous topics that don't quite fit in any other chapter, but I'm glad he covers them. Context managers, unicode, data classes (using the attrs module), and Python 2/3 support are definitely important to have in your Python toolbox.

This book could easily have been ten times its current length, but I like that it is to the point and it does a great job guiding the reader through the most important topics that aren't always covered by other books. "Serious Python" is a book you need to read if you're serious about following mature processes and being a capable Python programmer. It's filled with practical information that's normally scattered across web tutorials, conference talks, and Stack Overflow posts, but has been compiled here into one an excellent book. 5 stars.

(Full disclosure: I'm an author for No Starch Press, but No Starch Press didn't ask me to write this review and I purchased a copy on my own.)

Amazon review link

Book Review: Tiny Python Projects

2022-01-13T12:00:00-05:00

Writing for an intermediate audience is hard, but Ken Youens-Clark has nailed it with Tiny Python Projects. This is a great book for those who have dabbled with a few beginner Python tutorials but still feel like they don't "get" programming. The projects in this book are short and simple; perfect for beginners who want to get experience with actual programs instead of just code snippets.

The book covers many classic programs: Tic Tac Toe, Mad Libs, 99 Bottles of Beer, a password generator, and more. Youens-Clark uses these projects to discuss several intermediate and advance topics such as regular expressions, file i/o, random number generation, unit tests, ASCII values, parsing CSV files, and several others. I recommend this book for anyone who has been wanting to level up their coding skills, or even for beginners who aren't afraid to dive right into programming.

Amazon review link

How to Represent a 2D Grid in Python Code

2021-12-28T12:00:00-05:00

Introduction

This blog post examines different ways that Python lists and dictionaries can be used to represent a 2D data structure. I also write some test programs to measure the performance of each data structure.

A two-dimensional or 2D grid is used in a variety of applications. Think of chess boards, top-down video games, spreadsheets, Conway's Game of Life simulation are all examples of data that is stored in a two-dimensional grid. We can use a Cartesian coordinate system to create unique "addresses" for each item in the grid. The x coordinate is the horizontal address and the y coordinate is the vertical address.

The Cartesian coordinate system in programming is different from the one you may have learned about in math class. The origin (that is, the (0, 0) coordinate) is in the top-left corner of the screen, and while the x coordinates increase going to the right as in mathematics, the y coordinates increase going down rather than increase going up. In a spreadsheet program like Excel, the x coordinates may be represented by letters instead of numbers, but we'll use numbers for both the x and y coordinates. When listed together, the x coordinate comes first. In the coordinates (2, -5), 2 is the x coordinate and -5 is the y coordinate.

As an aside, here's a list of Python projects that utilize a 2D data structure that come from my free book, The Big Book of Small Python Projects:

The 2D Data Structures

By "2D data structure" I mean a data structure that contains other values the way that lists and dictionaries contain other values. While the data in lists can be accessed by an integer index and the data in dictionaries can be accessed by a key value, the data in our 2D data structures will be accessed by two integers: the x and y coordinates.

I'll be comparing three different data structures in this blog post:

A "1D list", where the data is stored in a Python list. The data at the coordinates (x, y) are stored at the index grid[y * WIDTH + x].
A "2D list", where the data is stored in a Python list of lists. The data at the coordinates (x, y) are stored at grid[x][y].
A dictionary, where the data is stored in... a Python dictioanry. The data at the coordiantes (x, y) are stored at grid[(x, y)]. (We can just specify grid[x, y] and Python will automaticall interpret this as a tuple containing x and y.)

There are a few advantages and disadvantages that I can see off the top of my head:

The 1D list and 2d list must have a fixed width and height. The dictionary can store data at any arbitrary coordinates.
The 1D list and 2d list use the same full amount of memory no matter how empty or full they are. The dictionary only uses up as much memory as it contains data.
The 2D lists can be tricky to work with, especially mixing the x and y coordinates with each other.
This is conjecture, but I think that as the dictionary becomes full, it uses up more memory than the 1D or 2D lists.
This is conjectue, but I think the dictionary might be slower than the lists at accessing and storing data.

Performance Tests

Without going into the specifics of Big O algorithm analysis (which you can learn about in Chapter 13 of my free book, Beyond the Basic Stuff with Python), accessing and storing data is a constant time operation for lists, lists of lists, and dictionaries. This means that it generally doesn't take longer to access or store data in lists or dictionaries as they fill up with data.

However, I'm more interested in the specific performance metrics of these as well as the memory usage. I'm going to write tests to measure these for these three different approaches to storing data in a grid. You can download and run these tests yourself on your computer. I'm running them with Python 3.10.0 on my T480s Thinkpad laptop running Windows 10.

I use Python's timeit module to measure the performance of the test code. You can also learn about this module in Beyond the Basic Stuff with Python.

Here's the gridtest.py program I wrote to measure the runtime speed and memory usage of these three 2D grid data structures. I put the output I got next to its respective print() call:

import timeit from sys import getsizeof, stderr from itertools import chain from collections import deque # These constants are the size of the grid used in the tests: WIDTH = 150 HEIGHT = 50 # Function to determine memory usage from https://code.activestate.com/recipes/577504-compute-memory-footprint-of-an-object-and-its-cont/?in=user-178123 def memoryUsage(o, handlers={}, verbose=False): dict_handler = lambda d: chain.from_iterable(d.items()) all_handlers = {tuple: iter, list: iter, deque: iter, dict: dict_handler, set: iter, frozenset: iter, } all_handlers.update(handlers) # user handlers take precedence seen = set() # track which object id's have already been seen default_size = getsizeof(0) # estimate sizeof object without __sizeof__ def sizeof(o): if id(o) in seen: # do not double count the same object return 0 seen.add(id(o)) s = getsizeof(o, default_size) for typ, handler in all_handlers.items(): if isinstance(o, typ): s += sum(map(sizeof, handler(o))) break return s return sizeof(o) def createAndFillDict(): # Create a 2D grid from scratch using a dictionary and completely fill it with data. dictGrid = {} for x in range(WIDTH): for y in range(HEIGHT): dictGrid[(x, y)] = 'A' return dictGrid def createAndFillDictComp(): # Create a 2D grid from scratch using a dictionary comprehension and completely fill it with data. return {(x, y): 'A' for x in range(WIDTH) for y in range(HEIGHT)} def createAndFill1DList(): # Create a 2D grid from scratch using a list and completely fill it with data. list1DGrid = [] for i in range(WIDTH * HEIGHT): list1DGrid.append('A') return list1DGrid def createAndFill1DListComp(): # Create a 2D grid from scratch using a list comprehension and completely fill it with data. return ['A' for i in range(WIDTH * HEIGHT)] def createAndFill2DList(): # Create a 2D grid from scratch using a list of lists and completely fill it with data. list2DGrid = [] for x in range(WIDTH): list2DGrid.append([]) for y in range(HEIGHT): list2DGrid[-1].append('A') return list2DGrid def createAndFill2DListComp(): # Create a 2D grid from scratch using a list comprehension of list comprehensions and completely fill it with data. list2DGrid = [['A' for y in range(HEIGHT)] for x in range(WIDTH)] return list2DGrid def read1DList(grid): # Read every coordinate in the list 2D grid. for x in range(WIDTH): for y in range(HEIGHT): data = grid[y * WIDTH + x] def read2DList(grid): # Read every coordinate in the list of lists 2D grid. for x in range(WIDTH): for y in range(HEIGHT): data = grid[x][y] def readDict(grid): # Read every coordinate in the dictionary 2D grid. for x in range(WIDTH): for y in range(HEIGHT): data = grid[x, y] def write1DList(grid): # Write to every coordinate in the list 2D grid. for x in range(WIDTH): for y in range(HEIGHT): grid[y * WIDTH + x] = 'A' def write2DList(grid): # Write to every coordinate in the list to lists 2D grid. for x in range(WIDTH): for y in range(HEIGHT): grid[x][y] = 'A' def writeDict(grid): # Write to every coordinate in the dictionary 2D grid. for x in range(WIDTH): for y in range(HEIGHT): grid[x, y] = 'A' print('Compare the 1D list and 1D list comprehension creations:') print(timeit.timeit('createAndFill1DList()', number=10000, globals=globals())) # 5.796480499964673 print(timeit.timeit('createAndFill1DListComp()', number=10000, globals=globals())) # 3.3725536999991164 # Conclusion: Using list comprehensions to create the list is faster than a for loop. print('Compare the 2D list and 2D list comprehension creations:') print(timeit.timeit('createAndFill2DList()', number=10000, globals=globals())) # 7.913099199999124 print(timeit.timeit('createAndFill2DListComp()', number=10000, globals=globals())) # 3.83729699999094 # Conclusion: Using list comprehensions to creat the 2D list is faster than nested for loops. print('Compare the dictionary and dictionary comprehension creations:') print(timeit.timeit('createAndFillDict()', number=10000, globals=globals())) # 9.804479899990838 print(timeit.timeit('createAndFillDictComp()', number=10000, globals=globals())) # 10.132151499972679 # Conclusion: With repeated trials, there isn't a significant difference. print('Compare the 1D list, 2D list, and dictionary creations:') print(timeit.timeit('createAndFill1DListComp()', number=10000, globals=globals())) # 3.2536532999947667 print(timeit.timeit('createAndFill2DListComp()', number=10000, globals=globals())) # 3.1561911000171676 print(timeit.timeit('createAndFillDict()', number=10000, globals=globals())) # 9.759650700027123 # Conclusion: The dictionary is slowest to create, and the 1D and 2D lists are about the same. print('Compare the memory usage of a full grid of each of the three approaches:') print(memoryUsage(createAndFill1DListComp())) # 67274 print(memoryUsage(createAndFill2DListComp())) # 72282 print(memoryUsage(createAndFillDict())) # 719246 # Conclusion: The 1D and 2D list use about the same amount, the 1D list less so. The dictionary uses 10x the memory though. print('Compare the speed of reading grid data:') list1dGrid = createAndFill1DListComp() list2dGrid = createAndFill2DListComp() dictGrid = createAndFillDict() print(timeit.timeit('read1DList(list1dGrid)', number=10000, globals=globals())) # 8.444686400005594 print(timeit.timeit('read2DList(list2dGrid)', number=10000, globals=globals())) # 3.76759669999592 print(timeit.timeit('readDict(dictGrid)', number=10000, globals=globals())) # 7.19706789997872 # Conclusion: The 2D list is twice as fast as the others at reading data. The 1D list is slower than the dictionary. print('Compare the speed of writing grid data:') print(timeit.timeit('write1DList(list1dGrid)', number=10000, globals=globals())) # 8.487390499969479 print(timeit.timeit('write2DList(list2dGrid)', number=10000, globals=globals())) # 4.278829399961978 print(timeit.timeit('writeDict(dictGrid)', number=10000, globals=globals())) # 7.716881500033196 # Conclusion: As with the read test, the 2D list is twice as fast as the others. The 1D list is slower than the dictionary.

Conclusions

The 2D list approach was the fastest and the dictionary approach was the slowest and used 10x as much memory as the 1D and 2D lists. But the dictionary approach gives you the flexibility of unbounded grids while the 1D and 2D lists have fixed width and height. The 1D list's requirement to calculate the index actually made it slower than the dictionary.

So if you need to have a 2D grid data structure, use the list-of-lists approach, unless you need an unbounded grid. In that case, the dictionary approach is significantly slower but offers this flexibility. Or, if performance isn't important, the dictionary approach has the easiest implementation.

In my personal view, ease of implementation and debuggability are the most important factors and my use cases don't tend to be at large enough scales where the performance differences are significant. I'd go with the dictionary approach.

JavaScript Books That Misspell "JavaScript": How Amazon Became a Minefield of Low-Quality Programming Books

2021-12-27T12:00:00-05:00

Here's a hint for programmers writing their resumes: "JavaScript" is spelled as one word, capital-J, capital-S, and no hyphen.

But this isn't a blog post about programmers who make typos on their resumes, but about what a minefield of low-quality programming books that Amazon has become.

Teaching people to code is important to me. I write books on programming and make them freely available online under a Creative Commons license. But there are many low-quality, self-published programming books on Amazon that you need to learn to avoid.

Let's look at JavaScript books that misspell "JavaScript". I'm not linking the books here, because they don't deserve the traffic.

First up is SQL Programming Guide. The subtitle is "Java Script and Coding Programming Guide: Learn In A Day!". If you look at the cover, it looks pretty nice except for the subtitle which was amateurishly added on after the fact. The subtitle is in a completely different font than the rest of the cover's text. It uses a serifed font instead of sans serif, likely because the serifed font was the default in whatever graphics program the "author" used.

It was odd that a SQL database book would also cover the JavaScript programming language. What's funny is that if you look at the table of contents, this book doesn't JavaScript at all. Literally none. They're just trying to capitalize on the popularity of JavaScript.

Suffice it to say, the positive reviews are probably all fake.

Best Excerpt from a Negative Review: "The only mention of Javascript is in the title." (I liked this one because even the negative review misspells JavaScript.)

The next JavaScript book that misspells "JavaScript" is Ajax books, ajax for beginners, Complete reference, Tips and tricks, ajax study, ajax for beginners, Step to step, ajax jquery, Jquery, Java script, PHP, Programming language. There's no subtitle, that's the entire title. The title contains the word "ajax" five times. They're clearly trying to cover their bases with that title. It's a title that has it all!

The cover is... a mess. The background pattern makes it hard to read the text, and he puts his name in a larger font than the title. Yikes.

Also, the book's contents are plagarized from Wikipedia. Most of these books probably are.

Best Excerpt from a Negative Review: "A book without a beginning or an end!"

Software Development for Engineers, C/C++, Pascal, Assembly, Visual Basic, HTML, Java Script, Java DOS, Windows NT, UNIX is amazing because it's from 1997. There's only one copy for sale available, so Amazon has it priced at $143. I'm not sure if it's actually from 1997 because there's a Kindle version available, but the cover sure does look like late 90s tech books. It was doing the SEO title thing before SEO was a thing. I like how it covers everything from Assembly to Java to VB to Pascal, and also UNIX, Windows NT, and DOS. Remember DOS? I do, because I'm old.

The book is over 600 pages, and from the table of contents it seems to actually cover the topics in its verbose title. It's just that the JavaScript chapter is 21 pages long. This was late 90s JavaScript, but still... I don't think 16 pages is enough to make a scrolling marquee in the status bar.

Remember scrolling marquees in the status bar? I do, because I'm old.

Best Excerpt from a Negative Review: There's only one review for this book, and it's just a wordless 3-star rating.

SMART Scripting is a nice title. It's followed by a subtitle that seems to be the author's life story: Scripting in more than one language - Learn mixing of VBScript, Java Script, HTML, Batch script and SQL Script. Write scripts for solving real daily life problems by mixing of scripts without having any expensive IDE compilers. That's multiple sentences with punctuation.

The cover design isn't that bad: it uses a limit color palette and sticks to two fonts. The author's name is about the same size as the title. But then it has this college entrance essay for a subtitle in tiny tiny print. The book is only 100 pages, and I'm guessing forty of those is for the subtitle. The remaining sixty pages covers the entirety of VBScript, JavaScript, HTML, batch files, and SQL.

I read the first page, and it's incredible: There are only three sentences that don't have blatantly wrong information.

Best Excerpt from a Negative Review: There's only one wordless 3-star review for this book too.

I like the tasteful cover and title of Java Script. The author didn't go for the 500-word subtitle approach of other books. It's too bad that the brief title gets the spelling of the language wrong. What's even more tragic is that the title is the only place in the book where "JavaScript" is misspelled. The author and cover designer must be two different people, otherwise the book's creator snatch defeat from the jaws of victory.

The interior of the book is the standard low quality writing and layout design. I can tell from the font and text color that this book was written in Word and directly exported to PDF from there.

Best Excerpt from a Negative Review: There are no reviews for this book, which makes me feel like this and the previous two books were actual earnest attempts to write books instead of making a cash grab that involved paying for positive reviews.

Using JavaScript's cover is a masterpiece of ugly. The top half is a blue and white cloudscape, the bottom is a stone-gray table of sorts with an illustrated coffee cup on a saucer. A cursive font is an... interesting... choice for the title. Normally you'd want the title to be easy to read. The cursive font makes this book's title look like "Javal Cript".

And the author forgot to put his name on the cover. He's modest.

The author of this self-published book didn't do a good job with their Amazon listing. "JavaScript" is spelled correctly on the cover of the book, but not on the Amazon page. There's no "see inside" preview, which is alluring because apparently this book is 896 pages. But it also says this book was published on January 1, 2001, which is before the Pearson Custom Publishing company existed.

And Amazon image of the cover... is literally a photo of the printed book resting on a table. The flash from the camera adds a bright spot that makes the title even harder to read.

I almost want to buy it just because I'm so curious as to what could be in the pages of this massive tome.

Best Excerpt fro- of course there are no reviews for this book.

From the author of SQL Programming Guide, the JavaScript book that literally has no JavaScript content, comes JAVA, JAVA Script and SQL, another JavaScript book that literally has no JavaScript content. Or Swift content (the subtitle is "Programming Guide: Learn In A Day! (Java, Swift, Apps, Programming Language)"). Or any content: the "look inside" preview on Amazon is literally 35 blank pages.

The cover is simply two copies of the other book's cover copy and pasted together.

The book has only one 5-star review from Brianna, a nurse from Portland, Oregon. Her headshot is so conventionally attractive you'd think she's a stock photo model. She's written 540 reviews, all 5-star.

Conclusion

Self-publishing has created a new wave of tech books. While I got my own start through self-publishing programming books, I need to stress that you should cast a skeptical eye over these books before you buy them. Just being listed on Amazon is not an indicator of quality, and Amazon's review system is rife with paid-for positive reviews.

How to Test Multiple Variables Against a Single Value and a Single Variable Against Multiple Values in Python

2021-12-20T12:00:00-05:00

TL;DR: Version

To test if a variable is one of many values, use the in operator:

>>> spam = 42
>>> if spam in (3.1415, 'hello', 42, False):
...   print("spam is either 3.1415, 'hello', 42, or False")
...
spam is either 3.1415, 'hello', 42, or False

To test if one of multiple variables is one of many values, use a list comprehension and the any() function:

>>> a, b, c = 1, 42, 3
>>> any([x in (100, 3.1415, 'Hello', 42, 'cheese') for x in (a, b, c)])
True

Testing Multiple Variables Against a Single Value And Vice Versa

In Python, if you want to see if a variable is one of many possible values, you could use the or operator like this:

>>> spam = 42
>>> if spam == 3.1415 or spam == 'hello' or spam == 42 or spam == False:
...   print("spam is either 3.1415, 'hello', 42, or False")
...
spam is either 3.1415, 'hello', 42, or False

Python has a more concise syntax that uses the in operator and the multiple values are packaged in a tuple:

>>> spam = 42
>>> if spam in (3.1415, 'hello', 42, False):
...   print("spam is either 3.1415, 'hello', 42, or False")
...
spam is either 3.1415, 'hello', 42, or False

The in operator literally checks if the value in spam is in the tuple on the right side of the in operator. This code is more readable and in most cases code readability is more important than performance. But using the in does perform slightly faster than the series of or operators. We can use Python's built-in timeit modules to see how many seconds running this code ten million times takes:

>>> timeit.timeit("spam = 42; spam == 3.1415 or spam == 'hello' or spam == 42 or spam == False", number=10000000)
1.527424699976109

>>> timeit.timeit("spam = 42; spam in (3.1415, 'hello', 42, False)", number=10000000)
0.8834100000094622

If you have the opposite case and you have multiple variables you need to check against one value, you can swap the left and right sides of the in operator. So instead of using or operators like this:

>>> a, b, c = 3.1415, 'hello', 42
>>> if a == 'hello' or b == 'hello' or c == 'hello':
...   print("One of a, b, or c is equal to 'hello'.")
...
One of a, b, or c is equal to 'hello'.

...you can write code using an in operator like this:

>>> if 'hello' in (a, b, c):
...   print("One of a, b, or c is equal to 'hello'.")
...
One of a, b, or c is equal to 'hello'.

Testing Multiple Variables Against Multiple Values

If you have multiple variables and you want to see if any of these variables matches one of several values, you can use a list comprehension and the built-in any() function. Let's take a moment to learn about these two concepts first.

The any() function takes a list or tuple (or any other iterable value) and returns True if any of the values in that list are True. If the list only has False values or is empty, it returns False:

>>> any([False, False, True, False])
True
>>> any([True, True])
True
>>> any([False, False, False, False, False])
False
>>> any([])
False

There is also a built-in all() function that returns True if the list only contains True values, or is an empty list. Otherwise, all() returns False.

List comprehensions are a short Python syntax for creating list values based on another list or tuple (or any other iterable value).

Normally you would use a for loop to create a new list based on another list's values. For example, I'm creating a list called doubles which contains the integers in the numbers list, but multiplied by 2:

>>> numbers = [3, 7, 15]
>>> doubles = []
>>> for number in numbers:
...   doubles.append(number * 2)
...
>>> doubles
[6, 14, 30]

A more concise way to write this code in Python is with a list comprehension. Note the similarities between the single-line list comprehension and the multi-line for loop code:

>>> numbers = [3, 7, 15]
>>> doubles = [number * 2 for number in numbers]
>>> doubles
[6, 14, 30]

To check if any one of multiple variables contains any one of multiple values, we can use list comprehensions and the in operator to create a list of Boolean True and False values. The list of Booleans created by the list comprehension are based on if the variables' value is in the tuple of values:

>>> a, b, c = 1, 2, 3
>>> [x in (100, 3.1415, 'Hello', 42, 'cheese') for x in (a, b, c)]
[False, False, False]
>>> b = 42
>>> [x in (100, 3.1415, 'Hello', 42, 'cheese') for x in (a, b, c)]
[False, True, False]

We can pass this list of Booleans to the any() function and determine if any of the variables matches any of the values:

>>> a, b, c = 1, 2, 3
>>> any([x in (100, 3.1415, 'Hello', 42, 'cheese') for x in (a, b, c)])
False
>>> b = 42
>>> any([x in (100, 3.1415, 'Hello', 42, 'cheese') for x in (a, b, c)])
True

Putting this much code into a single line stretches the limits of code readability, but it is more concise than not using list comprehensions and any(). Without them, you'd have to use nested for loops and so many lines of code that it's not necessarily more

>>> a, b, c = 1, 2, 3
>>> match = False
>>> for variable in (a, b, c):
...   for value in (100, 3.1415, 'Hello', 42, 'cheese'):
...     if variable == value:
...       match = True
...
>>> match
False

That's a lot of code to do a simple task. The list comprehension and any() approach is more concise and readable.

How, As a Kid, I Taught Myself to Code

2021-11-07T12:00:00-05:00

I was one of those kids in the 90s who taught themselves how to code by making video games in the BASIC programming language. Later, I majored in computer science, moved to Silicon Valley, became a software engineer, started writing programming books including Automate the Boring Stuff with Python, and then quit my job to write full-time. I now wake up whenever I want and work from home or nearby cafes. I'm financially secure while being my own boss.

This is a completely true story.^*

Here's how I accomplished all that by, as a kid, teaching myself to code:

When I was five, my parents bought an 8-bit Nintendo Entertainment System which got me into video games.
In the 90s my parents bought a Compaq 386 PC with a 14 MHz CPU, 40 megabyte hard drive, and ran MS-DOS.
In the third grade, my friend Brian showed me a book from the school library about programming video games in BASIC. (His parents also bought a PC for their home.)
While I was in elementary school, my grandfather gave my a 5 1/4" floppy disk with some BASIC games. As an adult I found out that these games were commonly copied around on university computer networks (my grandfather was a professor). I didn't understand the source code to them, but I liked looking through them.
My parents bought a Compaq Presario desktop with a 100 Mhz CPU, 1.2 gigabyte hard drive, and ran Windows 95.
My parents bought me a 16-bit Super Nintendo and more games that inspired the games I programmed (or at least tried to).
In high school, I made friends with hacker kids (it turned out most of their "hacks" were made up) who showed me how to pirate Visual Basic 4.0. This was when developer tools cost hundreds of dollars, as opposed to today when they're given away for free. The hacker kids also grew up in houses with PCs.
I found a copy of the Borland Turbo C compiler for sale at Half Price Books for $15 (instead of the usual hundreds of dollars). My parents bought it for me.
I started going to the monthly 2600 hacker meetings. People there gave me advice and some direction. I once brought my girlfriend to a meeting, but she felt out place there and didn't come with me again.
I started going to Barnes and Noble after school, pulling thick $80 tech books off the shelf, reading them in the store for a few hours, then putting them back on the shelf. I did this for years. The employees started to recognize me, but they didn't hassle me. I looked like I fit in.
My parents signed up for CompuServ (back when America Online, Prodigy, and CompuServ where the three main online services). I could be online for ten hours a month on dialup, but my parents would also pay the extra $2.50 an hour when I exceeded that.
My parents later signed up for an unlimited dial up service. I spent a lot more time online.
My parents later signed up for broadband internet. They also bought an additional 7 gigabyte hard drive. My hacker friends showed me how to pirate Star Wars: The Phantom Menance.
Junior year of high school, my computer science teacher (my high school had computer science classes) selected me and two other students to represent our school at a citywide programming competition. 14 teams from 14 schools had 3 hours to solve programming problems. The easiest problem was worth one point, and the questions got harder and worth more points. My team scored one point. So did ten other teams.
The programming competition was hosted by a tech company, and they gave every participant and teacher a copy of Visual Studio 6.0. I was amazed, because this was several dozen copies of software that cost $600. (At the time I didn't realize that CDs cost pennies to create.)
Reading the books at Barnes and Noble for free, I studied for the A+ certification exam. My parents paid for the $125 exam fee (and later, the exam fees for the Network+ and i-Net+ certifications). I never did use those certifications to get a job. These days, I don't even bother putting them on my resume.
While I was in high school, my parents bought me a laptop. Because I asked them to.
My older sister worked in a neurology lab as a student. She introduced me to the professor who ran the lab. He hired me part time to create some software for him. The program I created was pretty bad and not all that useful, but he still paid me. He also wrote me a letter of recommendation for my college application.
When I was in college, my parents bought me a newer laptop. Later, they bought me a wifi card so I could get on the internet at cafes. They also paid for my tuition and housing while I majored in computer science.

And that's the story of how I, on my own as a kid, taught myself to code.

(Did I mention all of my hacker friends were boys?)

I'm encountering some readers who aren't picking up on the facetious nature of this post. While everything in this post is factually true, it is satire. No child teaches themselves to code, though software engineers often tell and believe this story about themselves. I, myself, didn't realize how long this list would be until I wrote this post. We've had support, encouragement, and inspiration to follow this path. And we did not have discouragement, subtle or not, that convinced us we were out of place or not "programmer types." We would do well to remember this.

22 Examples of Recursive Functions in Python

2021-10-04T12:00:00-04:00

This blog post contains information from Al Sweigart's next book, The Recursive Book of Recurson from No Starch Press. The book will be released in June 2022. You can use the discount code PREORDERRECURSION to get 30% off your preorder, and receive the ebook free when you buy a print book. This book will also be freely available under a Creative Commons license on the Invent with Python website. Al Sweigart also gave a conference talk on recursion at North Bay Python 2018 titled, Recursion for Beginners: A Beginner's Guide to Recursion.

Here are 22 actual, runnable Python code for several recursive functions, written in a style to be understandable by beginners and produce debuggable output.

These are not code snippets; they are complete, runnable Python programs. The source code has been put inside a text field to make scrolling through this blog post easier. You can click on the text field, select all by pressing Ctrl-A, then copy the code to the clipboard by pressing Ctrl-C. Once on the clipboard, you can paste it into your editor or IDE. There are also download links for each of the programs as well.

These recursive functions are also designed to produce helpful, teachable output. Some of the functions have an indent parameter to aid in this output and isn't a part of the recursive algorithm itself.

Ackermann

Download ackermann.py

The Ackermann function is named after its discoverer, Wilhelm Ackermann. Ackermann, a student of mathematician David Hilbert (creator of the Hilbert curve fractal), published his function in 1928. Mathematicians Rózsa Péter and Raphael Robinson later developed the version of the function featured in this section. While the Ackermann function has some application in advanced mathematics, it is mostly known for being an example of a highly recursive function. Even slight increases to its two integer arguments cause a large increase in the number of recursive calls it makes.

Computerphile YouTube channel has a video on it titled, "The Most Difficult Program to Compute?"

The output of this program looks like this:

Starting with m = 1, n = 1:
ackermann(1, 1)
 ackermann(1, 0)
  ackermann(0, 1)
 ackermann(0, 2)
3
Starting with m = 2, n = 3:
ackermann(2, 3)
 ackermann(2, 2)
  ackermann(2, 1)
   ackermann(2, 0)
    ackermann(1, 1)
     ackermann(1, 0)
      ackermann(0, 1)
     ackermann(0, 2)
   ackermann(1, 3)
    ackermann(1, 2)
     ackermann(1, 1)
      ackermann(1, 0)
       ackermann(0, 1)
      ackermann(0, 2)
     ackermann(0, 3)
    ackermann(0, 4)
  ackermann(1, 5)
   ackermann(1, 4)
    ackermann(1, 3)
     ackermann(1, 2)
      ackermann(1, 1)
       ackermann(1, 0)
        ackermann(0, 1)
       ackermann(0, 2)
      ackermann(0, 3)
     ackermann(0, 4)
    ackermann(0, 5)
   ackermann(0, 6)
 ackermann(1, 7)
  ackermann(1, 6)
   ackermann(1, 5)
    ackermann(1, 4)
     ackermann(1, 3)
      ackermann(1, 2)
       ackermann(1, 1)
        ackermann(1, 0)
         ackermann(0, 1)
        ackermann(0, 2)
       ackermann(0, 3)
      ackermann(0, 4)
     ackermann(0, 5)
    ackermann(0, 6)
   ackermann(0, 7)
  ackermann(0, 8)
9

Binary Search

Download binarySearch.py

Binary search is a technique for locating a target item in a sorted list by re-peatedly determining which half of the list the item is in. The most impartial way to search the bookshelf is to start with a book in the middle, then ascertain if the target book you’re looking for is in the left half or the right half.

You can then repeat this process: look at the book in the middle of your chosen half, and determine if your target book is in the left-side quarter or the right-side quarter. You can do this until you either find the book or find the place where the book should be but isn’t and declare that the book doesn’t exist on the shelf.

The output of this program looks like this:

Combinations

Download combinations.py

Given a set of items, we can return a set of every combination of those items. For example, given a set of four letters, ABCD, the k-combinations are:

The 0-combinations and 4-combinations have one combination: the empty string and ABCD respectively.
The 1-combinations and 3-combinations have four combinations: A, B, C, D and ABC, ABD, ACD, BCD, respectively.
The 2-combinations have the most combinations at six combinations: AB, AC, AD, BC, BD, and CD.

def getCombos(chars, k, indent=0):
    debugMsg = '.' * indent + "In getCombos('" + chars + "', " + str(k) + ")"
    print(debugMsg + ', start.')
    if k == 0:
        # BASE CASE
        print(debugMsg + " base case returns ['']")
        return ['']  # If k asks for 0-combinations, return '' as the selection of zero letters from chars.
    elif chars == '':
        # BASE CASE
        print(debugMsg + ' base case returns []')
        return []  # A blank chars has no combinations, no matter what k is.

# RECURSIVE CASE
    combinations = []
    # First part, get the combos that include the head:
    head = chars[:1]
    tail = chars[1:]
    print(debugMsg + " part 1, get combos with head '" + head + "'")
    tailCombos = getCombos(tail, k - 1, indent + 1)
    print('.' * indent + "Adding head '" + head + "' to tail combos:")
    for tailCombo in tailCombos:
        print('.' * indent + 'New combination', head + tailCombo)
        combinations.append(head + tailCombo)

# Second part, get the combos that don't include the head:
    print(debugMsg + " part 2, get combos without head '" + head + "')")
    combinations.extend(getCombos(tail, k, indent + 1))

print(debugMsg + ' results are', combinations)
    return combinations

print('2-combinations of "ABC":')
print('Results:', getCombos('ABC', 2))

The output of this program looks like this:

2-combinations of "ABC":
In getCombos('ABC', 2), start.
In getCombos('ABC', 2) part 1, get combos with head 'A'
.In getCombos('BC', 1), start.
.In getCombos('BC', 1) part 1, get combos with head 'B'
..In getCombos('C', 0), start.
..In getCombos('C', 0) base case returns ['']
.Adding head 'B' to tail combos:
.New combination B
.In getCombos('BC', 1) part 2, get combos without head 'B')
..In getCombos('C', 1), start.
..In getCombos('C', 1) part 1, get combos with head 'C'
...In getCombos('', 0), start.
...In getCombos('', 0) base case returns ['']
..Adding head 'C' to tail combos:
..New combination C
..In getCombos('C', 1) part 2, get combos without head 'C')
...In getCombos('', 1), start.
...In getCombos('', 1) base case returns []
..In getCombos('C', 1) results are ['C']
.In getCombos('BC', 1) results are ['B', 'C']
Adding head 'A' to tail combos:
New combination AB
New combination AC
In getCombos('ABC', 2) part 2, get combos without head 'A')
.In getCombos('BC', 2), start.
.In getCombos('BC', 2) part 1, get combos with head 'B'
..In getCombos('C', 1), start.
..In getCombos('C', 1) part 1, get combos with head 'C'
...In getCombos('', 0), start.
...In getCombos('', 0) base case returns ['']
..Adding head 'C' to tail combos:
..New combination C
..In getCombos('C', 1) part 2, get combos without head 'C')
...In getCombos('', 1), start.
...In getCombos('', 1) base case returns []
..In getCombos('C', 1) results are ['C']
.Adding head 'B' to tail combos:
.New combination BC
.In getCombos('BC', 2) part 2, get combos without head 'B')
..In getCombos('C', 2), start.
..In getCombos('C', 2) part 1, get combos with head 'C'
...In getCombos('', 1), start.
...In getCombos('', 1) base case returns []
..Adding head 'C' to tail combos:
..In getCombos('C', 2) part 2, get combos without head 'C')
...In getCombos('', 2), start.
...In getCombos('', 2) base case returns []
..In getCombos('C', 2) results are []
.In getCombos('BC', 2) results are ['BC']
In getCombos('ABC', 2) results are ['AB', 'AC', 'BC']
Results: ['AB', 'AC', 'BC']

Count Down and Up

Download countDownAndUp.py

This function is a demonstration of a simple recursive function and shows the order that code runs before and after the recursive call.

The output of this program looks like this:

Drunk Sierpinski Triangle

Download drunkSierpinskiTriangle.py

This program uses the turtle module to draw a sierpinski triangle fractal, except with slight errors to give the fractal a distorted look.

import random
import turtle
turtle.tracer(1000, 0) # Increase the first argument to speed up the drawing.
turtle.setworldcoordinates(0, 0, 700, 700)
turtle.hideturtle()

MIN_SIZE = 4 # Try changing this to decrease/increase the amount of recursion.

DRUNKENESS = 0.001 # Increase to make more drunk. 0.01 is seriously drunk.

def midpoint(startx, starty, endx, endy):
    # Return the x, y coordinate in the middle of the four given parameters.
    xDiff = abs(startx - endx)
    yDiff = abs(starty - endy)
    return (min(startx, endx) + (xDiff / 2.0) + (random.random() * xDiff * (random.randint(-100, 100) * DRUNKENESS)),
            min(starty, endy) + (yDiff / 2.0) + (random.random() * xDiff * (random.randint(-100, 100) * DRUNKENESS)))

def isTooSmall(ax, ay, bx, by, cx, cy):
    # Determine if the triangle is too small to draw.
    width = max(ax, bx, cx) - min(ax, bx, cx)
    height = max(ay, by, cy) - min(ay, by, cy)
    return width < MIN_SIZE or height < MIN_SIZE

def drawTriangle(ax, ay, bx, by, cx, cy):
    if isTooSmall(ax, ay, bx, by, cx, cy):
        # BASE CASE
        return
    else:
        # RECURSIVE CASE
        # Draw the triangle.
        turtle.penup()
        turtle.goto(ax, ay)
        turtle.pendown()
        turtle.goto(bx, by)
        turtle.goto(cx, cy)
        turtle.goto(ax, ay)
        turtle.penup()

# Calculate midpoints between points A, B, and C.
        mid_ab = midpoint(ax, ay, bx, by)
        mid_bc = midpoint(bx, by, cx, cy)
        mid_ca = midpoint(cx, cy, ax, ay)

# Draw the three inner triangles.
        drawTriangle(ax, ay, mid_ab[0], mid_ab[1], mid_ca[0], mid_ca[1])
        drawTriangle(mid_ab[0], mid_ab[1], bx, by, mid_bc[0], mid_bc[1])
        drawTriangle(mid_ca[0], mid_ca[1], mid_bc[0], mid_bc[1], cx, cy)
        return

# Draw an equilateral Sierpinski triangle.
drawTriangle(50, 50, 350, 650, 650, 50)

# Draw a skewed Sierpinski triangle.
#drawTriangle(30, 250, 680, 600, 500, 80)

turtle.exitonclick()

The output of this program looks like this:

Eight Queens

Download eightQueens.py

The eight queens puzzle is how to find an arrangement of eight chess queens on a board such that they cannot attack each other. This recursive program finds every possible solution on an 8 x 8 chess board.

SIZE = 8

def getPermutations(items):
    if len(items) == 0:
        # BASE CASE
        return [[]]
    else:
        # RECURSIVE CASE
        permutations = []
        head = [items[0]]
        tail = items[1:]
        tailPermutations = getPermutations(tail)
        for tailPerm in tailPermutations:
            for i in range(len(tailPerm) + 1):
                newPermutation = tailPerm[0:i] + head + tailPerm[i:]
                permutations.append(newPermutation)
        return permutations

def printBoard(board):
    for row in range(SIZE):
        for column in range(SIZE):
            if board[row] == column:
                print('Q ', end='')  # Print queen.
            else:
                print('. ', end='')  # Print blank space.
        print()  # Print newline.
    print()

numSolutions = 0
# Go through all possible boards with one queen per column, and
# filter out the ones with queens that can attack each other diagonally:
for board in getPermutations(list(range(SIZE))):
    # check if any queens can diagonally attack each other
    isValidBoard = True
    for row in range(SIZE):
        column = board[row]
        for diagOffset in range(1, SIZE):
            if row + diagOffset < SIZE:  # Bounds check.
                if (board[row + diagOffset] == column + diagOffset) or \
                   (board[row + diagOffset] == column - diagOffset):
                    isValidBoard = False
                    break

if row - diagOffset >= 0:  # Bounds check.
                if (board[row - diagOffset] == column - diagOffset) or \
                   (board[row - diagOffset] == column + diagOffset):
                    isValidBoard = False
                    break

if isValidBoard:
        printBoard(board)
        numSolutions += 1
print('Number of solutions:', numSolutions)

The output of this program looks like this:

. . . . Q . . .
. Q . . . . . .
. . . . . Q . .
Q . . . . . . .
. . . . . . Q .
. . . Q . . . .
. . . . . . . Q
. . Q . . . . .

. . . . . Q . .
. . Q . . . . .
. . . . Q . . .
. . . . . . Q .
Q . . . . . . .
. . . Q . . . .
. Q . . . . . .
. . . . . . . Q

. . . . . Q . .
. . . Q . . . .
. . . . . . Q .
Q . . . . . . .
. . Q . . . . .
. . . . Q . . .
. Q . . . . . .
. . . . . . . Q

. . Q . . . . .
. . . . . Q . .
. Q . . . . . .
. . . . . . Q .
. . . . Q . . .
Q . . . . . . .
. . . . . . . Q
. . . Q . . . .

. . . . . Q . .
. . Q . . . . .
Q . . . . . . .
. . . . . . Q .
. . . . Q . . .
. . . . . . . Q
. Q . . . . . .
. . . Q . . . .

. . . . . Q . .
. Q . . . . . .
. . . . . . Q .
Q . . . . . . .
. . Q . . . . .
. . . . Q . . .
. . . . . . . Q
. . . Q . . . .

. . . . . Q . .
. . . Q . . . .
. . . . . . Q .
Q . . . . . . .
. . . . . . . Q
. Q . . . . . .
. . . . Q . . .
. . Q . . . . .

. . Q . . . . .
. . . . . Q . .
. Q . . . . . .
. . . . . . Q .
Q . . . . . . .
. . . Q . . . .
. . . . . . . Q
. . . . Q . . .

. . . . . Q . .
. . Q . . . . .
. . . . . . Q .
. Q . . . . . .
. . . Q . . . .
. . . . . . . Q
Q . . . . . . .
. . . . Q . . .

. . . . . Q . .
. . Q . . . . .
. . . . . . Q .
. . . Q . . . .
Q . . . . . . .
. . . . . . . Q
. Q . . . . . .
. . . . Q . . .

. Q . . . . . .
. . . . . Q . .
Q . . . . . . .
. . . . . . Q .
. . . Q . . . .
. . . . . . . Q
. . Q . . . . .
. . . . Q . . .

. . . . . Q . .
. Q . . . . . .
. . . . . . Q .
Q . . . . . . .
. . . Q . . . .
. . . . . . . Q
. . . . Q . . .
. . Q . . . . .

. . . . . Q . .
. . Q . . . . .
. . . . . . Q .
. Q . . . . . .
. . . . . . . Q
. . . . Q . . .
Q . . . . . . .
. . . Q . . . .

. . . . Q . . .
. . . . . . Q .
. Q . . . . . .
. . . . . Q . .
. . Q . . . . .
Q . . . . . . .
. . . Q . . . .
. . . . . . . Q

. . . . Q . . .
. . . . . . Q .
. Q . . . . . .
. . . . . Q . .
. . Q . . . . .
Q . . . . . . .
. . . . . . . Q
. . . Q . . . .

. . . Q . . . .
. . . . . . Q .
. . . . Q . . .
. . Q . . . . .
Q . . . . . . .
. . . . . Q . .
. . . . . . . Q
. Q . . . . . .

. . . Q . . . .
. . . . . . Q .
. . . . Q . . .
. Q . . . . . .
. . . . . Q . .
Q . . . . . . .
. . Q . . . . .
. . . . . . . Q

. . . . . . Q .
. . . . Q . . .
. . Q . . . . .
Q . . . . . . .
. . . . . Q . .
. . . . . . . Q
. Q . . . . . .
. . . Q . . . .

. . . Q . . . .
. Q . . . . . .
. . . . . . Q .
. . Q . . . . .
. . . . . Q . .
. . . . . . . Q
Q . . . . . . .
. . . . Q . . .

. . . Q . . . .
. Q . . . . . .
. . . . . . Q .
. . Q . . . . .
. . . . . Q . .
. . . . . . . Q
. . . . Q . . .
Q . . . . . . .

Q . . . . . . .
. . . . . . Q .
. . . Q . . . .
. . . . . Q . .
. . . . . . . Q
. Q . . . . . .
. . . . Q . . .
. . Q . . . . .

. . . . . . Q .
. Q . . . . . .
. . . . . Q . .
. . Q . . . . .
Q . . . . . . .
. . . Q . . . .
. . . . . . . Q
. . . . Q . . .

. Q . . . . . .
. . . . . . Q .
. . Q . . . . .
. . . . . Q . .
. . . . . . . Q
. . . . Q . . .
Q . . . . . . .
. . . Q . . . .

. . . . . . Q .
. . Q . . . . .
Q . . . . . . .
. . . . . Q . .
. . . . . . . Q
. . . . Q . . .
. Q . . . . . .
. . . Q . . . .

. . . . Q . . .
. Q . . . . . .
. . . Q . . . .
. . . . . . Q .
. . Q . . . . .
. . . . . . . Q
. . . . . Q . .
Q . . . . . . .

. . Q . . . . .
. . . . Q . . .
. . . . . . Q .
Q . . . . . . .
. . . Q . . . .
. Q . . . . . .
. . . . . . . Q
. . . . . Q . .

. . . . Q . . .
. . . . . . Q .
. . . Q . . . .
Q . . . . . . .
. . Q . . . . .
. . . . . . . Q
. . . . . Q . .
. Q . . . . . .

. . . . Q . . .
. . . . . . Q .
. Q . . . . . .
. . . Q . . . .
. . . . . . . Q
Q . . . . . . .
. . Q . . . . .
. . . . . Q . .

. Q . . . . . .
. . . . Q . . .
. . . . . . Q .
. . . Q . . . .
Q . . . . . . .
. . . . . . . Q
. . . . . Q . .
. . Q . . . . .

. . . . Q . . .
. . . . . . Q .
Q . . . . . . .
. . . Q . . . .
. Q . . . . . .
. . . . . . . Q
. . . . . Q . .
. . Q . . . . .

. . . . Q . . .
. . Q . . . . .
Q . . . . . . .
. . . . . . Q .
. Q . . . . . .
. . . . . . . Q
. . . . . Q . .
. . . Q . . . .

. Q . . . . . .
. . . . Q . . .
. . . . . . Q .
Q . . . . . . .
. . Q . . . . .
. . . . . . . Q
. . . . . Q . .
. . . Q . . . .

. . . . Q . . .
. . . . . . Q .
Q . . . . . . .
. . Q . . . . .
. . . . . . . Q
. . . . . Q . .
. . . Q . . . .
. Q . . . . . .

. . . Q . . . .
. Q . . . . . .
. . . . . . Q .
. . . . Q . . .
Q . . . . . . .
. . . . . . . Q
. . . . . Q . .
. . Q . . . . .

. . . . . . Q .
. . . Q . . . .
. Q . . . . . .
. . . . Q . . .
. . . . . . . Q
Q . . . . . . .
. . Q . . . . .
. . . . . Q . .

. . Q . . . . .
Q . . . . . . .
. . . . . . Q .
. . . . Q . . .
. . . . . . . Q
. Q . . . . . .
. . . Q . . . .
. . . . . Q . .

. Q . . . . . .
. . . . . . Q .
. . . . Q . . .
. . . . . . . Q
Q . . . . . . .
. . . Q . . . .
. . . . . Q . .
. . Q . . . . .

Q . . . . . . .
. . . . . . Q .
. . . . Q . . .
. . . . . . . Q
. Q . . . . . .
. . . Q . . . .
. . . . . Q . .
. . Q . . . . .

. . . Q . . . .
. . . . . . Q .
. . Q . . . . .
. . . . . . . Q
. Q . . . . . .
. . . . Q . . .
Q . . . . . . .
. . . . . Q . .

. . . Q . . . .
. . . . . . Q .
Q . . . . . . .
. . . . . . . Q
. . . . Q . . .
. Q . . . . . .
. . . . . Q . .
. . Q . . . . .

. . . . . . Q .
. Q . . . . . .
. . . Q . . . .
Q . . . . . . .
. . . . . . . Q
. . . . Q . . .
. . Q . . . . .
. . . . . Q . .

. . Q . . . . .
. . . . . . Q .
. Q . . . . . .
. . . . . . . Q
. . . . Q . . .
Q . . . . . . .
. . . Q . . . .
. . . . . Q . .

. . . . . . Q .
. . Q . . . . .
. . . . . . . Q
. Q . . . . . .
. . . . Q . . .
Q . . . . . . .
. . . . . Q . .
. . . Q . . . .

. . . . . . Q .
. . . Q . . . .
. Q . . . . . .
. . . . . . . Q
. . . . . Q . .
Q . . . . . . .
. . Q . . . . .
. . . . Q . . .

. . Q . . . . .
. . . . . . Q .
. Q . . . . . .
. . . . . . . Q
. . . . . Q . .
. . . Q . . . .
Q . . . . . . .
. . . . Q . . .

. . . . . . Q .
Q . . . . . . .
. . Q . . . . .
. . . . . . . Q
. . . . . Q . .
. . . Q . . . .
. Q . . . . . .
. . . . Q . . .

. . . . Q . . .
. Q . . . . . .
. . . Q . . . .
. . . . . Q . .
. . . . . . . Q
. . Q . . . . .
Q . . . . . . .
. . . . . . Q .

. . . . Q . . .
Q . . . . . . .
. . . Q . . . .
. . . . . Q . .
. . . . . . . Q
. Q . . . . . .
. . . . . . Q .
. . Q . . . . .

. . . . Q . . .
. . Q . . . . .
Q . . . . . . .
. . . . . Q . .
. . . . . . . Q
. Q . . . . . .
. . . Q . . . .
. . . . . . Q .

. . . Q . . . .
. . . . . Q . .
Q . . . . . . .
. . . . Q . . .
. Q . . . . . .
. . . . . . . Q
. . Q . . . . .
. . . . . . Q .

. . . . . Q . .
. . . Q . . . .
Q . . . . . . .
. . . . Q . . .
. . . . . . . Q
. Q . . . . . .
. . . . . . Q .
. . Q . . . . .

. . . . . Q . .
. . Q . . . . .
. . . . Q . . .
. . . . . . . Q
Q . . . . . . .
. . . Q . . . .
. Q . . . . . .
. . . . . . Q .

. . Q . . . . .
. . . . . Q . .
. Q . . . . . .
. . . . Q . . .
. . . . . . . Q
Q . . . . . . .
. . . . . . Q .
. . . Q . . . .

. . . . . Q . .
Q . . . . . . .
. . . . Q . . .
. Q . . . . . .
. . . . . . . Q
. . Q . . . . .
. . . . . . Q .
. . . Q . . . .

. . Q . . . . .
. . . . . Q . .
. . . Q . . . .
. Q . . . . . .
. . . . . . . Q
. . . . Q . . .
. . . . . . Q .
Q . . . . . . .

. . Q . . . . .
. . . . . Q . .
. . . Q . . . .
Q . . . . . . .
. . . . . . . Q
. . . . Q . . .
. . . . . . Q .
. Q . . . . . .

. . . . . Q . .
. . . Q . . . .
. Q . . . . . .
. . . . . . . Q
. . . . Q . . .
. . . . . . Q .
Q . . . . . . .
. . Q . . . . .

. . . . . Q . .
. . Q . . . . .
Q . . . . . . .
. . . . . . . Q
. . . . Q . . .
. Q . . . . . .
. . . Q . . . .
. . . . . . Q .

. . Q . . . . .
. . . . . Q . .
. . . . . . . Q
Q . . . . . . .
. . . . Q . . .
. . . . . . Q .
. Q . . . . . .
. . . Q . . . .

. Q . . . . . .
. . . Q . . . .
. . . . . Q . .
. . . . . . . Q
. . Q . . . . .
Q . . . . . . .
. . . . . . Q .
. . . . Q . . .

. . . Q . . . .
. . . . . Q . .
. . . . . . . Q
. . Q . . . . .
Q . . . . . . .
. . . . . . Q .
. . . . Q . . .
. Q . . . . . .

. . . Q . . . .
. . . . . Q . .
. . . . . . . Q
. Q . . . . . .
. . . . . . Q .
Q . . . . . . .
. . Q . . . . .
. . . . Q . . .

. . Q . . . . .
. . . . . Q . .
. . . . . . . Q
. Q . . . . . .
. . . Q . . . .
Q . . . . . . .
. . . . . . Q .
. . . . Q . . .

. . Q . . . . .
. . . . . Q . .
. . . . . . . Q
Q . . . . . . .
. . . Q . . . .
. . . . . . Q .
. . . . Q . . .
. Q . . . . . .

. . . . . Q . .
. . Q . . . . .
Q . . . . . . .
. . . . . . . Q
. . . Q . . . .
. Q . . . . . .
. . . . . . Q .
. . . . Q . . .

. Q . . . . . .
. . . . . Q . .
. . . . . . . Q
. . Q . . . . .
Q . . . . . . .
. . . Q . . . .
. . . . . . Q .
. . . . Q . . .

. . . . . Q . .
. . . . . . . Q
. Q . . . . . .
. . . Q . . . .
Q . . . . . . .
. . . . . . Q .
. . . . Q . . .
. . Q . . . . .

Q . . . . . . .
. . . . . Q . .
. . . . . . . Q
. . Q . . . . .
. . . . . . Q .
. . . Q . . . .
. Q . . . . . .
. . . . Q . . .

. . . Q . . . .
. Q . . . . . .
. . . . Q . . .
. . . . . . . Q
. . . . . Q . .
Q . . . . . . .
. . Q . . . . .
. . . . . . Q .

. . . Q . . . .
Q . . . . . . .
. . . . Q . . .
. . . . . . . Q
. . . . . Q . .
. . Q . . . . .
. . . . . . Q .
. Q . . . . . .

. . . . Q . . .
. . . . . . . Q
. . . Q . . . .
Q . . . . . . .
. . Q . . . . .
. . . . . Q . .
. Q . . . . . .
. . . . . . Q .

. . Q . . . . .
. . . . Q . . .
. Q . . . . . .
. . . . . . . Q
. . . . . Q . .
. . . Q . . . .
. . . . . . Q .
Q . . . . . . .

Q . . . . . . .
. . . . Q . . .
. . . . . . . Q
. . . . . Q . .
. . Q . . . . .
. . . . . . Q .
. Q . . . . . .
. . . Q . . . .

. . . . Q . . .
Q . . . . . . .
. . . . . . . Q
. . . . . Q . .
. . Q . . . . .
. . . . . . Q .
. Q . . . . . .
. . . Q . . . .

. . . Q . . . .
. Q . . . . . .
. . . . . . . Q
. . . . . Q . .
Q . . . . . . .
. . Q . . . . .
. . . . Q . . .
. . . . . . Q .

. . . . . . . Q
. . Q . . . . .
Q . . . . . . .
. . . . . Q . .
. Q . . . . . .
. . . . Q . . .
. . . . . . Q .
. . . Q . . . .

. Q . . . . . .
. . . . . . . Q
. . . . . Q . .
Q . . . . . . .
. . Q . . . . .
. . . . Q . . .
. . . . . . Q .
. . . Q . . . .

. . . Q . . . .
. . . . . . . Q
Q . . . . . . .
. . Q . . . . .
. . . . . Q . .
. Q . . . . . .
. . . . . . Q .
. . . . Q . . .

. . . . . . . Q
. . . Q . . . .
Q . . . . . . .
. . Q . . . . .
. . . . . Q . .
. Q . . . . . .
. . . . . . Q .
. . . . Q . . .

. . . Q . . . .
Q . . . . . . .
. . . . Q . . .
. . . . . . . Q
. Q . . . . . .
. . . . . . Q .
. . Q . . . . .
. . . . . Q . .

. . Q . . . . .
. . . . Q . . .
. . . . . . . Q
. . . Q . . . .
Q . . . . . . .
. . . . . . Q .
. Q . . . . . .
. . . . . Q . .

. . . . Q . . .
. . Q . . . . .
. . . . . . . Q
. . . Q . . . .
. . . . . . Q .
Q . . . . . . .
. . . . . Q . .
. Q . . . . . .

. . . . Q . . .
. Q . . . . . .
. . . . . . . Q
Q . . . . . . .
. . . Q . . . .
. . . . . . Q .
. . Q . . . . .
. . . . . Q . .

. . . . Q . . .
Q . . . . . . .
. . . . . . . Q
. . . Q . . . .
. Q . . . . . .
. . . . . . Q .
. . Q . . . . .
. . . . . Q . .

. . . . Q . . .
. . . . . . . Q
. . . Q . . . .
Q . . . . . . .
. . . . . . Q .
. Q . . . . . .
. . . . . Q . .
. . Q . . . . .

. . Q . . . . .
. . . . Q . . .
. Q . . . . . .
. . . . . . . Q
Q . . . . . . .
. . . . . . Q .
. . . Q . . . .
. . . . . Q . .

. . . Q . . . .
. . . . . . . Q
. . . . Q . . .
. . Q . . . . .
Q . . . . . . .
. . . . . . Q .
. Q . . . . . .
. . . . . Q . .

. . . Q . . . .
. Q . . . . . .
. . . . . . . Q
. . . . Q . . .
. . . . . . Q .
Q . . . . . . .
. . Q . . . . .
. . . . . Q . .

. . . Q . . . .
. . . . . . . Q
Q . . . . . . .
. . . . Q . . .
. . . . . . Q .
. Q . . . . . .
. . . . . Q . .
. . Q . . . . .

. . . . . . . Q
. Q . . . . . .
. . . . Q . . .
. . Q . . . . .
Q . . . . . . .
. . . . . . Q .
. . . Q . . . .
. . . . . Q . .

. . . . . . . Q
. Q . . . . . .
. . . Q . . . .
Q . . . . . . .
. . . . . . Q .
. . . . Q . . .
. . Q . . . . .
. . . . . Q . .

. . Q . . . . .
. . . . . . . Q
. . . Q . . . .
. . . . . . Q .
Q . . . . . . .
. . . . . Q . .
. Q . . . . . .
. . . . Q . . .

Number of solutions: 92

Exponentiation

Download exponentWithPowerRule.py

Calculating exponents such as 2^5 (or 2 x 2 x 2 x 2 x 2) can be done without using the ** operator by doing repeat multiplications. However, there's a shortcut in that 2^(m * 2) == 2^m * 2^m. You can use this trick to perform a^m in less than m multiplications.

The output of this program looks like this:

Factorial

Download factorialByRecursion.py

The factorial of 4 is 4 × 3 × 2 × 1 and the factorial of 5 is 5 × 4 × 3 × 2 × 1. So you could say that 5! = 5 × 4!. This is recursive because the definition of the factorial of 5 (or any number n) includes the definition of the factorial of 4 (the number n – 1). In turn, 4! = 4 × 3!, and so on, until you must calculate 1!, the base case, which is simply 1.

The output of this program looks like this:

Fibonacci

Download fibonacciByRecursion.py

The Fibonacci sequence is another classic example for introducing recursion. Mathematically, the Fibonacci sequence of integers begins with the numbers 1 and 1 (or sometimes, 0 and 1). The next number in the sequence is the sum of the previous two numbers. This creates the sequence 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, and so on, forever.

There is a recursive property to calculating Fibonacci numbers. For example, if you want to calculate the 10th Fibonacci number, you add the 9th and 8th Fibonacci numbers together. To calculate those Fibonacci numbers, you add the 8th and 7th, then the 7th and 6th Fibonacci numbers. There’s going to be a lot of repeat calculations: notice that adding the 9th and 8th Fibonacci number involves calculating the 8th Fibonacci number again. You would continue this recursion until you reach the base case of the 1st or 2nd Fibonacci numbers, which are always 1.

The output of this program looks like this:

fibonacci(10) called.
Calling fibonacci(9) (nthNumber - 1).
fibonacci(9) called.
Calling fibonacci(8) (nthNumber - 1).
fibonacci(8) called.
Calling fibonacci(7) (nthNumber - 1).
fibonacci(7) called.
Calling fibonacci(6) (nthNumber - 1).
fibonacci(6) called.
Calling fibonacci(5) (nthNumber - 1).
fibonacci(5) called.
Calling fibonacci(4) (nthNumber - 1).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Calling fibonacci(3) (nthNumber - 2).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Call to fibonacci(5) returning 5.
Calling fibonacci(4) (nthNumber - 2).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Call to fibonacci(6) returning 8.
Calling fibonacci(5) (nthNumber - 2).
fibonacci(5) called.
Calling fibonacci(4) (nthNumber - 1).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Calling fibonacci(3) (nthNumber - 2).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Call to fibonacci(5) returning 5.
Call to fibonacci(7) returning 13.
Calling fibonacci(6) (nthNumber - 2).
fibonacci(6) called.
Calling fibonacci(5) (nthNumber - 1).
fibonacci(5) called.
Calling fibonacci(4) (nthNumber - 1).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Calling fibonacci(3) (nthNumber - 2).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Call to fibonacci(5) returning 5.
Calling fibonacci(4) (nthNumber - 2).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Call to fibonacci(6) returning 8.
Call to fibonacci(8) returning 21.
Calling fibonacci(7) (nthNumber - 2).
fibonacci(7) called.
Calling fibonacci(6) (nthNumber - 1).
fibonacci(6) called.
Calling fibonacci(5) (nthNumber - 1).
fibonacci(5) called.
Calling fibonacci(4) (nthNumber - 1).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Calling fibonacci(3) (nthNumber - 2).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Call to fibonacci(5) returning 5.
Calling fibonacci(4) (nthNumber - 2).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Call to fibonacci(6) returning 8.
Calling fibonacci(5) (nthNumber - 2).
fibonacci(5) called.
Calling fibonacci(4) (nthNumber - 1).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Calling fibonacci(3) (nthNumber - 2).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Call to fibonacci(5) returning 5.
Call to fibonacci(7) returning 13.
Call to fibonacci(9) returning 34.
Calling fibonacci(8) (nthNumber - 2).
fibonacci(8) called.
Calling fibonacci(7) (nthNumber - 1).
fibonacci(7) called.
Calling fibonacci(6) (nthNumber - 1).
fibonacci(6) called.
Calling fibonacci(5) (nthNumber - 1).
fibonacci(5) called.
Calling fibonacci(4) (nthNumber - 1).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Calling fibonacci(3) (nthNumber - 2).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Call to fibonacci(5) returning 5.
Calling fibonacci(4) (nthNumber - 2).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Call to fibonacci(6) returning 8.
Calling fibonacci(5) (nthNumber - 2).
fibonacci(5) called.
Calling fibonacci(4) (nthNumber - 1).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Calling fibonacci(3) (nthNumber - 2).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Call to fibonacci(5) returning 5.
Call to fibonacci(7) returning 13.
Calling fibonacci(6) (nthNumber - 2).
fibonacci(6) called.
Calling fibonacci(5) (nthNumber - 1).
fibonacci(5) called.
Calling fibonacci(4) (nthNumber - 1).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Calling fibonacci(3) (nthNumber - 2).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Call to fibonacci(5) returning 5.
Calling fibonacci(4) (nthNumber - 2).
fibonacci(4) called.
Calling fibonacci(3) (nthNumber - 1).
fibonacci(3) called.
Calling fibonacci(2) (nthNumber - 1).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Calling fibonacci(1) (nthNumber - 2).
fibonacci(1) called.
Base case fibonacci(1) returning 1.
Call to fibonacci(3) returning 2.
Calling fibonacci(2) (nthNumber - 2).
fibonacci(2) called.
Base case fibonacci(2) returning 1.
Call to fibonacci(4) returning 3.
Call to fibonacci(6) returning 8.
Call to fibonacci(8) returning 21.
Call to fibonacci(10) returning 55.
55

Floodfill

Download floodfill.py

import sys

# Create the image (make sure it's rectangular!)
im = [list('..########################...........'),
      list('..#......................#...#####...'),
      list('..#..........########....#####...#...'),
      list('..#..........#......#............#...'),
      list('..#..........########.........####...'),
      list('..######......................#......'),
      list('.......#..#####.....###########......'),
      list('.......####...#######................')]

HEIGHT = len(im)
WIDTH = len(im[0])

def floodFill(image, x, y, newChar, oldChar=None):
    if oldChar == None:
        # oldChar defaults to the character at x, y.
        oldChar = image[y][x]
    if oldChar == newChar or image[y][x] != oldChar:
        # BASE CASE
        return

image[y][x] = newChar # Change the character.

# Uncomment to view each step:
    #printImage(image)

# Change the neighboring characters.
    if y + 1 < HEIGHT and image[y + 1][x] == oldChar:
        # RECURSIVE CASE
        floodFill(image, x, y + 1, newChar, oldChar)
    if y - 1 >= 0 and image[y - 1][x] == oldChar:
        # RECURSIVE CASE
        floodFill(image, x, y - 1, newChar, oldChar)
    if x + 1 < WIDTH and image[y][x + 1] == oldChar:
        # RECURSIVE CASE
        floodFill(image, x + 1, y, newChar, oldChar)
    if x - 1 >= 0 and image[y][x - 1] == oldChar:
        # RECURSIVE CASE
        floodFill(image, x - 1, y, newChar, oldChar)
    return # BASE CASE

def printImage(image):
    for y in range(HEIGHT):
        # Print each row.
        for x in range(WIDTH):
            # Print each column.
            sys.stdout.write(image[y][x])
        sys.stdout.write('\n')
    sys.stdout.write('\n')

printImage(im)
floodFill(im, 3, 3, 'o')
printImage(im)

The output of this program looks like this:

GCD, Greatest Common Denominator

Download gcdRecursive.py

Factors are the numbers that are multiplied to produce a particular number. Consider 4 × 6 = 24. In this equation, 4 and 6 are factors of 24. Because a number’s factors can also be used to divide that number without leaving a remainder, factors are also called divisors.

The factors of 24 are 1, 2, 3, 4, 6, 8, 12, and 24. The factors of 30 are 1, 2, 3, 5, 6, 10, 15, and 30. Note that any number will always have 1 and itself as its factors because 1 times a number is equal to that number. Notice too that the list of factors for 24 and 30 have 1, 2, 3, and 6 in common. The greatest of these common factors is 6, so 6 is the greatest common factor, more commonly known as the greatest common divisor (GCD), of 24 and 30.

Euclid, a mathematician who lived 2000 years ago, came up with a short algorithm for finding the GCD of two numbers using modular arithmetic. His algorithm can be implemented with recursion:

The output of this program looks like this:

Hilbert Curve Fractal

Download hilbertCurve.py

A space-filling curve is a one-dimensional line that curves around until it completely fills a two-dimensional space without crossing over itself. German mathematician David Hilbert described his space-filling Hilbert curve in 1891.

import turtle
turtle.tracer(10, 0) # Increase the first argument to speed up the drawing.
turtle.setworldcoordinates(0, 0, 700, 700)
turtle.hideturtle()

LINE_LENGTH  = 5 # Try changing the line length by a litte.
ANGLE = 90 # Try changing the turning angle by a few degrees.
LEVELS = 6  # Try changing the recursive level by a litte.
DRAW_SOLID = False
#turtle.setheading(20) # Uncomment this line to draw the curve at an angle.

def hilbertCurveQuadrant(level, angle):
    if level == 0:
        # BASE CASE
        return
    else:
        # RECURSIVE CASE
        turtle.right(angle)
        hilbertCurveQuadrant(level - 1, -angle)
        turtle.forward(LINE_LENGTH)
        turtle.left(angle)
        hilbertCurveQuadrant(level - 1, angle)
        turtle.forward(LINE_LENGTH)
        hilbertCurveQuadrant(level - 1, angle)
        turtle.left(angle)
        turtle.forward(LINE_LENGTH)
        hilbertCurveQuadrant(level - 1, -angle)
        turtle.right(angle)
        return

def hilbertCurve(startingPosition):
    # Move to starting position.
    turtle.penup()
    turtle.goto(startingPosition)
    turtle.pendown()
    if DRAW_SOLID:
        turtle.begin_fill()

hilbertCurveQuadrant(LEVELS, ANGLE) # Draw lower left quadrant.
    turtle.forward(LINE_LENGTH)

hilbertCurveQuadrant(LEVELS, ANGLE) # Draw lower right quadrant.
    turtle.left(ANGLE)
    turtle.forward(LINE_LENGTH)
    turtle.left(ANGLE)

hilbertCurveQuadrant(LEVELS, ANGLE) # Draw upper right quadrant.
    turtle.forward(LINE_LENGTH)

hilbertCurveQuadrant(LEVELS, ANGLE) # Draw upper left quadrant.

turtle.left(ANGLE)
    turtle.forward(LINE_LENGTH)
    turtle.left(ANGLE)
    if DRAW_SOLID:
        turtle.end_fill()

hilbertCurve((30, 350))
turtle.exitonclick()

The output of this program looks like this:

Karatsuba Multiplication

Download karatsubaMultiplication.py

Karatsuba multiplication is a fast, recursive algorithm discovered by Anatoly Karatsuba in 1960 that can multiply integers using addition, subtraction, and a pre-computed multiplication table of all products from single-digit numbers.

import math

# Create a cache of all single-digit multiplication products:
MULT_TABLE = {}
for i in range(10):
    for j in range(10):
        MULT_TABLE[(i, j)] = i * j

def padZeros(numberString, numZeros, insertSide):
    """Return a string padded with zeros on the left or right side."""
    if insertSide == 'left':
        return '0' * numZeros + numberString
    elif insertSide == 'right':
        return numberString + '0' * numZeros

def karatsuba(x, y):
    """Multiply two integers with the Karatsuba algorithm. Note that
    the * operator isn't used anywhere in this function."""
    assert isinstance(x, int), 'x must be an integer'
    assert isinstance(y, int), 'y must be an integer'
    x = str(x)
    y = str(y)

# At single-digits, look up the products in the multiplication table:
    if len(x) == 1 and len(y) == 1:  # BASE CASE
        print('Lookup', x, '*', y, '=', MULT_TABLE[(int(x), int(y))])
        return MULT_TABLE[(int(x), int(y))]

# RECURSIVE CASE
    print('Multiplying', x, '*', y)

# Pad with prepended zeros so that x and y are the same length:
    if len(x) < len(y):
        # If x is shorter than y, pad x with zeros:
        x = padZeros(x, len(y) - len(x), 'left')
    elif len(y) < len(x):
        # If y is shorter than x, pad y with zeros:
        y = padZeros(y, len(x) - len(y), 'left')
    # At this point, x and y have the same length.

halfOfDigits = math.floor(len(x) / 2)

# Split x into halves a & b, split y into halves c & d:
    a = int(x[:halfOfDigits])
    b = int(x[halfOfDigits:])
    c = int(y[:halfOfDigits])
    d = int(y[halfOfDigits:])

# Make the recursive calls with these halves:
    step1Result = karatsuba(a, c) # Step 1: Multiply a & c.
    step2Result = karatsuba(b, d) # Step 2: Multiply b & d.
    step3Result = karatsuba(a + b, c + d) # Step 3: Multiply a + b & c + d.

# Step 4: Calculate Step 3 - Step 2 - Step 1:
    step4Result = step3Result - step2Result - step1Result

# Step 5: Pad these numbers, then add them for the return value:
    step1Padding = (len(x) - halfOfDigits) + (len(x) - halfOfDigits)
    step1PaddedNum = int(padZeros(str(step1Result), step1Padding, 'right'))

step4Padding = (len(x) - halfOfDigits)
    step4PaddedNum = int(padZeros(str(step4Result), step4Padding, 'right'))

print('Solved', x, '*', y, '=', step1PaddedNum + step2Result + step4PaddedNum)

return step1PaddedNum + step2Result + step4PaddedNum

# Example: 1357 x 2468 = 3349076
print('1357 * 2468 =', karatsuba(1357, 2468))

The output of this program looks like this:

Koch Snowflake Fractal

Download kochSnowflake.py

First introduced in 1902 by Swedish mathematician Helge von Koch, the Koch curve is one of the earliest fractals to be described mathematically. Its construction is simple: take a line of length b and divide it into three equal parts, each of length b / 3. Replace the middle section with a “bump” whose sides are also of length b / 3. This bump causes the Koch curve to be longer than the original line, since there are now four line segments of length b / 3. (We’ll exclude the original middle part of the line segment.) This bump-creation can be repeated on the new four line segments. The Koch Snowflake is three of these Koch curves connected together.

import turtle
turtle.tracer(10, 0) # Increase the first argument to speed up the drawing.
turtle.setworldcoordinates(0, 0, 700, 700)
turtle.hideturtle()
turtle.pensize(2)

def drawKochCurve(startPosition, heading, length):
    if length < 1:
        # BASE CASE
        return
    else:
        # RECURSIVE CASE
        # Move to the start position.
        recursiveArgs = []
        turtle.penup()
        turtle.goto(startPosition)
        turtle.setheading(heading)
        recursiveArgs.append({'position':turtle.position(),
                              'heading':turtle.heading()})

# Erase the middle third.
        turtle.forward(length / 3)
        turtle.pencolor('white')
        turtle.pendown()
        turtle.forward(length / 3)

# Draw the bump.
        turtle.backward(length / 3)
        turtle.left(60)
        recursiveArgs.append({'position':turtle.position(),
                              'heading':turtle.heading()})
        turtle.pencolor('black')
        turtle.forward(length / 3)
        turtle.right(120)
        recursiveArgs.append({'position':turtle.position(),
                              'heading':turtle.heading()})
        turtle.forward(length / 3)
        turtle.left(60)
        recursiveArgs.append({'position':turtle.position(),
                              'heading':turtle.heading()})

for i in range(4):
            drawKochCurve(recursiveArgs[i]['position'],
                     recursiveArgs[i]['heading'],
                     length / 3)
        return

def drawKochSnowflake(startPosition, heading, length):
    # A Koch snowflake is three Koch curves in a triangle.

# Move to the starting position
    turtle.penup()
    turtle.goto(startPosition)
    turtle.setheading(heading)

for i in range(3):
        # Record the starting position and heading.
        curveStartingPosition = turtle.position()
        curveStartingHeading = turtle.heading()
        drawKochCurve(curveStartingPosition,
                      curveStartingHeading, length)

# Move back to the start position for this side.
        turtle.penup()
        turtle.goto(curveStartingPosition)
        turtle.setheading(curveStartingHeading)

# Move to the start position of the next side.
        turtle.forward(length)
        turtle.right(120)

drawKochSnowflake((100, 500), 0, 500)
turtle.exitonclick()

The output of this program looks like this:

Merge Sort

Download mergeSort.py

Computer scientist John von Neumann developed merge sort in 1945 and it is an efficient, general-purpose sorting algorithm particularly used to sort linked list data structures. It uses a divide-merge approach: each recursive call to mergeSort() divides the unsorted list into halves until they’ve been whittled down into lists with lengths of zero or one. Then, as the recursive calls return, these smaller lists are merged together into sorted order. When the last recursive call has returned, the entire list will have been sorted.

For example, the divide step takes a list, such as [0, 7, 6, 3, 1, 2, 5, 4], and splits it into two lists, like [0, 7, 6, 3] and [1, 2, 5, 4], to pass to two recursive function calls. At the base case, the lists have been divided into lists of zero or one item. After the recursive calls return, the code merges the two lists into a larger list. If the two lists are in sorted order (and lists of zero or one item are sorted by their nature), merging will also produce a sorted list. The end result is that the original mergeSort() call returns the full list in sorted order.

import math

def mergeSort(items):
    print('.....mergeSort() called on:', items)

if len(items) == 0 or len(items) == 1:  # BASE CASE
        # With only zero or one items, `items` is already sorted.
        return items

# RECURSIVE CASE
    # Round down if `items` doesn't divide in half evenly:
    iMiddle = math.floor(len(items) / 2)

print('................Split into:', items[:iMiddle], 'and', items[iMiddle:])

left = mergeSort(items[:iMiddle])
    right = mergeSort(items[iMiddle:])

# At this point, `left` should be sorted and `right` should be
    # sorted. We can merge them into a single sorted list like a zipper.
    sortedResult = []
    iLeft = 0
    iRight = 0
    while (len(sortedResult) < len(items)):
        # Append the smaller of left & right's value to `sortedResult`.
        if left[iLeft] < right[iRight]:
            sortedResult.append(left[iLeft])
            iLeft += 1
        else:
            sortedResult.append(right[iRight])
            iRight += 1

# If one of the pointers has reached the end of its list,
        # put the rest of the other list into `sortedResult`.
        if iLeft == len(left):
            sortedResult.extend(right[iRight:])
            break
        elif iRight == len(right):
            sortedResult.extend(left[iLeft:])
            break

print('The two halves merged into:', sortedResult)

return sortedResult  # Returns a sorted version of `items`.

myList = [0, 7, 6, 3, 1, 2, 5, 4]
myList = mergeSort(myList)
print(myList)

The output of this program looks like this:

.....mergeSort() called on: [0, 7, 6, 3, 1, 2, 5, 4]
................Split into: [0, 7, 6, 3] and [1, 2, 5, 4]
.....mergeSort() called on: [0, 7, 6, 3]
................Split into: [0, 7] and [6, 3]
.....mergeSort() called on: [0, 7]
................Split into: [0] and [7]
.....mergeSort() called on: [0]
.....mergeSort() called on: [7]
The two halves merged into: [0, 7]
.....mergeSort() called on: [6, 3]
................Split into: [6] and [3]
.....mergeSort() called on: [6]
.....mergeSort() called on: [3]
The two halves merged into: [3, 6]
The two halves merged into: [0, 3, 6, 7]
.....mergeSort() called on: [1, 2, 5, 4]
................Split into: [1, 2] and [5, 4]
.....mergeSort() called on: [1, 2]
................Split into: [1] and [2]
.....mergeSort() called on: [1]
.....mergeSort() called on: [2]
The two halves merged into: [1, 2]
.....mergeSort() called on: [5, 4]
................Split into: [5] and [4]
.....mergeSort() called on: [5]
.....mergeSort() called on: [4]
The two halves merged into: [4, 5]
The two halves merged into: [1, 2, 4, 5]
The two halves merged into: [0, 1, 2, 3, 4, 5, 6, 7]
[0, 1, 2, 3, 4, 5, 6, 7]

Permutations

Download permutations.py

A permutation of a set is a specific ordering of all elements in the set. For example, there are six permutations for the set {A, B, C}: ABC, ACB, BAC, BCA, CAB, and CBA. We call these permutations without repetition or permutations without replacement, because each element doesn’t appear in the permutation more than once.

Imagine you must arrange the seating chart for a wedding reception with delicate social requirements. Some of the guests hate each other and while others demand to sit near an influential guest. The seats at the table form one long row, rather than a circle. It’d be helpful for your planning to see every possible ordering of guests, that is, every permutation without repetition of the set of guests. There is no repetition because each guest will only appear in the seating chart once. Let’s use a simple example of Alice, Bob, and Carol, or {A, B, C}.

The output of this program looks like this:

Permutations of "ABCD":
Start of getPerms("ABCD")
.Start of getPerms("BCD")
..Start of getPerms("CD")
...Start of getPerms("D")
...When chars = "D" base case returns D
..When chars = CD putting head C in all places in D
..New permutation: CD
..New permutation: DC
..When chars = CD results are ['CD', 'DC']
.When chars = BCD putting head B in all places in CD
.New permutation: BCD
.New permutation: CBD
.New permutation: CDB
.When chars = BCD putting head B in all places in DC
.New permutation: BDC
.New permutation: DBC
.New permutation: DCB
.When chars = BCD results are ['BCD', 'CBD', 'CDB', 'BDC', 'DBC', 'DCB']
When chars = ABCD putting head A in all places in BCD
New permutation: ABCD
New permutation: BACD
New permutation: BCAD
New permutation: BCDA
When chars = ABCD putting head A in all places in CBD
New permutation: ACBD
New permutation: CABD
New permutation: CBAD
New permutation: CBDA
When chars = ABCD putting head A in all places in CDB
New permutation: ACDB
New permutation: CADB
New permutation: CDAB
New permutation: CDBA
When chars = ABCD putting head A in all places in BDC
New permutation: ABDC
New permutation: BADC
New permutation: BDAC
New permutation: BDCA
When chars = ABCD putting head A in all places in DBC
New permutation: ADBC
New permutation: DABC
New permutation: DBAC
New permutation: DBCA
When chars = ABCD putting head A in all places in DCB
New permutation: ADCB
New permutation: DACB
New permutation: DCAB
New permutation: DCBA
When chars = ABCD results are ['ABCD', 'BACD', 'BCAD', 'BCDA', 'ACBD', 'CABD', 'CBAD', 'CBDA', 'ACDB', 'CADB', 'CDAB', 'CDBA', 'ABDC', 'BADC', 'BDAC', 'BDCA', 'ADBC', 'DABC', 'DBAC', 'DBCA', 'ADCB', 'DACB', 'DCAB', 'DCBA']
Results: ABCD,BACD,BCAD,BCDA,ACBD,CABD,CBAD,CBDA,ACDB,CADB,CDAB,CDBA,ABDC,BADC,BDAC,BDCA,ADBC,DABC,DBAC,DBCA,ADCB,DACB,DCAB,DCBA

Quicksort

Download quicksort.py

Quicksort uses a divide-and-conquer technique called partitioning. Think of partitioning this way: imagine you have a large pile of unalphabetized books. Grabbing one book and placing it in the right spot on the shelf means you’ll spend a lot of time rearranging the bookshelf as it gets full. It would help if you first turned the pile of books into two piles: an A to M pile and an N to Z pile. (In this example, M would be our pivot.)

You haven’t sorted the pile, but you have partitioned it. And partitioning is easy: the book doesn’t have to go into the correct place in one of the two piles, it just has to go into the correct pile. Then you can further partition these two piles into four piles: A to G, H to M, N to T, and U to Z. This is shown in Figure 5-x. If you keep partitioning, you end up with piles that contain one book each (the base case), and the piles are now in sorted order. This repeated partitioning is how quicksort works.

In our implementation, each call to quicksort() is given an array of items to sort. It is also given left and right arguments specifying the range of indexes in that array to sort, similar to binarySearch()’s left and right arguments. The algorithm selects a pivot value to compare with the other values in the range, then places the values to either the left side of the range (if they’re less than the pivot value) or the right side (if they’re greater than the pivot value). This is the partition step. Next, the quicksort() function is recursively called on these two, smaller ranges until a range has been reduced to zero. The list becomes more and more sorted as the recursive calls are made, until finally the entire list is in correct order.

def quicksort(items, left=None, right=None):
    # By default, `left` and `right` span the entire range of `items`:
    if left is None:
        left = 0  # `left` defaults to the 0 index.
    if right is None:
        right = len(items) - 1  # `right` defaults to the last index.

print('\nquicksort() called on this range:', items[left:right + 1])
    print('................The full list is:', items)

if right <= left:
        return  # BASE CASE

# START OF THE PARTITIONING
    i = left  # i starts at the left end of the range.
    pivotValue = items[right]  # Select the last value for the pivot.

print('....................The pivot is:', pivotValue)

# Iterate up to, but not including, the pivot:
    for j in range(left, right):
        # If a value is less than the pivot, swap it so that it's on the
        # left side of `items`:
        if items[j] <= pivotValue:
            # Swap these two values:
            items[i], items[j] = items[j], items[i]
            i += 1

# Put the pivot on the left side of `items`:
    items[i], items[right] = items[right], items[i]
    # END OF THE PARTITIONING

print('....After swapping, the range is:', items[left:right + 1])
    print('Recursively calling quicksort on:', items[left:i], 'and', items[i + 1:right + 1])

# Call quicksort() on the two partitions:
    quicksort(items, left, i - 1)   # RECURSIVE CASE
    quicksort(items, i + 1, right)  # RECURSIVE CASE

myList = [0, 7, 6, 3, 1, 2, 5, 4]
quicksort(myList)
print('Sorted:', myList)

The output of this program looks like this:

quicksort() called on this range: [0, 7, 6, 3, 1, 2, 5, 4]
................The full list is: [0, 7, 6, 3, 1, 2, 5, 4]
....................The pivot is: 4
....After swapping, the range is: [0, 3, 1, 2, 4, 7, 5, 6]
Recursively calling quicksort on: [0, 3, 1, 2] and [7, 5, 6]

quicksort() called on this range: [0, 3, 1, 2]
................The full list is: [0, 3, 1, 2, 4, 7, 5, 6]
....................The pivot is: 2
....After swapping, the range is: [0, 1, 2, 3]
Recursively calling quicksort on: [0, 1] and [3]

quicksort() called on this range: [0, 1]
................The full list is: [0, 1, 2, 3, 4, 7, 5, 6]
....................The pivot is: 1
....After swapping, the range is: [0, 1]
Recursively calling quicksort on: [0] and []

quicksort() called on this range: [0]
................The full list is: [0, 1, 2, 3, 4, 7, 5, 6]

quicksort() called on this range: []
................The full list is: [0, 1, 2, 3, 4, 7, 5, 6]

quicksort() called on this range: [3]
................The full list is: [0, 1, 2, 3, 4, 7, 5, 6]

quicksort() called on this range: [7, 5, 6]
................The full list is: [0, 1, 2, 3, 4, 7, 5, 6]
....................The pivot is: 6
....After swapping, the range is: [5, 6, 7]
Recursively calling quicksort on: [5] and [7]

quicksort() called on this range: [5]
................The full list is: [0, 1, 2, 3, 4, 5, 6, 7]

quicksort() called on this range: [7]
................The full list is: [0, 1, 2, 3, 4, 5, 6, 7]
Sorted: [0, 1, 2, 3, 4, 5, 6, 7]

Shortest Possible Recursive Function

Download shortest.py

For a demonstration, this is the shortest possible recursive function. It is merely a function that calls itself. It will result in a stack overflow error.

The output of this program looks like this:

Sierpinski Carpet

Download sierpinskiCarpet.py

The sierpinski carpet is a square with an empty center and fractal sierpinski carpets in the eight perimeter areas of the square.

import turtle
turtle.tracer(10, 0) # Increase the first argument to speed up the drawing.
turtle.setworldcoordinates(0, 0, 700, 700)
turtle.hideturtle()

MIN_SIZE = 6 # Try changing this to decrease/increase the amount of recursion.
DRAW_SOLID = True

def isTooSmall(width, height):
    # Determine if the rectangle is too small to draw.
    return width < MIN_SIZE or height < MIN_SIZE

def drawCarpet(x, y, width, height):
    # The x and y are the lower left corner of the carpet.

# Move the pen into position.
    turtle.penup()
    turtle.goto(x, y)

# Draw the outer rectangle.
    turtle.pendown()
    if DRAW_SOLID:
        turtle.fillcolor('black')
        turtle.begin_fill()
    turtle.goto(x, y + height)
    turtle.goto(x + width, y + height)
    turtle.goto(x + width, y)
    turtle.goto(x, y)
    if DRAW_SOLID:
        turtle.end_fill()
    turtle.penup()

# Draw the inner rectangles.
    drawInnerRectangle(x, y, width, height)

def drawInnerRectangle(x, y, width, height):
    if isTooSmall(width, height):
        # BASE CASE
        return
    else:
        # RECURSIVE CASE

oneThirdWidth = width / 3
        oneThirdHeight = height / 3
        twoThirdsWidth = 2 * (width / 3)
        twoThirdsHeight = 2 * (height / 3)

# Move into position.
        turtle.penup()
        turtle.goto(x + oneThirdWidth, y + oneThirdHeight)

# Draw the inner rectangle.
        if DRAW_SOLID:
            turtle.fillcolor('white')
            turtle.begin_fill()
        turtle.pendown()
        turtle.goto(x + oneThirdWidth, y + twoThirdsHeight)
        turtle.goto(x + twoThirdsWidth, y + twoThirdsHeight)
        turtle.goto(x + twoThirdsWidth, y + oneThirdHeight)
        turtle.goto(x + oneThirdWidth, y + oneThirdHeight)
        turtle.penup()
        if DRAW_SOLID:
            turtle.end_fill()

# Draw the inner rectangles across the top.
        drawInnerRectangle(x, y + twoThirdsHeight, oneThirdWidth, oneThirdHeight)
        drawInnerRectangle(x + oneThirdWidth, y + twoThirdsHeight, oneThirdWidth, oneThirdHeight)
        drawInnerRectangle(x + twoThirdsWidth, y + twoThirdsHeight, oneThirdWidth, oneThirdHeight)

# Draw the inner rectangles across the middle.
        drawInnerRectangle(x, y + oneThirdHeight, oneThirdWidth, oneThirdHeight)
        drawInnerRectangle(x + twoThirdsWidth, y + oneThirdHeight, oneThirdWidth, oneThirdHeight)

# Draw the inner rectangles across the bottom.
        drawInnerRectangle(x, y, oneThirdWidth, oneThirdHeight)
        drawInnerRectangle(x + oneThirdWidth, y, oneThirdWidth, oneThirdHeight)
        drawInnerRectangle(x + twoThirdsWidth, y, oneThirdWidth, oneThirdHeight)

drawCarpet(50, 50, 600, 600)
turtle.exitonclick()

The output of this program looks like this:

Sierpinski Triangle

Download sierpinskiTriangle.py

The sierpinski triangle is an equilateral triangle that contains three sierpinski triangles. It looks like the triforce from Zelda video games.

import turtle
turtle.tracer(100, 0) # Increase the first argument to speed up the drawing.
turtle.setworldcoordinates(0, 0, 700, 700)
turtle.hideturtle()

MIN_SIZE = 4 # Try changing this to decrease/increase the amount of recursion.

# Calculate midpoints between points A, B, and C.
        mid_ab = midpoint(ax, ay, bx, by)
        mid_bc = midpoint(bx, by, cx, cy)
        mid_ca = midpoint(cx, cy, ax, ay)

# Draw an equilateral Sierpinski triangle.
drawTriangle(50, 50, 350, 650, 650, 50)

# Draw a skewed Sierpinski triangle.
#drawTriangle(30, 250, 680, 600, 500, 80)

turtle.exitonclick()

The output of this program looks like this:

Towers of Hanoi

Download towerOfHanoiSolver.py

The Tower of Hanoi is a puzzle involving a tower of stacked disks. The puzzle begins with the largest disk on the bottom and the disk sizes decrease going up. The disks have a hole in their center so they can be stacked on top of each other through a pole. To solve the puzzle, the player must move the stack of disks from one pole to another while following three rules:

The player can move only one disk at a time.
The player can only move disks to and from the top of a tower.
The player can never place a larger disk on top of a smaller disk.

# Set up towers A, B, and C. The end of the list is the top of the tower.
TOTAL_DISKS = 6

# Populate Tower A:
TOWERS = {'A': list(reversed(range(1, TOTAL_DISKS + 1))),
          'B': [],
          'C': []}

def printDisk(diskNum):
    # Print a single disk of width diskNum.
    emptySpace = ' ' * (TOTAL_DISKS - diskNum)
    if diskNum == 0:
        # Just draw the pole.
        print(emptySpace + '||' + emptySpace, end='')
    else:
        # Draw the disk.
        diskSpace = '@' * diskNum
        diskNumLabel = str(diskNum).rjust(2, '_')
        print(emptySpace + diskSpace + diskNumLabel + diskSpace + emptySpace, end='')

def printTowers():
    # Print all three towers.
    for level in range(TOTAL_DISKS, -1, -1):
        for tower in (TOWERS['A'], TOWERS['B'], TOWERS['C']):
            if level >= len(tower):
                printDisk(0)
            else:
                printDisk(tower[level])
        print()
    # Print the tower labels A, B, and C.
    emptySpace = ' ' * (TOTAL_DISKS)
    print('%s A%s%s B%s%s C\n' % (emptySpace, emptySpace, emptySpace, emptySpace, emptySpace))

def moveOneDisk(startTower, endTower):
    # Move the top disk from startTower to endTower.
    disk = TOWERS[startTower].pop()
    TOWERS[endTower].append(disk)

def solve(numberOfDisks, startTower, endTower, tempTower):
    # Move the top numberOfDisks disks from startTower to endTower.
    if numberOfDisks == 1:
        # BASE CASE
        moveOneDisk(startTower, endTower)
        printTowers()
        return
    else:
        # RECURSIVE CASE
        solve(numberOfDisks - 1, startTower, tempTower, endTower)
        moveOneDisk(startTower, endTower)
        printTowers()
        solve(numberOfDisks - 1, tempTower, endTower, startTower)
        return

# Solve
printTowers()
solve(TOTAL_DISKS, 'A', 'B', 'C')

# Uncomment to enable interactive mode:
#while True:
#    printTowers()
#    print('Enter letter of start tower and the end tower. (A, B, C) Or Q to quit.')
#    move = input().upper()
#    if move == 'Q':
#        sys.exit()
#    elif move[0] in 'ABC' and move[1] in 'ABC' and move[0] != move[1]:
#        moveOneDisk(move[0], move[1])

The output of this program looks like this:

||            ||            ||
     @_1@           ||            ||
    @@_2@@          ||            ||
   @@@_3@@@         ||            ||
  @@@@_4@@@@        ||            ||
 @@@@@_5@@@@@       ||            ||
@@@@@@_6@@@@@@      ||            ||
       A             B             C

||            ||            ||
      ||            ||            ||
    @@_2@@          ||            ||
   @@@_3@@@         ||            ||
  @@@@_4@@@@        ||            ||
 @@@@@_5@@@@@       ||            ||
@@@@@@_6@@@@@@      ||           @_1@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
   @@@_3@@@         ||            ||
  @@@@_4@@@@        ||            ||
 @@@@@_5@@@@@       ||            ||
@@@@@@_6@@@@@@    @@_2@@         @_1@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
   @@@_3@@@         ||            ||
  @@@@_4@@@@        ||            ||
 @@@@@_5@@@@@      @_1@           ||
@@@@@@_6@@@@@@    @@_2@@          ||
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
  @@@@_4@@@@        ||            ||
 @@@@@_5@@@@@      @_1@           ||
@@@@@@_6@@@@@@    @@_2@@       @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@           ||            ||
  @@@@_4@@@@        ||            ||
 @@@@@_5@@@@@       ||            ||
@@@@@@_6@@@@@@    @@_2@@       @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@           ||            ||
  @@@@_4@@@@        ||            ||
 @@@@@_5@@@@@       ||          @@_2@@
@@@@@@_6@@@@@@      ||         @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
  @@@@_4@@@@        ||           @_1@
 @@@@@_5@@@@@       ||          @@_2@@
@@@@@@_6@@@@@@      ||         @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||           @_1@
 @@@@@_5@@@@@       ||          @@_2@@
@@@@@@_6@@@@@@  @@@@_4@@@@     @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
 @@@@@_5@@@@@      @_1@         @@_2@@
@@@@@@_6@@@@@@  @@@@_4@@@@     @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
    @@_2@@          ||            ||
 @@@@@_5@@@@@      @_1@           ||
@@@@@@_6@@@@@@  @@@@_4@@@@     @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@           ||            ||
    @@_2@@          ||            ||
 @@@@@_5@@@@@       ||            ||
@@@@@@_6@@@@@@  @@@@_4@@@@     @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@           ||            ||
    @@_2@@          ||            ||
 @@@@@_5@@@@@    @@@_3@@@         ||
@@@@@@_6@@@@@@  @@@@_4@@@@        ||
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
    @@_2@@          ||            ||
 @@@@@_5@@@@@    @@@_3@@@         ||
@@@@@@_6@@@@@@  @@@@_4@@@@       @_1@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||          @@_2@@          ||
 @@@@@_5@@@@@    @@@_3@@@         ||
@@@@@@_6@@@@@@  @@@@_4@@@@       @_1@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||           @_1@           ||
      ||          @@_2@@          ||
 @@@@@_5@@@@@    @@@_3@@@         ||
@@@@@@_6@@@@@@  @@@@_4@@@@        ||
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||           @_1@           ||
      ||          @@_2@@          ||
      ||         @@@_3@@@         ||
@@@@@@_6@@@@@@  @@@@_4@@@@   @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||          @@_2@@          ||
     @_1@        @@@_3@@@         ||
@@@@@@_6@@@@@@  @@@@_4@@@@   @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@        @@@_3@@@       @@_2@@
@@@@@@_6@@@@@@  @@@@_4@@@@   @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||           @_1@
      ||         @@@_3@@@       @@_2@@
@@@@@@_6@@@@@@  @@@@_4@@@@   @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||           @_1@
   @@@_3@@@         ||          @@_2@@
@@@@@@_6@@@@@@  @@@@_4@@@@   @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
   @@@_3@@@        @_1@         @@_2@@
@@@@@@_6@@@@@@  @@@@_4@@@@   @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
    @@_2@@          ||            ||
   @@@_3@@@        @_1@           ||
@@@@@@_6@@@@@@  @@@@_4@@@@   @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@           ||            ||
    @@_2@@          ||            ||
   @@@_3@@@         ||            ||
@@@@@@_6@@@@@@  @@@@_4@@@@   @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@           ||            ||
    @@_2@@          ||            ||
   @@@_3@@@         ||        @@@@_4@@@@
@@@@@@_6@@@@@@      ||       @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
    @@_2@@          ||           @_1@
   @@@_3@@@         ||        @@@@_4@@@@
@@@@@@_6@@@@@@      ||       @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||           @_1@
   @@@_3@@@         ||        @@@@_4@@@@
@@@@@@_6@@@@@@    @@_2@@     @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
   @@@_3@@@        @_1@       @@@@_4@@@@
@@@@@@_6@@@@@@    @@_2@@     @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||         @@@_3@@@
      ||           @_1@       @@@@_4@@@@
@@@@@@_6@@@@@@    @@_2@@     @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||         @@@_3@@@
     @_1@           ||        @@@@_4@@@@
@@@@@@_6@@@@@@    @@_2@@     @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||          @@_2@@
      ||            ||         @@@_3@@@
     @_1@           ||        @@@@_4@@@@
@@@@@@_6@@@@@@      ||       @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||           @_1@
      ||            ||          @@_2@@
      ||            ||         @@@_3@@@
      ||            ||        @@@@_4@@@@
@@@@@@_6@@@@@@      ||       @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||           @_1@
      ||            ||          @@_2@@
      ||            ||         @@@_3@@@
      ||            ||        @@@@_4@@@@
      ||      @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||          @@_2@@
      ||            ||         @@@_3@@@
      ||           @_1@       @@@@_4@@@@
      ||      @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||         @@@_3@@@
      ||           @_1@       @@@@_4@@@@
    @@_2@@    @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||         @@@_3@@@
     @_1@           ||        @@@@_4@@@@
    @@_2@@    @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@        @@@_3@@@     @@@@_4@@@@
    @@_2@@    @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||           @_1@
      ||         @@@_3@@@     @@@@_4@@@@
    @@_2@@    @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||          @@_2@@         @_1@
      ||         @@@_3@@@     @@@@_4@@@@
      ||      @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||           @_1@           ||
      ||          @@_2@@          ||
      ||         @@@_3@@@     @@@@_4@@@@
      ||      @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||           @_1@           ||
      ||          @@_2@@          ||
      ||         @@@_3@@@         ||
  @@@@_4@@@@  @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||          @@_2@@          ||
     @_1@        @@@_3@@@         ||
  @@@@_4@@@@  @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@        @@@_3@@@       @@_2@@
  @@@@_4@@@@  @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||           @_1@
      ||         @@@_3@@@       @@_2@@
  @@@@_4@@@@  @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||           @_1@
   @@@_3@@@         ||          @@_2@@
  @@@@_4@@@@  @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
   @@@_3@@@        @_1@         @@_2@@
  @@@@_4@@@@  @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
    @@_2@@          ||            ||
   @@@_3@@@        @_1@           ||
  @@@@_4@@@@  @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@           ||            ||
    @@_2@@          ||            ||
   @@@_3@@@         ||            ||
  @@@@_4@@@@  @@@@@@_6@@@@@@ @@@@@_5@@@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@           ||            ||
    @@_2@@          ||            ||
   @@@_3@@@    @@@@@_5@@@@@       ||
  @@@@_4@@@@  @@@@@@_6@@@@@@      ||
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
    @@_2@@          ||            ||
   @@@_3@@@    @@@@@_5@@@@@       ||
  @@@@_4@@@@  @@@@@@_6@@@@@@     @_1@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||          @@_2@@          ||
   @@@_3@@@    @@@@@_5@@@@@       ||
  @@@@_4@@@@  @@@@@@_6@@@@@@     @_1@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||           @_1@           ||
      ||          @@_2@@          ||
   @@@_3@@@    @@@@@_5@@@@@       ||
  @@@@_4@@@@  @@@@@@_6@@@@@@      ||
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||           @_1@           ||
      ||          @@_2@@          ||
      ||       @@@@@_5@@@@@       ||
  @@@@_4@@@@  @@@@@@_6@@@@@@   @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||          @@_2@@          ||
     @_1@      @@@@@_5@@@@@       ||
  @@@@_4@@@@  @@@@@@_6@@@@@@   @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
     @_1@      @@@@@_5@@@@@     @@_2@@
  @@@@_4@@@@  @@@@@@_6@@@@@@   @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||           @_1@
      ||       @@@@@_5@@@@@     @@_2@@
  @@@@_4@@@@  @@@@@@_6@@@@@@   @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||        @@@@_4@@@@       @_1@
      ||       @@@@@_5@@@@@     @@_2@@
      ||      @@@@@@_6@@@@@@   @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||           @_1@           ||
      ||        @@@@_4@@@@        ||
      ||       @@@@@_5@@@@@     @@_2@@
      ||      @@@@@@_6@@@@@@   @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||           @_1@           ||
      ||        @@@@_4@@@@        ||
      ||       @@@@@_5@@@@@       ||
    @@_2@@    @@@@@@_6@@@@@@   @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||        @@@@_4@@@@        ||
     @_1@      @@@@@_5@@@@@       ||
    @@_2@@    @@@@@@_6@@@@@@   @@@_3@@@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||         @@@_3@@@         ||
      ||        @@@@_4@@@@        ||
     @_1@      @@@@@_5@@@@@       ||
    @@_2@@    @@@@@@_6@@@@@@      ||
       A             B             C

||            ||            ||
      ||            ||            ||
      ||            ||            ||
      ||         @@@_3@@@         ||
      ||        @@@@_4@@@@        ||
      ||       @@@@@_5@@@@@       ||
    @@_2@@    @@@@@@_6@@@@@@     @_1@
       A             B             C

||            ||            ||
      ||            ||            ||
      ||          @@_2@@          ||
      ||         @@@_3@@@         ||
      ||        @@@@_4@@@@        ||
      ||       @@@@@_5@@@@@       ||
      ||      @@@@@@_6@@@@@@     @_1@
       A             B             C

||            ||            ||
      ||           @_1@           ||
      ||          @@_2@@          ||
      ||         @@@_3@@@         ||
      ||        @@@@_4@@@@        ||
      ||       @@@@@_5@@@@@       ||
      ||      @@@@@@_6@@@@@@      ||
       A             B             C

Tree Fractal

Download fractalTree.py

Trees can be algorithmically generated as a fractal. These trees are generated by having each branch produce two more similar but smaller branches.

import random
import time
import turtle
turtle.tracer(1000, 0) # Increase the first argument to speed up the drawing.
turtle.setworldcoordinates(0, 0, 700, 700)
turtle.hideturtle()

def drawBranch(startPosition, direction, branchLength):
    if branchLength < 5:
        # BASE CASE
        return

# Go to the starting point & direction.
    turtle.penup()
    turtle.goto(startPosition)
    turtle.setheading(direction)

# Draw the branch (thickness is 1/7 the length).
    turtle.pendown()
    turtle.pensize(max(branchLength / 7.0, 1))
    turtle.forward(branchLength)

# Record the position of the branch's end.
    endPosition = turtle.position()
    leftDirection = direction + LEFT_ANGLE
    leftBranchLength = branchLength - LEFT_DECREASE
    rightDirection = direction - RIGHT_ANGLE
    rightBranchLength = branchLength - RIGHT_DECREASE

# RECURSIVE CASE
    drawBranch(endPosition, leftDirection, leftBranchLength)
    drawBranch(endPosition, rightDirection, rightBranchLength)

seed = 0
while True:
    # Get psuedorandom numbers for the branch properties.
    random.seed(seed)
    LEFT_ANGLE     = random.randint(10,  30)
    LEFT_DECREASE  = random.randint( 8,  15)
    RIGHT_ANGLE    = random.randint(10,  30)
    RIGHT_DECREASE = random.randint( 8,  15)
    START_LENGTH   = random.randint(80, 120)

# Write out the seed number.
    turtle.clear()
    turtle.penup()
    turtle.goto(10, 10)
    turtle.write('Seed: %s' % (seed))

# Draw the tree.
    drawBranch((350, 10), 90, START_LENGTH)
    turtle.update()
    time.sleep(2)

seed = seed + 1

The output of this program looks like this:

Learn More About Recursion

To learn how these programs work and learn more about recursion in general, you can check out my book, The Recursive Book of Recursion. You can get an ebook copy for free when you buy a print book from the publisher, No Starch Press.

What is a Python Generator? (Implementing Your Own range() Function)

2021-09-24T12:00:00-04:00

Generators in Python (also called generator functions) are used to create a series of values one at a time. Let's learn how they work by re-creating the built-in range() function. This can keep your program from requiring the large amounts of memory needed if you generated all the values in the series at once. For example, in Python 2 running for i in range(1000000): the range() function would create and return a list with one million integers in it. This takes up a large amount of memory even though the for loop only needs one integer at a time. This was fixed in Python 3, where range() now produces one integer at a time. Generator functions let you create one value at a time with any sort of data, not just ranges of integers.

If you find yourself creating a large list of values with, say, a list comprehension or for loop, but you only need one value at a time, you should consider using a generator instead. This is especially true if you are creating large lists with hundreds of thousands of items or more. Using a generator is like using the readline() method to read a text file one line at a time, instead of using the read() method to read in the entire file all at once.

As a side note, generator functions return generator objects and generator objects are iterables. (Iterables are beyond the scope of this blog post, but see The Iterator Protocol: How "For Loops" Work in Python for more details.)

You can download a single .py file of all the examples from whatIsAGenerator.py. This blog post assumes you have a basic beginner's level of understanding of Python.

First, let's take a look at a regular function that you're already familiar with:

### A regular function:
def aRegularFunction(param):
    print('Hello', param)
    return 42

print("Calling aRegularFunction('Alice'):")
returnedValue = aRegularFunction('Alice')
print('Returned value:', returnedValue)

When you run this code, the output looks like this:

Calling aRegularFunction('Alice'):
Hello Alice
Returned value: 42

This is familiar and unsurprising. A function takes arguments for its parameters, runs some code, and then returns some return value.

Now let's take a look at a generator function. You can tell a function is a generator function because it'll have the yield keyword somewhere in the function body:

### A generator (aka generator function):
def aGeneratorFunction(param):
    print('Hello', param)
    yield 42
    print('How are you,', param)
    yield 99
    print('Goodbye', param)
    return 86  # Raises StopIteration with value 86.

print("Calling aGeneratorFunction('Bob'):")
generatorObj = aGeneratorFunction('Bob')  # Does not run the code, but returns a generator object.
print('Calling next():')
yieldedValue = next(generatorObj)
print('Yielded value:', yieldedValue)
print('Calling next():')
yieldedValue = next(generatorObj)
print('Yielded value:', yieldedValue)
print('Calling next():')
try:
    next(generatorObj)
except StopIteration as excObj:
    print('type(excObj) is', type(excObj))
    print('excObj.value is', excObj.value)
    print('type(excObj.value) is', type(excObj.value))

When you run this code, the output looks like this:

Calling aGeneratorFunction('Bob'):
Calling next():
Hello Bob
Yielded value: 42
Calling next():
How are you, Bob
Yielded value: 99
Calling next():
Goodbye Bob
type(excObj) is <class 'StopIteration'>
excObj.value is 86
type(excObj.value) is <class 'int'>

What you need to know is that one does not simply call a generator function. Calling a generator function does not run it's code. Instead, calling a generator function returns a generator object. You can see this in the interactive shell:

>>> aGeneratorFunction('Eve')
<generator object aGeneratorFunction at 0x0000013470179580>

To run the code inside a generator function, you must call Python's built-in next() function and pass it the generator object. This will run the code up until a yield statement, which acts like a return statement and makes the next() call return a value. The next time next() is called, the execution resumes from the yield statement with all the same values for the local variables.

When a return statement is reached, the generator function raises a StopIteration exception. Usually there's no value returned, but if so it is set to the exception object's value attribute.

The next() function usually isn't used with generators, but rather the generator function is used in a for loop. On each iteration, the for loop sets the loop variable to the yielded value. The StopIteration exception tells the for loop that the generator object has exhausted its values. For example:

### Using a generator function with a for loop or list() call:
for yieldedValue in aGeneratorFunction('Carol'):
    print('Yielded value:', yieldedValue)

listOfGeneratedValues = list(aGeneratorFunction('David'))
print('List of generated values:', listOfGeneratedValues)

When you run this code, the output looks like this:

Hello Carol
Yielded value: 42
How are you, Carol
Yielded value: 99
Goodbye Carol
Hello David
How are you, David
Goodbye David
List of generated values: [42, 99]

Rememebr that generators are mainly used to generate a series of values, but one at a time. Let's use an example of a Fibonacci sequence number generator. The Fibonacci sequence begins with 0 and 1, and then the next number in the sequence is the sum of the previous two numbers: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, and so on.

A generator can produce these numbers (up to a given maximum) one at a time. This generator can be used with a for loop or a list() call:

### A practical example of a generator using the Fibonacci sequence:
def fibonacciSequence(maxNum=50):
    a = 0
    b = 1
    yield a
    yield b
    while True:
        a, b = b, b + a
        if b >= maxNum:
            return b  # Raise StopIteration.
        else:
            yield b


for fibNum in fibonacciSequence():
    print('Next number in the Fibonacci sequence:', fibNum)


fibNumsUpTo500 = list(fibonacciSequence(500))
print('List of fib numbers up to 500:', fibNumsUpTo500)

When you run this code, the output looks like this:

Next number in the Fibonacci sequence: 0
Next number in the Fibonacci sequence: 1
Next number in the Fibonacci sequence: 1
Next number in the Fibonacci sequence: 2
Next number in the Fibonacci sequence: 3
Next number in the Fibonacci sequence: 5
Next number in the Fibonacci sequence: 8
Next number in the Fibonacci sequence: 13
Next number in the Fibonacci sequence: 21
Next number in the Fibonacci sequence: 34
List of fib numbers up to 500: [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377]

To summarize, Python generators look like functions that contain the yield keyword. They're used for producing a series of values one at a time so that your program doesn't consume a lot of memory by producing all the values at once. When a generator function is called, it doesn't run the code inside it but rather returns a generator object. This generator object can be passed to the built-in next() function. This runs the code in the generator function up until a yield statement (which gives a value for next() to return) or a return statement (which raises the StopIteration to signal that there are no more values to generate). However, generators are usually used in for loops, which automatically handle them.

That's it! Generators aren't all that complicated. I recommend you learn about iterables and iterators in general by checking out Trey Hunner's blog post, The Iterator Protocol: How "For Loops" Work in Python.

Implementing Your Own range() Function

Let's put our knowledge to the test by creating our own range() function. Instead of for i in range(10):, we'll be able to use for i in mySimpleImplementationOfRange(10):. We'll use a generator function that takes a single integer argument, and yields values starting from 0 up to but not including the argument:

### Using generator functions to re-implement range():
def mySimpleImplementationOfRange(stop):
    i = 0
    while i < stop:
        yield i
        i += 1
    return  # Raise StopIteration.

for i in mySimpleImplementationOfRange(5):
    print(i)

When you run this code, the output looks like this:

Of course, the range() function is a bit more complicated than that. It can take up to three arguments to specify a starting integer, stopping integer, and a "step" integer to indicate how much the yielded integers should change by. Also, range() only accepts integer arguments and the step argument cannot be 0. A fuller implementation is below:

### Using generator functions for a more complete range() re-implementation:
def myImplementationOfRange(firstParam, secondParam=None, thirdParam=None):
    if secondParam is None:
        if not isinstance(firstParam, int):
            raise TypeError("'" + firstParam.__class__.__name__ + "' object cannot be interpreted as an integer")
        start = 0
        stop = firstParam
        step = 1
    elif thirdParam is None:
        if not isinstance(secondParam, int):
            raise TypeError("'" + secondParam.__class__.__name__ + "' object cannot be interpreted as an integer")
        start = firstParam
        stop = secondParam
        step = 1
    else:
        if not isinstance(thirdParam, int):
            raise TypeError("'" + thirdParam.__class__.__name__ + "' object cannot be interpreted as an integer")
        if thirdParam == 0:
            raise ValueError('myImplementationOfRange() arg 3 must not be zero')
        start = firstParam
        stop = secondParam
        step = thirdParam

    i = start
    if step > 0:  # step arg is increasing
        while i < stop:
            yield i
            i += step
        return i
    elif step < 0:  # step arg is decreasing
        while i > stop:
            yield i
            i += step  # Adding a negative to decrease
        return i

for i in myImplementationOfRange(4, 12, 2):
    print(i)

When you run this code, the output looks like this:

There's a bit more to it than that, as range is actually a class which implements several dunder methods (which you can learn about from Nina Zakharenko's PyCon 2018 talk, Elegant Solutions for Everyday Python Problems. But now you can see how something like Python's built-in range() is implemented.

Recursion Is Not A Superpower: An Iterative Ackermann

2021-09-05T12:00:00-04:00

This post has the Python code for the infamously recursive Ackermann function, but without using recursion. Many people think that recursive algorithms hold some special power that can do computations beyond the reach of iterative algorithms. But recursion is not a superpower: there's nothing you can do with recurison that you can't do with a loop and a stack.

This blog post contains information from Al Sweigart's next book, The Recursive Book of Recurson from No Starch Press. The book will be released in February 2022. You can use the discount code PREORDERRECURSION to get 30% off your preorder, and receive the ebook free when you buy a print book. This book will also be freely available under a Creative Commons license on the Invent with Python website. Al Sweigart also gave a conference talk on recursion at North Bay Python 2018 titled, Recursion for Beginners: A Beginner's Guide to Recursion.

A stack is one of the simplest data structures in computing. It stores multiple values like a list or an array does, but unlike lists or arrays, it limits you to adding to or removing values from the “top” of the stack only. Adding values is called pushing values onto the stack, while removing values is called popping values off the stack.

The call stack is a stack data structure your programming language's compiler or interpreter uses to keep track of where in your program the execution should return to when a function call finishes. When your program calls a function, this return address information is pushed onto the stack. When the function call returns, the information is popped off the stack. If your function call makes a function call which makes another function call, you'll have three things pushed onto the call stack.

Recursion is confusing for beginner because instructors and tutorials often don't explicitly explain what the call stack is. The call stack is managed by the compiler or interpreter automatically in the background. You can't point to a place in your source code and say, "this is the call stack" like you can with other variables. This makes the call stack an invisible gap in the understanding of students.

Recursive functions use the call stack as their stack data structure, but you can use a list or array as a stack data structure by restricting yourself to adding or removing things only from the end. For example, Python's append() and pop() list methods are effectively the "push" and "pop" operations to treat a Python list as a stack.

There is nothing special about recursion. Anything you can do with recursion can be done with a loop and a stack. Further, recursion is not automatically more "elegant" than an iterative solution. Quite the opposite: recursion is often produces overengineered and less readable code than a straightforward iterative solution.

To prove this, I'll use the famous Ackermann recursive function as an example. The Ackermann function doesn't have much practical use aside from an example of a recursive function that is extremely recursive. Even small inputs to this function can result in an amount of computation that takes years or lifetimes to finish. Here's the code to the recursive Ackermann function in Python:

def ackermann(m, n):
    if m == 0:
        # BASE CASE
        return n + 1
    elif m > 0 and n == 0:
        # RECURSIVE CASE
        return ackermann(m - 1, 1)
    elif m > 0 and n > 0:
        # RECURSIVE CASE
        return ackermann(m - 1, ackermann(m, n - 1))

For example, calling ackermann(1, 1) will take less than a second to complete. Calling ackermann(4,1) will take a couple minutes. But calling ackermann(15, 20) will take longer than the universe has existed to finish calculating. The Ackermann function becomes untennable very quickly.

But recursion is not a superpower. Even Ackermann, one the most recursive of recursive functions, can be written with a loop and a stack. Here's an iterative Ackermann implementation in Python:

print('Starting with m = 2, n = 3:')
callStack = [{'m': 2, 'n': 3, 'indentation': 0, 'instrPtr': 'start'}]
returnValue = None

while len(callStack) != 0:
    m = callStack[-1]['m']
    n = callStack[-1]['n']
    indentation = callStack[-1]['indentation']
    instrPtr = callStack[-1]['instrPtr']

    if instrPtr == 'start':
        print('%sackermann(%s, %s)' % (' ' * indentation, m, n))

        if m == 0:
            # BASE CASE
            returnValue = n + 1
            callStack.pop()
            continue
        elif m > 0 and n == 0:
            # RECURSIVE CASE
            callStack[-1]['instrPtr'] = 'after first recursive case'
            callStack.append({'m': m - 1, 'n': 1, 'indentation': indentation + 1, 'instrPtr': 'start'})
            continue
        elif m > 0 and n > 0:
            # RECURSIVE CASE
            callStack[-1]['instrPtr'] = 'after second recursive case, inner call'
            callStack.append({'m': m, 'n': n - 1, 'indentation': indentation + 1, 'instrPtr': 'start'})
            continue
    elif instrPtr == 'after first recursive case':
        returnValue = returnValue
        callStack.pop()
        continue
    elif instrPtr == 'after second recursive case, inner call':
        callStack[-1]['innerCallResult'] = returnValue
        callStack[-1]['instrPtr'] = 'after second recursive case, outer call'
        callStack.append({'m': m - 1, 'n': returnValue, 'indentation': indentation + 1, 'instrPtr': 'start'})
        continue
    elif instrPtr == 'after second recursive case, outer call':
        returnValue = returnValue
        callStack.pop()
        continue
print(returnValue)

Try running both programs. You'll see that they produce identical output. But the iterative version doesn't use recursive functions. In fact, it doesn't use functions at all: there's no def statement anywhere in the program.

If you find recursion confusing or wonder why you "should" use recursion, don't despair. Recursion is an inappropriate approach just as often as it is appropriate (or even more). Just remember that recursion, while a useful technique that every programmer should understand, is not a superpower.

If you'd like to learn how to use recursion, check out Al Sweigart's upcoming book, The Recursive Book of Recursion from No Starch Press. This book will also be freely available under a Creative Commons license on the Invent with Python website. Al Sweigart also gave a conference talk on recursion at North Bay Python 2018 titled, Recursion for Beginners: A Beginner's Guide to Recursion.

ccwd - A Copy Current Working Directory Command

2021-08-28T12:01:00-04:00

In 2008 I created a small program meant to be run from a terminal window called ccwd which copies the current working directory to the clipboard. While the standard Unix command pwd will print the working directory (that is, the current folder the terminal is in), this will copy it to the clipboard. I found myself using it all the time when I needed to get the directory that I was in.

Example usage in the Windows Command Prompt:

Microsoft Windows [Version 10.0.19043.1165]
(c) Microsoft Corporation. All rights reserved.

C:\Users\Al>cd Desktop

C:\Users\Al\Desktop>ccwd

C:\Users\Al\Desktop>

At this point, C:\Users\Al\Desktop would be copied to the clipboard and could easily be pasted into other apps. I have the C source code and Windows executable here. ccwd.exe does not produce any output, and returns 0 on success and a nonzero value on failure.

C source code for Windows

ccwd.exe executable program

I recommend placing the ccwd.exe file in the C:\Windows folder or someplace on the system PATH (i.e. one of the folders listed in your PATH environment variable).

UPDATE 2022/05/04: If you don't want to download the sketchy looking, unsigned .exe file from this page, you can download a batch file to use instead:

ccwd.bat batch file

The code in this batch file is easy enough to understand. It uses the Get-Location cmdlet for Powershell (preinstalled on Windows 7 SP1 and later) to get the current working directory and stores it in a temporary variable. Then it uses Set-Clipboard to put the contents of this variable on the clipboard.

TODO

pwd | tr -d '\n' | pbcopy

Algorithmic Art with the BitFieldDraw Module

2021-08-02T12:00:00-04:00

A bit field is a 2D image of black and white pixels. It's the simplest possible image. The pixels don't necessarily have to be black and white, but a bit field is limited to two colors because each pixel is represented by a bit: a 0 or 1 number. You can install it by running pip install --user bitfielddraw (on Windows) or pip3 install --user bitfielddraw (on macOS and Linux). In the interactive shell, run import bitfielddraw and bitfielddraw.main() to see a demo. (Maximize your terminal window for best effect.)

Despite this limitation, bit fields can be beautiful. I found this twitter thread (and MetaFilter discussion) that had several bit fields generated by simple mathematical functions. The functions are fed the X and Y coordinate of a pixel, and if the function returns a zero the pixel is white and if the function returns a nonzero the pixel is black. There are several interesting patterns that can be generated from simple functions:

Inspired by this, I've created a Python module called BitFieldDraw, which makes it easy to see the bit fields generated from a given function. You can from bitfielddraw import * and then call the save() (to save it to an image or text file), p() functions to print it to the terminal screen as block text characters, or s() (to show the image using the Pillow module).

The function that generates the art can be a Python lambda function such as lambda x, y: (x ^ y) % 5 or simply a string with the body of the lambda function such as '(x ^ y) % 5'.

The function (x ^ y) % 5 xor's (that is, exclusive or's) the x and y coordinates, then mods the result by 5. Let's use the coordinates (10, 19). This produces the operation (10 ^ 19) % 5. 10 and 19 are 01010 and 10011 in binary. When we xor them, we get 11001 or 25. 25 mod 5 is 0 (that is, 25 divided by 5 has a remainder of 0). Because 0 is a zero value, this produces a white pixel at the coordinates (10, 19).

The BitFieldDraw runs this calculation for every pixel in a 2D field to draw algorithmic art. Some examples:

>>> save('bitfield1.png', '(x ^ y) % 5', w=400, h=400)

>>> save('bitfield2.png', '(x * 64) % y', w=400, h=400)

>>> save('bitfield3.png', '(x % y) % 4', w=400, h=400)

>>> save('bitfield4.png', '(x & y) & (x ^ y) % 19', w=400, h=400)

When you save bit fields as image files, you can give them any two colors for the foreground and background colors:

>>> save('bitfield-color1.png', '(x & y) & (x ^ y) % 19', w=400, h=400, fg='red', bg='black')

>>> save('bitfield-color2.png', '(x & y) & (x ^ y) % 19', w=400, h=400, fg='yellow', bg='blue')

>>> save('bitfield-color3.png', '(x & y) & (x ^ y) % 19', w=400, h=400, fg='#004400', bg='green')

The first argument to p() print-function and s() save-function are an expression with x and y variables. The expression evaluates to the color for that pixel: black if zero and white if nonzero. The width and height of the bit field are automatically set to the size of the terminal window. Since text cells in terminal windows are twice as tall as they are wide, each text cell represents two pixel. However, other integers values can be passed for the w and h parameters to the functions to change the width and height.

Since text cells in terminal windows are twice as tall as they are wide, each text cell actually represents two pixels in one column and two rows. The text characters used are code points 9600 (just the top pixel set '▀'), 9604 (just the bottom pixel set '▄'), and 9608 (both pixels set '█'). For both pixels being clear, we use a space character ' '.

The 0, 0 origin of the bit field is set to the bottom left corner. The origin can be changed by passing integers to the x and y parameters.

>>> p('(x^y)%5', w=10, h=10)
██▀▄██▄▀▀▄
██▄▀██▀▄▄▀
▄▀██▀▄████
██▀▄██▄▀▀▄
▀▄██▄▀████
>>> p('(x^y)%5', w=10, h=10, x=2)
▀▄██▄▀▀▄██
▄▀██▀▄▄▀██
██▀▄████▄▀
▀▄██▄▀▀▄██
██▄▀████▀▄
>>> p('(x^y)%5', w=10, h=10, y=2)
▀▄██▄▀████
██▀▄██▄▀▀▄
██▄▀██▀▄▄▀
▄▀██▀▄████
██▀▄██▄▀▀▄

Unlike computer screen coordinates, the bitfielddraw module uses mathematics coordinates so that the Y coordinates increase going up, not down. You can change this by passing flipy=True to any of the BitFieldDraw functions, in which case the y coordinates will increase going down. You can also pass flipx=True to flip the x coordinates. (Currently there's no way to rotate the bit fields.)

>>> p('(x^y)%5', w=10, h=10)
██▀▄██▄▀▀▄
██▄▀██▀▄▄▀
▄▀██▀▄████
██▀▄██▄▀▀▄
▀▄██▄▀████
>>> p('(x^y)%5', w=10, h=10, flipx=True)
▄▀▀▄██▄▀██
▀▄▄▀██▀▄██
████▄▀██▀▄
▄▀▀▄██▄▀██
████▀▄██▄▀
>>> p('(x^y)%5', w=10, h=10, flipy=True)
▄▀██▀▄████
██▄▀██▀▄▄▀
▀▄██▄▀████
██▀▄██▄▀▀▄
██▄▀██▀▄▄▀
>>> p('(x^y)%5', w=10, h=10, flipx=True, flipy=True)
████▄▀██▀▄
▀▄▄▀██▀▄██
████▀▄██▄▀
▄▀▀▄██▄▀██
▀▄▄▀██▀▄██

If you'd like to swap the colors used, you can pass True for the invert parameter:

>>> p('(x^y)%5', w=10, h=10)
██▀▄██▄▀▀▄
██▄▀██▀▄▄▀
▄▀██▀▄████
██▀▄██▄▀▀▄
▀▄██▄▀████
>>> p('(x^y)%5', w=10, h=10, invert=True)
  ▄▀  ▀▄▄▀
  ▀▄  ▄▀▀▄
▀▄  ▄▀
  ▄▀  ▀▄▄▀
▄▀  ▀▄

You can also get the string of the bit field directly with getBitFieldStr():

>>> import bitfielddraw
>>> bitfielddraw.printBitFieldStr('(x ^ y) % 5', w=10, h=10)  # This is the same as the p() function.
██▀▄██▄▀▀▄
██▄▀██▀▄▄▀
▄▀██▀▄████
██▀▄██▄▀▀▄
▀▄██▄▀████
>>> bitfielddraw.getBitFieldStr('(x ^ y) % 5', w=10, h=10)
'██▀▄██▄▀▀▄\n██▄▀██▀▄▄▀\n▄▀██▀▄████\n██▀▄██▄▀▀▄\n▀▄██▄▀████'

getBitField(), getBitFieldStrFromSet(), and getBitFieldImgFromSet

If you'd like to get the raw data of the bit field, you can call getBitField() which will return a frozen set of (x, y) tuples. From this, you can make changes to the data and then pass it to getBitFieldStrFromSet() or getBitFieldImgFromSet() to get a string or Pillow image object of the modified bit field.

>>> import bitfielddraw
>>> bitFieldData = bitfielddraw.getBitField(lambda x, y: (x^y)%5, width=20, height=20)
>>> bitFieldData
frozenset({(7, 17), (18, 17), (8, 0), (19, 0), (8, 9), (19, 9), (11, 5), (8, 18), (19, 18), (0, 14), (4, 2), (3, 15), (14, 15), (15, 7), (7, 3), (18, 3), (15, 16), (7, 12), (8, 4), (19, 4), (11, 0), (0, 9), (11, 9), (3, 1), (3, 10), (14, 10), (3, 19), (14, 19), (15, 2), (15, 11), (18, 7), (7, 16), (18, 16), (10, 8), (10, 17), (3, 5), (14, 5), (3, 14), (15, 6), (18, 2), (7, 11), (6, 15), (10, 3), (10, 12), (2, 17), (3, 0), (14, 0), (14, 9), (3, 18), (14, 18), (6, 10), (6, 19), (10, 7), (2, 3), (10, 16), (2, 12), (3, 4), (17, 6), (9, 11), (6, 5), (6, 14), (10, 2), (10, 11), (2, 16), (16, 18), (17, 1), (5, 8), (17, 10), (17, 19), (9, 15), (6, 0), (10, 6), (2, 11), (1, 15), (13, 17), (16, 13), (5, 3), (9, 1), (5, 12), (17, 14), (9, 10), (9, 19), (6, 4), (6, 13), (13, 3), (1, 10), (13, 12), (16, 8), (1, 19), (16, 17), (17, 0), (5, 7), (17, 9), (9, 5), (5, 16), (9, 14), (12, 15), (1, 5), (16, 3), (13, 16), (16, 12), (5, 2), (17, 4), (9, 0), (5, 11), (0, 18), (12, 1), (12, 10), (4, 6), (12, 19), (4, 15), (1, 0), (1, 9), (13, 11), (16, 7), (1, 18), (5, 6), (19, 8), (0, 4), (19, 17), (0, 13), (11, 13), (12, 5), (12, 14), (4, 10), (4, 19), (16, 2), (1, 13), (8, 3), (19, 3), (19, 12), (8, 12), (0, 8), (11, 8), (0, 17), (11, 17), (12, 0), (4, 5), (15, 1), (7, 6), (15, 19), (7, 15), (18, 15), (0, 3), (11, 3), (19, 16), (8, 16), (0, 12), (11, 12), (12, 4), (4, 0), (4, 9), (3, 13), (14, 13), (7, 1), (18, 1), (15, 14), (7, 10), (18, 10), (18, 19), (19, 2), (8, 11), (19, 11), (0, 7), (11, 7), (0, 16), (11, 16), (3, 8), (14, 8), (3, 17), (14, 17), (15, 9), (7, 5), (18, 5), (15, 18), (7, 14), (18, 14), (19, 6), (0, 2), (11, 2), (14, 3), (14, 12), (15, 4), (7, 0), (18, 0), (15, 13), (7, 9), (18, 9), (10, 1), (2, 6), (2, 15), (3, 7), (14, 7), (3, 16), (17, 18), (7, 4), (18, 4), (6, 8), (6, 17), (2, 1), (10, 14), (2, 10), (2, 19), (3, 2), (14, 2), (3, 11), (17, 13), (9, 18), (10, 9), (2, 5), (10, 18), (2, 14), (14, 6), (9, 4), (9, 13), (6, 7), (6, 16), (10, 4), (2, 0), (10, 13), (2, 9), (13, 6), (2, 18), (13, 15), (16, 11), (5, 1), (17, 3), (17, 12), (9, 8), (5, 19), (9, 17), (6, 2), (6, 11), (2, 4), (13, 1), (1, 8), (13, 10), (16, 6), (1, 17), (16, 15), (17, 7), (5, 14), (17, 16), (12, 13), (4, 18), (1, 3), (13, 5), (16, 1), (1, 12), (13, 14), (16, 10), (16, 19), (17, 2), (5, 9), (17, 11), (9, 7), (5, 18), (6, 1), (12, 8), (12, 17), (4, 13), (13, 0), (1, 7), (13, 9), (16, 5), (1, 16), (13, 18), (5, 4), (9, 2), (5, 13), (8, 6), (8, 15), (19, 15), (0, 11), (4, 8), (4, 17), (1, 2), (13, 4), (16, 0), (7, 18), (8, 1), (19, 1), (8, 10), (0, 6), (11, 6), (8, 19), (11, 15), (12, 7), (4, 3), (12, 16), (4, 12), (1, 6), (15, 8), (18, 13), (8, 5), (19, 5), (0, 1), (8, 14), (19, 14), (11, 10), (0, 19), (11, 19), (12, 2), (12, 11), (4, 7), (15, 3), (15, 12), (18, 8)})

(Currently, getBitFieldStrFromSet() isn't implemented.)

Examples

BitFieldDraw comes with several examples in its EXAMPLES member:

>>> import bitfielddraw
>>> import pprint
>>> pprint.pprint(bitfielddraw.EXAMPLES)
('(x ^ y) % 5',
 '(x ^ y) % 9',
 '(x ^ y) % 17',
 '(x ^ y) % 33',
 '(x ^ y) % 2',
 '(x ^ y) % 4',
 '(x ^ y) % 8',
 '(x | y) % 7',
 '(x | y) % 17',
 '(x | y) % 29',
 '(x * y) & 64',
 '(x * y) & 24',
 '(x * y) & 47',
 '(x ^ y) < 77',
...

You can view a slideshow of these examples by running bitfielddraw.main(). I recommend maximizing your terminal window for the largest view.

Book Review: The Charisma Machine by Morgan G. Ames

2021-07-10T12:01:00-04:00

Five stars. Ames' The Charisma Machine covers the emperor-wears-no-clothes story of the One Laptop Per Child project, and how the technical gurus of MIT's famed Media Group set out to change the world and got it so wrong.

I remember the OLPC project. I followed news of it in the late 2000s and could get behind the idea; create a $100 laptop and give it to poor kids across the Global South and encourage them to learn to program. I loved the idea, because I had the same upbringing as the OLPC promoters who loved the idea. I was one of those kids who taught themselves how to program, making little video games in the BASIC programming language. This interest led me to major in computer science and then on to a successful career in Silicon Valley. So I thought these kids would teach themselves to program, express their creativity in code, develop a curiosity and an internal motivation to learn, become highly paid software engineers and tech entrepreneurs and Make The World A Better Place TM.

OLPC is a classic story of Silicon Valley hubris by way of MIT's famed Media Lab, but Ames does a fantastic job of dissecting the missteps, grand delusions, and false presumptions that went into constructing this fiasco. This is a book for several audiences: educators, policy makers, social workers, or even just jaded techies like me who gasp with relief that someone else has pulled back the curtain on these so-called wizards.

Ames uses the term "technically precocious boy" to identify the archetype that many in the OLPC project would identify with and, consciously or not, identify their targeted laptop-recipients as. I certainly was one of these "gifted" boys (and they were overwhelmingly boys) who taught himself to program at a young age by making little video games. I was independent, had a curiosity to learn outside of school, and had general anti-authority streak. Or at least I liked to think I did. Like the members behind OLPC, I was rather blind to the privileges I had: growing up with a PC and even internet access in the 90s and parents who encouraged my computing interest.

So I am especially primed to fall under the charisma of the One Laptop Per Child's cheap XO laptops. All these poor kids need is a laptop, and they'll follow the same path that I did and have successful careers and bring economic prosperity to their home countries and the world at large, right? Socioeconomic problems like poverty and lack of opportunity are hard; a quick, cheap technical fix can seem like a miracle. If that sounds too good to be true, it's because it is.

Not that the OLPC was a scam, but it did have some cult-like features. The charisma of the backers such as Nicholas Negroponte, who also had the connections to bring in funding and code contributions from open source volunteers, was overwhelming. The input of actual teachers, social workers, and local community organizers was glossed over, as was tracking the actual effectiveness of the program.

Ames spent months in Paraguay in the actual communities that were recipients of OLPC laptops, cataloguing the experience of students and teachers. She also saw firsthand the many shortcomings of these laptops. Some of these were simple: classrooms often didn't have enough electric outlets or power strips to sustain everyone's laptop. But some were large: kids mainly used the laptops, not for creative expression, but just to consume media on the internet. They more often played video games than programmed them.

I lived in Silicon Valley for over a decade and I've personally seen the strain of naivety of these tech-based utopian vision. Some guy will claim that he's going to teach JavaScript to homeless people and solve poverty. They never have any previous experience in education or social work, but this doesn't matter. After a few weeks, they, and the internet audience enrapture by their first blog post announcement, lose interest and quietly move on to their next venture. The One Laptop Per Child project was this, scaled up into millions of dollars spent by project funders and recipient governments, along with the countless time of open source volunteers, local teachers, parents, and the students themselves. In the end, the time and money would have been better spent on more conventional, but not-so-charismatic, educational programs.

Ames' The Charisma Machine is a cautionary tale that is important to read for anyone who follows developments in the tech industry. These institutions and companies frequently make grand claims of innovation and salvation. I, for one, appreciate Ames' efforts to expose these hollow proclamations and her guidance on how to avoid repeating their mistakes in the future.

Combinations and Permutations in Python with itertools

2021-07-03T12:01:00-04:00

(The following information and more can be found from my upcoming, to-be-announced book on recursive algorithms. I'll update this post when the book is released in 2022.)

If you a list, dictionary, or other iterable object of values you need to generate combinations and permutations from, Python has the built-in itertools module as part of its standard library. The permutations of an iterable are every possible ordering of all of the values, while the combinations are every possible selection of some, none, or all of the values. For example, the permutations and combinations of the set {'A', 'B', 'C'} are:

Permutations	Combinations
ABC, ACB, BAC, BCA, CAB	(none), A, B, C, AB, AC, BC, ABC

You can also reuse the values multiple times, which is called permutations with repetition and combinations with repetition (also called replacement):

Permutations with Repetition	Combinations with Repetition
AAA, AAB, AAC, ABA, ABB, ABC, ACA, ACB, ACC, BAA, BAB, BAC, BBA, BBB, BBC, BCA, BCB, BCC, CAA, CAB, CAC, CBA, CBB, CBC, CCA, CCB, CCC	(none), A, B, C, AA, AB, AC, BB, BC, CC, AAA, AAB, AAC, ABB, ABC, ACC, BBB, BBC, BCC, CCC

(Note that permutations with repetition is effectively the same as a password cracker that tries every possible combination of characters to brute force a password.)

The number of permutations and combinations quickly grows when more values are added to the iterable object. The total number of permutations and combinations is given in the following:

	Permutations of n Values	Combinations of n Values
Without Repetition	n!	2^n
With Repetition	n^n	"2n choose n", that is, (2n)! / (n!)^2

But to have Python generate permutations, you can use itertools.permutations():

>>> import itertools
>>> for v in itertools.permutations(['A', 'B', 'C']):
...   print(v)
...
('A', 'B', 'C')
('A', 'C', 'B')
('B', 'A', 'C')
('B', 'C', 'A')
('C', 'A', 'B')
('C', 'B', 'A')
>>>
>>> list(itertools.permutations(['A', 'B', 'C']))
[('A', 'B', 'C'), ('A', 'C', 'B'), ('B', 'A', 'C'), ('B', 'C', 'A'), ('C', 'A', 'B'), ('C', 'B', 'A')]


>>> list(itertools.permutations(['A', 'B', 'C'], 2))
[('A', 'B'), ('A', 'C'), ('B', 'A'), ('B', 'C'), ('C', 'A'), ('C', 'B')]
>>> list(itertools.permutations(['A', 'B', 'C'], 1))
[('A',), ('B',), ('C',)]

To have Python generate combinations, you can use itertools.combinations():

>>> import itertools
>>> for v in itertools.combinations(['A', 'B', 'C'], 2):
...   print(v)
...
('A', 'B')
('A', 'C')
('B', 'C')


>>> list(itertools.combinations(['A', 'B', 'C'], 1))
[('A',), ('B',), ('C',)]
>>> list(itertools.combinations(['A', 'B', 'C'], 2))
[('A', 'B'), ('A', 'C'), ('B', 'C')]
>>> list(itertools.combinations(['A', 'B', 'C'], 3))
[('A', 'B', 'C')]

Note that the combinations() function takes a second argument for the number of values to select. To get all combinations (also called the power set), you'll need to make multiple calls to combinations():

>>> powerSet = []
>>> import itertools
>>> for k in range(4):
...   powerSet.extend(itertools.combinations(['A', 'B', 'C'], k))
...
>>> powerSet
[(), ('A',), ('B',), ('C',), ('A', 'B'), ('A', 'C'), ('B', 'C'), ('A', 'B', 'C')]

To get permutations with repetition/replacement, call itertools.product() and pass the size of the iterable object for its repeat argument:

>>> import itertools
>>> for v in itertools.product(['A', 'B', 'C'], repeat=3):
...   print(v)
...
('A', 'A', 'A')
('A', 'A', 'B')
('A', 'A', 'C')
('A', 'B', 'A')
('A', 'B', 'B')
('A', 'B', 'C')
('A', 'C', 'A')
('A', 'C', 'B')
('A', 'C', 'C')
('B', 'A', 'A')
('B', 'A', 'B')
('B', 'A', 'C')
('B', 'B', 'A')
('B', 'B', 'B')
('B', 'B', 'C')
('B', 'C', 'A')
('B', 'C', 'B')
('B', 'C', 'C')
('C', 'A', 'A')
('C', 'A', 'B')
('C', 'A', 'C')
('C', 'B', 'A')
('C', 'B', 'B')
('C', 'B', 'C')
('C', 'C', 'A')
('C', 'C', 'B')
('C', 'C', 'C')
>>> list(itertools.product(['A', 'B', 'C'], repeat=3))
[('A', 'A', 'A'), ('A', 'A', 'B'), ('A', 'A', 'C'), ('A', 'B', 'A'), ('A', 'B', 'B'), ('A', 'B', 'C'), ('A', 'C', 'A'), ('A', 'C', 'B'), ('A', 'C', 'C'), ('B', 'A', 'A'), ('B', 'A', 'B'), ('B', 'A', 'C'), ('B', 'B', 'A'), ('B', 'B', 'B'), ('B', 'B', 'C'), ('B', 'C', 'A'), ('B', 'C', 'B'), ('B', 'C', 'C'), ('C', 'A', 'A'), ('C', 'A', 'B'), ('C', 'A', 'C'), ('C', 'B', 'A'), ('C', 'B', 'B'), ('C', 'B', 'C'), ('C', 'C', 'A'), ('C', 'C', 'B'), ('C', 'C', 'C')]

To get combinations with repetition/replacement, call itertools.combinations_with_replacement():

>>> import itertools
>>> for v in itertools.combinations_with_replacement(['A', 'B', 'C'], 3):
...   print(v)
...
('A', 'A', 'A')
('A', 'A', 'B')
('A', 'A', 'C')
('A', 'B', 'B')
('A', 'B', 'C')
('A', 'C', 'C')
('B', 'B', 'B')
('B', 'B', 'C')
('B', 'C', 'C')
('C', 'C', 'C')
>>> list(itertools.combinations_with_replacement(['A', 'B', 'C'], 3))
[('A', 'A', 'A'), ('A', 'A', 'B'), ('A', 'A', 'C'), ('A', 'B', 'B'), ('A', 'B', 'C'), ('A', 'C', 'C'), ('B', 'B', 'B'), ('B', 'B', 'C'), ('B', 'C', 'C'), ('C', 'C', 'C')]

If you're like me and you had trouble remembering the differences between permutations and combinations, with and without repetition, and which Python functions implement them, bookmark this page to have easy access in the future.

New Book: The Big Book of Small Python Projects

2021-06-26T12:01:00-04:00

My new book, The Big Book of Small Python Projects, is now available from No Starch Press. You can get the ebook for free when you purchase a print book from No Starch Press. Or you can buy the book off Amazon.

Read "The Big Book of Small Python Projects" online for free.

This book contains 81 small but complete programming projects written in Python. These projects are designed to help new programmers who have learned the basics see what real programs "look like". These aren't code snippets, but actual, full programs that you can run. At the same time, they are small enough so that their source code is easy to understand.

Watch this book's video trailer created by the author.

Episode 64 of the Teaching Python Podcast discusses the book.

If you've followed some basic Python tutorials but feel like programming hasn't quite "clicked" yet, this is the book to read. Or, if you are new to programming but adventureous enough to just dive into code, these programs are simple enough to be understood to new programmers as well.

Many of these projects come from my old "STDIO game jam" projects in this git repo on GitHub. You can also find the source code of the programs in the book in the downoadable resources file on the No Starch Press page for the book.

Praise for The Big Book of Small Python Projects

"I've always been impressed by the variety of simple, but interesting and fun, projects Al can come up with and this collection takes that to the next level... Even experienced coders are likely to be pulled into browsing through the wide variety that Al has put into this book."
—Naomi Ceder, Fellow of the Python Software Foundation

"Al Sweigart presents fun programs, inspiring learners to tweak them. That's how I learned to program: tinkering with examples from books and magazines. It works!"
–Luciano Ramalho, Technical Principal at ThoughtWorks and author of Fluent Python

"Whether you're new to Python or want to exercise your coding brain, I recommend The Big Book of Small Python Projects to spark your thinking. Both the 'big' and the 'small' in the title are accurate. There are a lot of projects in this book, but most code takes up only a page or two. That makes it a fun reference book to get you into the flow or kick off a session in your terminal."
–Adam DuVander, Founder, EveryDeveloper

Project Descriptions

Project 1, Bagels: Deduce a secret three-digit number based on clues.
Project 2, Birthday Paradox: Determine the probability that two people share the same birthday in groups of different sizes.
Project 3, Bitmap Message: Display a message on the screen configured by a 2D bitmap image.
Project 4, Blackjack: A classic card game played against an AI dealer.
Project 5, Bouncing DVD Logo: Simulates the colorful bouncing DVD logo of decades past.
Project 6, Caesar Cipher: A simple encryption scheme used thousands of years ago.
Project 7, Caesar Hacker: A program to decrypt Caesar cipher messages without the encryption key.
Project 8, Calendar Maker: Create calendar pages for a given year and month.
Project 9, Carrot in a Box: A silly bluffing game between two players.
Project 10, Cho-Han: A gambling dice game from feudal Japan.
Project 11, Clickbait Headline Generator: A humorous headline generator for your content farm.
Project 12, Collatz Sequence: Explore the simplest impossible conjecture in mathematics.
Project 13, Conway’s Game of Life: The classic cellular automata whose simple rules produce complex emergent behavior.
Project 14, Countdown: A countdown timer with a seven-segment display.
Project 15, Deep Cave: A tunnel animation that descends endlessly into the earth.
Project 16, Diamonds: An algorithm for drawing diamonds of various sizes.
Project 17, Dice Math: A visual dice-rolling math game.
Project 18, Dice Roller: A tool for reading Dungeons & Dragons dice notation to generate random numbers.
Project 19, Digital Clock: A clock with a calculator-like display.
Project 20, Digital Stream: A scrolling screensaver that resembles The Matrix.
Project 21, DNA Visualization: An endless ASCII-art double helix that demonstrates the structure of DNA.
Project 22, Ducklings: Mix and match strings to create a variety of ASCII-art ducks.
Project 23, Etching Drawer: Move the cursor to create line drawings.
Project 24, Factor Finder: Find all the multiplicative factors of a number.
Project 25, Fast Draw: Test your reflexes to see if you’re the fastest keyboard in the West.
Project 26, Fibonacci: Generate numbers in the famous Fibonacci sequence.
Project 27, Fish Tank: A colorful, animated ASCII-art fish tank.
Project 28, Flooder: Attempt to fill the entire puzzle board with one color.
Project 29, Forest Fire Sim: Simulate the spread of wildfires through a forest.
Project 30, Four in a Row: A board game where two players try to connect four tiles in a row.
Project 31, Guess the Number: The classic number guessing game.
Project 32, Gullible: A humorous program to keep gullible people busy for hours.
Project 33, Hacking Minigame: Deduce a password based on clues.
Project 34, Hangman and Guillotine: The classic word guessing game.
Project 35, Hex Grid: Programmatically generate tiled ASCII art.
Project 36, Hourglass: A simple physics engine for falling sand.
Project 37, Hungry Robots: Avoid killer robots in a maze.
Project 38, J’Accuse!: A detective game to determine liars and truth-tellers.
Project 39, Langton’s Ant: A cellular automata whose ants move according to simple rules.
Project 40, Leetspeak: Translate English messages into l33t5p34]<.
Project 41, Lucky Stars: A push-your-luck dice game.
Project 42, Magic Fortune Ball: A program to answer your yes/no questions about the future.
Project 43, Mancala: The ancient two-player board game from Mesopotamia.
Project 44, Maze Runner 2D: Try to escape a maze.
Project 45, Maze Runner 3D: Try to escape a maze... in 3D!
Project 46, Million Dice Roll Statistics Simulator: Explore the probability results of rolling a set of dice one million times.
Project 47, Mondrian Art Generator: Create geometric drawings in the style of Piet Mondrian.
Project 48, Monty Hall Problem: A simulation of the Monty Hall game show problem.
Project 49, Multiplication Table: Display the multiplication table up to 12 × 12.
Project 50, Ninety-Nine Bottles: Display the lyrics to a repetitive song.
Project 51, niNety-nniinE BoOttels: Display the lyrics to a repetitive song that get more distorted with each verse.
Project 52, Numeral Systems Counters: Examine binary and hexadecimal numbers.
Project 53, Periodic Table of the Elements: An interactive database of chemical elements.
Project 54, Pig Latin: Translates English messages into Igpay Atinlay.
Project 55, Powerball Lottery: Simulate losing at the lottery thousands of times.
Project 56, Prime Numbers: Calculate prime numbers.
Project 57, Progress Bar: A sample progress bar animation to use in other programs.
Project 58, Rainbow: A simple rainbow animation.
Project 59, Rock Paper Scissors: The classic hand game for two players.
Project 60, Rock Paper Scissors (Always-Win Version): A version of the game where the player cannot lose.
Project 61, ROT13 Cipher: The simplest cipher for encrypting and decrypting text.
Project 62, Rotating Cube: A rotating cube animation.
Project 63, Royal Game of Ur: A 5,000-year-old game from Mesopotamia.
Project 64, Seven-Segment Display Module: A display like those used in calculators and microwave ovens.
Project 65, Shining Carpet: Programmatically generate the carpet from The Shining.
Project 66, Simple Substitution Cipher: An encryption scheme more advanced than the Caesar cipher.
Project 67, Sine Message: Display a scrolling wave message.
Project 68, Sliding Tile Puzzle: The classic four-by-four tile puzzle.
Project 69, Snail Race: Fast-paced snail racing action!
Project 70, Soroban Japanese Abacus: A computer simulation of a pre-computer calculating tool.
Project 71, Sound Mimic: Memorize an increasingly long pattern of sounds.
Project 72, sPoNgEcAsE: Translates English messages into sPOnGEcAsE.
Project 73, Sudoku Puzzle: The classic nine-by-nine newspaper deduction puzzle.
Project 74, Text-to-Speech Talker: Make your computer talk to you!
Project 75, Three-Card Monte: The tricky fast-swapping card game that scammers play on tourists.
Project 76, Tic-Tac-Toe: The classic two-player board game of Xs and Os.
Project 77, Tower of Hanoi: The classic disk- stacking puzzle.
Project 78, Trick Questions: A quiz of simple questions with misleading answers.
Project 79, Twenty Forty-Eight: A casual tile matching game.
Project 80, Vigenère Cipher: An encryption scheme so advanced it remained unbreakable for hundreds of years until computers were invented.
Project 81, Water Bucket Puzzle: Obtain exactly four liters of water by filling and emptying three buckets.

Al Sweigart's PyTennessee 2020 Opening Keynote

2021-03-07T12:00:00-05:00

In March 2020, just before the lockdowns would begin, I gave the opening keynote at PyTennessee 2020. Unfortunately, it wasn't recorded. But I still have the script I used and so I re-recorded the talk. I've posted it to my YouTube channel.

VIDEO: Al Sweigart's PyTennessee 2020 Opening Keynote

Below is a transcript from my speaker notes:

Hello, Community. Hello PyTennessee. Thank you for having me, thank you to all the conference organizers. I really appreciate all the efforts the organizers put into this conference. And thank all of you for attending PyTennessee. Thank you. I’ve never given a 9am talk before. It’s a bit earlier than I’m used to. Also, I realized on the flight here from Seattle, that timezone change meant that this more like a 7am talk for me. And that registration was at 6am, and I had to get up around 4:30 in the morning. So this could be a very interesting talk.

Hi. I’m Al Sweigart. I’m mostly known as the author of Automate the Boring Stuff with Python.

Thank you. I've never given a 9am talk before. It's a bit earlier than I'm used to. Also, I realized on the flight here from Seattle, that timezone change meant that this more like a 7am talk for me. And that registration was at 6am, and I had to get up around 4:30 in the morning. So this could be a very interesting talk.Hi. I'm Al Sweigart. I'm mostly known as the author of Automate the Boring Stuff with Python, a book for complete beginners which is available for free online under a Creative Commons license. Let me tell you about myself. I like cats, I like origami, and I absolutely hate telling the story of how I learned to program. I hate it. I just... can't stand it.

When I was in elementary school, a friend of mine found a book on programming games in a language called BASIC. I was pretty lucky that I grew up with a PC in the house.

Of course, back then computers typically only had about 700 PB memory, a 12 gigahertz quantum CPU, and the hard drive was only big enough to store three, maybe four simulated universes. You know, typical Commodore 64 type of computer.

I was really into Nintendo, so programming seemed really cool to me. After high school I majored in computer science, and then I became a software engineer, and I move to San Francisco, and then I started writing programming books and the fourth book I wrote was picked up by No Starch Press, and I now write books full time. I hate telling this story. It's a true story, but it's also an incredibly misleading one. I hate telling this story because people might hear it and think, "Well I didn't start programming in the third grade." or "I didn't have a computer growing up." or "I didn't major in computer science." or "I didn't go to college." or "I didn't do well at math". People get the misleading idea that in order to become a capable software developer, you need to have started young, born with a genius IQ, and had elite training. That's of course complete nonsense.

The part of my story that doesn't get told, is that the games I made weren't really that good. They were all derivatives of games I had copied from other people. I really only had one book that I learned programming from, and all of the others were technical manuals that were way over my head. I didn't have Wikipedia or search engines or YouTube tutorials. I knew like three other kids who were into programming and they didn't know much more than I did.

Programming is so much easier now. It's still hard, but there are more resources available, the languages are more readable, the tools and documentation and community are just so much better now compared to the 1990s. And we have the internet so we can reach all of these things. And so in the introduction of the second edition of my book, I wrote "Everything I learned about programming in the years between grade school and high school graduation could be learned today in about a dozen weekends. My head start wasn't really much of a head start."

But the expectations today are so much higher. When you say programming, people today think of self-driving cars or triple-A video game titles or social media websites with millions of users. No one's really impressed by Guess The Number when billion dollar tech companies are household names.

You've probably seen news stories that say something like, "These local teens may be the next Bill Gates, Mark Zuckerberg, Elon Musk, or some other white guy with rich parents." These stories are everywhere, you can find them by doing a news search for "whiz kid programmer". The articles never go into that much detail about the actual software these teenagers create. So I started digging and I noticed that the programs these whiz kids made... aren't great?

I don't mean to take away from their accomplishments, they are way ahead of most other kids and certainly ahead of me when I was their age. But mostly their programs are nice demos or re-creations of existing apps. They aren't geniuses or self-made millionaires, because producing actual software is so much more than just writing code. But that gets lost in these news stories about "whiz kids".

How about me? Was I one of these "whiz kids"? Well, I don't mean to brag but in high school my computer science teacher picked me and two other students to represent our high school at a city wide programming competition. Oooo.

So there were 3 of us on our school's team. There were 14 teams representing 14 high schools. We had 3 hours to solve 10 problems. The easiest problems were worth 1 point, the harder problems were worth more. At the end of a grueling three hours, our team scored 1 point. Yeah the programming language was C. And all the problems, except the first one, required reading input from a text file, and I didn't know how to do that. And neither did the two other kids on my team. We spent three hours reading help menus and documentation to try to figure out how to read text from a text file. And we got nowhere. So we could only answer the first question. But the thing is, we tied with or did better than 10 of the other schools. 11 out of 14 teams at this competition of hand-picked computer nerds scored 0 or 1 point.

(pause) How did I get here? How did I manage to become a software developer and write a popular programming book and get invited to give the opening keynote at a conference? How did I get here? Was I a bright and talented computer whiz kid? (Laughter) Sure I was.

I was lucky. I was lucky to grow up in a house that had a personal computer. I was lucky to have a friend who also grew up in a house with a PC and he showed me that BASIC programming book that luckily the school library had. I was lucky I had free time and no pressure so I could just explore programming and have fun making mediocre video games. I was lucky that no one got in my way, no one ever took a look at me, at my skin and my face and said "Mmmm, I don't think you'd be interested in that nerd stuff." I was lucky, and luck can strike anyone, but it can't strike everyone.

So, on a lighter note: I don't like putting pop culture references in my talks because, frankly, it gives away how old I am. But as a kid I had a VHS tape of, I mean, I had a blue ray disc, of this one science fiction movie from the 1970s. It's called, uh, Star Wars? (pause) Oh good, some of you have heard of it. It's a really quotable movie. "May the force be with you", if you've ever heard that, it's from this movie.

Anyway, there's a scene where a space wizard is teaching his apprentice how to use a laser sword. And he puts this helmet on the apprentice so he can't see, and he tells him to block shots with the laser sword using his magic powers instead of his eyes. And he does! He pulls that off. But then this other character says, "I call it luck." And the space wizard replies, "In my experience there's no such thing as luck." And I thought, "That's cool." Yeah. That's like me. I make my own luck. I'm a ten year old watching Star Wars and I know how the world works. You have to have talent and work hard and the best people rise to the top of our meritocracy.

(pause for laughter)

There's a saying that "luck favors the prepared", which implies that random chance and systemic factors don't play a significant role and talented, hard-working people are rewarded. And that's kind of true. But I discovered another saying, "Luck favors the supported." I got where I am today because I had a lot of support. Not everyone can be lucky, but everyone can be supported. But in order to do that, we need to create inclusive communities and lower the barriers to entry. We can't just use the same excuses of "people need to have a thicker skin" and "people need to earn their place in our community". That's not high standards, that's just hazing. We need to lower the barriers to entry, and if we can't lower these barriers, we need to smash them. We can't just hope that people find the right book and then everything falls into place and they become software developers giving keynotes.

Now, there's going to be some people watching this talk who'll think, "Oh brother. Al, this is programming language conference. Why are you talking about diversity and inclusion? Code doesn't care about your feelings, you SJW. Why can't you be objective and rational? You should be talking about algorithms or arguing why Python 3 sucks."

Why is diversity important? Let me tell you a story that takes place before the story of how I learned to program.

In 1985, Nintendo released the 8-bit Nintendo Entertainment System and Super Mario Brothers. This was the first video game I ever played and it directly lead to me wanting to learn how to program. But there were earlier video games.

In 1972, Atari released Pong which became immensely popular and introduced a wide audience to video games. Lots of companies started making their own knock offs of Pong with their own hardware. Atari released their own home console which had hundreds of game titles.

One of which was ET in 1983. This was based on the ET movie which was very popular at the time. But the game was rushed. The developers only had five and half weeks to make it so it could be released in time for Christmas. When it came out, people hated it. It was confusing, you weren't sure what you were supposed to do or where to go, the controls were bad, and it was just... boring. Compared to the beloved movie, the game was huge disappointment.

Not only that, ET is often cited as one of the worst video games of all time and one of the biggest commercial failures in video game history. And this was at a bad time for video games as an industry.

With so many companies making cheap knock offs, consumers were getting tired of expensive hardware and lousy games. Revenue for the industry fell from a peak of $3.2 billion in 1983, to $100 million two years later. That was a 97% drop for the entire industry. This was the Video Game Crash of 1983.

Arguably, what saved video games in the 1980s was Nintendo.

Microprocessors were more powerful by then and they could support better graphics, but Nintendo's success was so much more than that. It's a bit of a game design cliche to explain how the first level of Mario teaches you how to play Mario, but it's such a great story I have to go into it.

Okay, when you start playing, Mario begins on the left facing right. This makes it obvious that you're suppose to go right. Every Mario level is designed to go from left to right, so you always know what you're supposed to do to make progress.

Now you soon find a flashing question mark block, which grabs your interest. You want to go to it but then you encounter your first enemy, an angry-looking mushroom with feet. It's just one, this isn't a huge challenge. If you run into the angry mushroom, you die but that's fine because you start again at the beginning and haven't lost much ground.

Shortly after you hit another question block and a mushroom pops out of it. This mushroom moves right, falls off the ledge, bounces off the green pipe and changes direction towards Mario. This means you're almost guaranteed to run into it, even if you confuse it for another enemy that you're supposed to avoid. When Mario touches it, he grows bigger and more powerful, so you can tell it's a powerup. This one event teaches you a lot about how objects in this world behave: there are power ups, they move on their own, they are affected by gravity, they can collide with objects and change direction.

Next you jump over that green pipe, and then there's a slightly taller green pipe after it. In Super Mario Brothers, the longer you hold down the jump button, the higher Mario jumps. Then there's a third pipe that's even taller than the second pipe. It's fine if you mess up, the pipe isn't going anywhere. This lets you practice high jumping until you've mastered it and gotten over the third pipe. Which is good because right after the green pipe is a bottomless pit. You had practice, now comes the test. If you jump too early, you'll end up falling into the pit instead of landing on the other side.

So to keep that from happening, there's a hidden powerup block that you run into which makes you fall back down immediately instead of into the bottomless pit. Out pops another powerup that gives you an extra life. This not only keeps you from making a bad jump, but it teaches you that there are secret hidden blocks that you can run into in this game. There's tons of stuff like this in the first level. You didn't see this kind of careful design in Atari games.

The main game designer behind Mario and other classic Nintendo games is Shigeru Miyamoto. There's a great quote from an interview of his. He goes...

"Well, early on, the people who made video games, they were technologists, they were programmers, they were hardware designers. But I wasn't. I was a designer, I studied industrial design. I was an artist, I drew pictures."

The person who is arguably responsible for much of video gaming's comeback in the 1980s and made me and many others into programmers, wasn't a programmer. He didn't devise new algorithms or write a compiler or anything like that. This non-programmer's impact on the programming world is immeasurable.

Diversity is important, because different people bring different skills and perspectives. They'll also have different needs which necessitate a variety of invention. The world itself is a diverse place, and if your community is a monoculture, then it's going to have blindspots and an existential danger of being irrelevant.

The thing about barriers to entry is that they're often invisible. It's easy for us to look around this room and see the people who are here. But it's also easy to forget to look for the people who aren't here. Let me put this way: When Al Sweigart walks into a tech meetup, Al Sweigart see a lot of people who look like Al Sweigart. I'm biracial white and Asian, I'm a cisgender man, I'm straight, I'm able-bodied and I'm in my thirties and I speak English natively and I have a college degree and I have nerdy hobbies. When I tell people I'm a software developer, no one is surprised. I'm a quote-unquote "culture fit".

Of course, there's no rule that explicitly states some kinds of people are welcome and some aren't. But there doesn't need to be one. Exclusion happens anyway.

This is a problem that is both immense and subtle, and I'm sorry that I have to gloss over so many details for a one hour talk. But for folks who are sick of me rambling about wishy-washy feelings, let's go into some hardcore technical chops. Let's be objective and rational and logical, you know like true programmers are.

This is a computer simulation called the Parable of the Polygons by vi hart and nicky case. It's a story of how harmless choices can make a harmful world.

In this simulation are triangles and squares. And triangles and squares don't *dislike* each other, they just have a slight preference for being around people like them. Nothing wrong with that, right? If a shape has less than a third of their neighbors like them, they'll move to a random new place. This doesn't seem so bad. They're not moving away from people who are different, they just have a slight preference to move closer to people like themselves.

When we run this simulation, we end up with a society that is deeply segregated. Okay, at this point, we learn the error of our ways and we decrease that bias from 33% to 0%. Problem solved, right? Well no. When we run the simulation again, nobody moves. There's nothing that pushes for desegregation, so a segregated society stays segregated. If your solution is to say, "I don't even see differences in shapes. There's only one shape and that's polygon." That is not a neutral position to have. It's a position that maintains segregation. It's a pro-segregation stance.

But is that so bad? So what if nerdy programmers just want to hang out with other nerdy programmers? What's the harm? What do we lose? I don't see anything missing.

There is a way to turn a community from segregated to diverse. And that's to have just a slight bias against monoculture. To take active steps towards creating diversity. It doesn't have to be much. If we set the simulation so that shapes want to move if more than 80% of their neighbors are like them,

We completely undo the segregation that previously took place. Now there's also issues of tokenism and assimilation but this is a short talk and I'm almost at the end of it.

One of my nerdy interests is science fiction, specifically the cyberpunk genre of science fiction. Cyberpunk is usually about hackers, and "high tech, low life" kind of settings. Think about The Matrix, or Johnny Mnemonic. Actually that was a terrible movie, just think about The Matrix if you need an example of cyberpunk. (pause) Heh. Keanu Reeves has been in a lot of cyberpunk movies. Anyway.

The cyberpunk genre arguably began with William Gibson's novel Neuromancer in 1984, but my favorite cyberpunk novel is

Snow Crash by Neal Stephenson, published in 1992. Specifically I love this one scene that describes a programmer named Juanita working at a software company that's making a virtual reality version of the world wide web, and specifically she's working on making the faces of the avatars be able to convey emotion and expression. The book goes "But at this phase, the all-male society of bit-heads that made up the power structure of Black Sun Systems said that the face problem was trivial and superficial. It was, of course, nothing more than sexism, the especially virulent type espoused by male techies who sincerely believe that they are too smart to be sexists."

Neal Stephenson was commenting on the real-world tech industry 30 years ago. I think about this line, and I think about this tweet from Jessica McKellar, who was the PyCon Diversity Chair for a number of years, and she shows how PyCon went from having 1% of its talks by women to 40% in five years. Think about how little diversity in the tech industry has changed in the 30 years since Snow Crash, and think of how much can it change in 5 years if we actually take diversity seriously.

I'm just impatient. I take a look at the Mercury 7, the seven astronauts selected by NASA in the 1950s to be the first Americans in space. Notice something all seven have in common with each other? I mean, there's been plenty of astronauts who weren't white men. There's... no reason the Mercury 7 had to all be white men. They were all pilots but there were pilots who weren't white men back even before the 1950s. But I'm sure the American government had reasons for why 7 out of 7 of their astronauts white and male. It's just that those reasons were wrong. And dumb. So I'm impatient. There's no reason this disparity needed to exist in the 1950s in the space program and no reason it needs to exist today in tech. The excuses we give for it are wrong and dumb.

Opportunity and obstacle are not randomly distributed. There is a pattern to privilege. We're not all playing on a level field. Ask anyone, anyone, to describe life and they will you that life is 1) tough and 2) not fair. That's why it falls on us to make our communities more equitable. And I'm impatient. I want to see results. I don't want another 30 years of it being enough to just say, "We're an equal opportunity employer" and have nothing actually change.

Does this mean we have to lower our standards to increase diversity? No. PyCon continues to be awesome, it hasn't gotten worse, it sells out every year. The Python conference you are sitting in right now also sold out of tickets. We haven't lowered standards by making efforts to support and reach out to voices we haven't heard from before. Everyone should learn to code. It's awesome. It's fun as a hobby, you can write little scripts to automate stuff on your computer, and if you stick with it you can even make a career of it. That's something that should be available to everyone.

And we can make it available to everyone.

(breathe) So, that's big picture. Let me leave you with some smaller tips. My first PyCon was 2011 in Atlanta. Lovely town. They have an aquarium with a whale shark. I know, right? And since then I've learned a lot about how to make the most of PyCon.

First, the point of PyCon is to meet people. The talks are great, thank you for coming to mine, but they're also being recorded. Don't feel like you have to cut conversations with people short to make it to every single talk.

When you're chatting with a group of people, you naturally stand in a circle. Instead stand like pacman with an open space, so new people can join the discussion.

I love going to pycon because I see my friends from across the country, but I have to remind myself that I also should spend time talking to new people. Don't spend the entire conference hanging out exclusively with your friends. Or go ahead and hang out with your friends, but also introduce new people to them.

Don't eat alone. Conferences usually have breakfasts and lunches and dinners, go to those. Follow the pycon hashtag on twitter and ask if people are going out to eat somewhere at the end of the day, or organize your own group dinner plans with random strangers standing next to you. That happens all the time.

Business cards! You remembered to bring business cards, right? That's fine if you didn't, just make one in a text file on your phone's screen and let the other person take a photo of it. But when do you get business cards, order the minimum amount. I know it's cheaper if you buy 50,000 cards, but trust me, just order the minimum amount. Make sure it's white and not glossy so people can write on it. And only have public information about yourself. Somebody should be able to take a photo of your business card and post it on the internet, and you're fine with it. I don't have my home address or even phone number on my card. So I don't care who ends up with it. After receiving business cards, write down the circumstances that you met them. And when you get a business card from someone, quickly write down the circumstances and what you talked about with the person, so you'll remember it later.

And do follow up. Twitter is great for this. You don't have to post to Twitter, just sign up for an account and you can just follow people and casually reply to random stuff they talk about.

This is a last minute slide addition: wash your hands from time to time throughout the day. No reason I'm bringing this up. This has always been good advice at all conferences. Just... wash your hands.

And finally, there's the shirt color trick. You're in a room full of strangers, and you want to pick someone to talk to. Here's what you do. Think of a color. Find the closest person wearing a shirt of that color. Talk to that person.

Don't think about it, just go by shirt color, the more you think about it, the more your internal biases will choose who you do and do not speak to. Don't think about who you might get along with or who you might have stuff in common with. No, talk to someone truly random. Because when we talk to everyone, we include everyone. I hope you enjoy PyTenneessee 2020. Thank you very much for having me.

Calm Programming Video Series

2021-03-06T12:00:00-05:00

I've started a new video series of me silently coding a small game project from scratch. The Calm Programming series are meant to be coding videos that you can watch while playing the music of your choice. They aren't quite the same as tutorials: they don't have screen capture and aren't narrated, though you can turn on captions for some explanations.

The premiere episode is creating a text-based blackjack card game from scratch.

I'm pulling the projects from my collection of short, text-based games at this repo which will be featured in my upcoming book, "The Big Book of Small Python Projects" from No Starch Press.

I plan on making some improvements to the format based on my experience with the first episode: I'm going to lower the screen brightness to reduce glare, cover the phone camera's screen so it doesn't reflect off the laptop screen, changed the terminal windows font to be larger and a light gray, and show a demonstration of the completed game at the start of each episode. I'm welcome to new ideas or suggestions: al@inventwithpython.com.

Text Recognition in Python with pytesseract

2021-01-11T12:01:00-05:00

Extracting text as string values from images is called optical character recognition (OCR) or simply text recognition. This blog post tells you how to run the Tesseract OCR engine from Python. For example, if you have the following image stored in diploma_legal_notes.png, you can run OCR over it to extract the string of text.

' \n\n \n\nCLASS OF 2019!\n\nYOUR DIPLOMA GRANTS YOU MANY NEW\nPOWERS AND PRIVILEGES. THESE INCLUDE:\n\n+ YOU MAY NOW LEGALLY PERFORM\nMARRIAGES AND ARREST PEOPLE.\n\n+ IF YOU HAVE YOUR DIPLOMA WITH YOU,\nYOU CAN USE. GROCERY STORE EXPRESS\nLANES WITH ANY NUMBER OF ITEMS.\n\n+ ALL GRADUATES ARE ENTITLED To\nDELETE ONE WORD OF THEIR CHOICE.\nFROM THE OXFORD ENGUSH DICTIONARY.\n+ THE UNIVERSITY WILL MAIL YOU YOUR’\nWORKING LIGHTSABER WITHIN 6-8 WEEKS.\n* YOU CAN SEND MAIL WITHOUT STAMPS.\n+ YOU HAVE EARNED THE RIGHT TO\nCHALLENGE THE BRITISH ROYAL FAMILY\nTO TRIAL BY COMBAT. IF YOU DEFEAT\nTHEM ALL, THE THRONE |S YOURS.\n\n* YOU MAY NOL IGNORE. "DO NOT PET”\nWARNINGS ON AIRPORT SECURITY DOGS.\n\n= CONGRATULATIONS,\n\n \n\n \n\x0c'

Notice that the text recognition isn't quite perfect. The "CONGRATULATIONS" at the top is mistakenly placed at the bottom, the word "NOW" is recognized as "NOL", the word "IS" has a vertical pipe character "|" instead of a capital "I", and there seems to be some confusing punctuation marks added in. Cleaning up your OCR scans depends on your particular project. This blog post will simply show you the code to do OCR from Python.

Installing Tesseract

First, run pip install pytesseract. The pytesseract package is a Python wrapper for the Tesseract OCR engine. If you need help running pip, see A Quick Pip Guide or What Is Pip? A Guide for New Pythonistas.

At this point, if you tried to use the pytesseract module, you'd get a TesseractNotFoundError message that says, tesseract is not installed or it's not in your path. (You can learn about the PATH environment variable in Chapter 2 of my free book, Beyond the Basic Stuff with Python.) Let's install the Tesseract OCR engine itself next.

On Windows, you can download the installer for version 5.0.0 of Tesseract and run the installer. (To get the latest version of Tesseract, go to the Tesseract at UB Mannheim web page.)

On macOS, according to this article, you can install Tesseract with Brew by opening a Terminal window and running brew install tesseract --all-languages. You can also install Tesseract on macOS with MacPorts by running sudo port install Tesseract, then run sudo port install tesseract-eng to install the English language. For other languages, use the language codes listed in this link.

On Linux, Tesseract may already be installed. If it isn't, according to this article, you can run the following:

On Ubuntu, run sudo apt-get install tesseract-ocr and then sudo apt-get install tesseract-ocr-all to install all languages. You also need to install ImageMagick for its convert program by running sudo apt-get install imagemagick.

On Fedora, run sudo dnf install tesseract

On Manjaro, run sudo pacman -Syu tesseract

Installing Pillow

The pytesseract module also requires the Pillow module for Python. You can install with pip by running pip install pillow on Windows or pip3 install pillow on macOS and Linux.

Running Tesseract from Python

To extract text from an image file named image.png, run the following code:

import pytesseract as tess
from PIL import Image
img = Image.open('image.png')
text = tess.image_to_string(img)
print(text)

The recognized text in the image is returned as a string value from image_to_string().

Additional Resources

To see an example of all of these steps, check out this YouTube video: Image to Text with pytesseract

A Quick Pip Guide: How to Install Python Modules

2021-01-11T12:00:00-05:00

Pip is a package manager that installs third-party packages (such as PyAutoGUI, Matplotlib, or Pygame) from https://pypi.org/, the Python Package Index. For a more detailed blog post on how pip works, see What Is Pip? A Guide for New Pythonistas

On Windows, to install a module named module_name open a Command Prompt window and run:

pip install --user module_name

On macOS and Linux, pip is for the older Python 2 version, so you need to open a Terminal window and run pip3 instead. On Ubuntu Linux, pip doesn't come with the pre-installed version of Python. You'll need to install it by opening a Terminal window and running sudo apt-get install python3-pip. (This AskUbuntu question has more information.)

pip3 install --user module_name

(If you get a 'pip' is not recognized as an internal or external command, operable program or batch file. or pip3: command not found error message, then the folder that the pip tool is listed in must be added to the PATH environment variable. You can find out about hte command line and environment variables in Chapter 2: Environment Setup and the Command Line in my free book, Beyond the Basic Stuff with Python.

If you can run python or python3 from the terminal/command prompt window without errors, you can use Python itself to run pip by entering the following on Windows:

python -m pip install --user module_name

On macOS and Linux, run:

python3 -m pip install --user module_name

Remember to run pip or python from the command line (either Terminal or Command Prompt) and not from the Python interactive shell. The Python interactive shell will have the >>> prompt. However, you can run pip from the Python interactive shell by running the following Python code:

import sys, os; os.system(sys.executable + ' -m pip install --user module_name')

Note the space before the -m is required. Replace module_name with the name of the module you wish to install, but type everything else exactly as shown.

You can find packages to install by browsing PyPI, the Python Package Index, at https://pypi.org/

Installing the ComputerCraft Mod for Minecraft 1.16 (and later)

2020-12-24T12:00:00-05:00

My book, Coding with Minecraft covers the ComputerCraft mod for Minecraft and is free to read online. ComputerCraft adds programmable robot "turtles" to the Minecraft world, and you can write Lua programs to have the robots mine, build, farm, and craft automatically.

As of 2020, the original ComputerCraft mod only supports up to Minecraft 1.12. However, the ComputerCraft Tweaked mod is a fork of the original ComputerCraft project and supports later versions of Minecraft (up to version 1.16 as of 2020).

The Coding with Minecraft book's instructions for installing this mod are out of date, but this blog post explains how to install the ComputerCraft Tweaked mod. After installing this new mod, the rest of the Coding with Minecraft book is still valid and applicable.

You can also watch this video of the ComputerCraft installation process.

The steps are:

Download and run the Forge mod installer.
Download the ComputerCraft: Tweaked mod.
From the Minecraft launcher, create a new installation that uses the "release 1.16.4-forge-35.1.4" mod. (Or whichever version of Forge you downloaded.)
Play the new installation of Minecraft.
From the Minecraft start sceen, click Mods, then click Open Mods Folder.
Copy the CC: Tweaked jar file to this folder.
Restart Minecraft. Check that "3 mods loaded" appears in the lower left.
You are now ready to play Minecraft with the CC mod.

First, you need to download Forge (a mod that runs other mods, such as CC Tweaked). Open a web browser to https://files.minecraftforge.net/ and select the version of Minecraft you have (as of December 2020, I have 1.16.4) and click the Installer link underneath "Download Recommended". You can also click on Installer underneath "Download Latest". This version will have the latest bug fixes (but also might have new bugs). The Forge file will be named something like forge-1.16.4-35.1.4-installer.jar. (The 1.16.4 refers to that this is for Minecraft version 1.16.4, and the 35.1.4 refers to the version of Forge.)

The minecraftforge.net website looks like this:

Double-click the forge-1.16.4-35.1.4-installer.jar file to run it. It will look like this:

Make sure "Install Client" is checked, and click OK. When the Forge installer is done, the window will tell you the installation was successful:

Next, go to the CC: Tweaked page on the CurseForge.com website, click the Files tab, and download the "Main File". As of December 2020, this is cc-tweaked-1.16.4-1.94.0.jar. (The 1.16.4 refers to that this is for Minecraft version 1.16.4, and the 1.94.0 refers to the version of CC: Tweaked.)

Instead of using the ATLauncher program, you can now install mods using the regular Minecraft Launcher that comes with Minecraft. Start the Minecraft Launcher. It will look like this:

Click on the Installations tab. We will create a new installation for ComputerCraft Tweaked. Click the New button and the screen will look like this:

name your installation something like, "ComputerCraft Install" and for the version select "release 1.16.4-forge-35.1.4" (or whatever Forge download you installed). Finally, click Create.

Back on the Play tab, click on the dropdown in the lower left corner and select the new "ComputerCraft Install" install, then click the Play button.

You may get a warning window telling you that modded Minecraft isn't officially supported. You can check the "I understand the risks. Don't warn me again about this installation." and then click Play.

Minecraft's loading screen will look different when you run the Forge installation:

When Minecraft has finished loading, note that it says in the lower left that there are "2 mods loaded". These are the original Minecraft application and Forge. Click the Mods button. You should see two mods in the list: "Minecraft" and "Forge".

Click the "Open mods folder" button to open the mods folder and copy the cc-tweaked-1.16.4-1.94.0.jar there.

Exit out of Minecraft, then restart it. The start screen should now say "3 mods loaded" in the lower left.

If you click the Mods button, you can see the "CC: Tweaked" mod is now loaded.

You can now play Minecraft with the ComputerCraft mod. If you want to learn how to program Minecraft robots, you can read the full text of the Coding with Minecraft book at https://turtleappstore.com/book/

Two Weird Tricks to Help Learn the Git Command Line

2020-09-18T12:00:00-04:00

TL;DR: Open two terminal windows and run watch "git status" in one and watch "git log -oneline" in the other so you can get live feedback as you enter Git commands.

Version control is a necessary skill for all software developers, and GUI tools for a version control system like Git make Git easy to use. But you'll often only have access to a command line, so it's still important to learn Git's command line commands. Here's two tricks (invent by a programmer!) you can do to make learning and using the Git command line easier.

The git status command shows which files are unmodified, modified, or untracked while the git log --oneline command shows the first line of every commit message. This is useful information to have, and you'll constantly run these commands as you use Git.

To make this easier, you can have the watch command run these automatically. The watch command repeatedly runs a command you give it, refreshing the screen with the command's output. Open a new terminal window, and run watch "git status" to have an automatically updated view of the Git repo's status. In another terminal window, run watch "git log --oneline" to see a log that is automatically updated every time you commit changes.

(These tricks aren't weird, but I wanted to follow the clickbait headline template in an attempt at humor that will surely date this article.)

The watch command comes standard with macOS and Linux. However, you'll have to download watch.exe separately on Windows and place it in a folder in the system PATH. (If you don't know what that is, you can always place it in C:\Windows if you have an admin account.)

Free Coupon Codes for My Online Courses

2020-03-26T12:00:00-04:00

Hello! I've probably sent you this link after you've asked about getting a discount or free code to my online Udemy course, "Automate the Boring Stuff with Python". Unfortunately, in 2019 Udemy changed their promo code policy so that I'm severely limited in how often I can give codes out. In response, I've made the following link:

https://inventwithpython.com/automateudemy

This URL will always redirect you to the lowest price possible. For the first six days of each month, it redirects to the free codes that I make for the course. The rest of the month it redirects to a 70% discount code that lowers the price from $50 to about $14. This is the maximum discount I'm allowed to provide.

You can also view the first 15 of the 50 videos from the course on my YouTube channel with this link. If you like the course, please use the above link to purchase it.

Please do use the https://inventwithpython.com/automateudemy; I get a much higher percentage of the course fee when people use my link as opposed to finding the course on their own through the Udemy site.

If this link doesn't work for some reason, you can try to manually enter the code. Each month's $14 code is the month and year. For example, in 2020 the codes are JAN2020, FEB2020, MAR2020, APR2020, MAY2020, JUN2020, JUL2020, AUG2020, SEP2020, OCT2020, NOV2020, DEC2020. The free code (which only works from the 1st to the 3rd of each month) has the suffix "FREE": JAN2020FREE, FEB2020FREE, and so on. These free codes expire after 3 days, so from the 4th to the 6th the code is JAN2020FREE2, FEB2020FREE2, and so on.

Thanks for your interest in my course. However, I'm unable to make additional free codes aside from the ones outlined in this post. Please don't contact me repeatedly asking for free codes; you can watch the first 15 videos for free on YouTube and wait for the next month's free code period.

You can always read the book that the course is based on, as well as all of my programming books, for free on https://inventwithpython.com.

Reading Guide to Automate the Boring Stuff, Second Edition, for Readers of the First Edition

2019-12-31T12:00:00-05:00

The second edition of Automate the Boring Stuff with Python is now available online under a Creative Commons license. This book teaches programming to complete beginners with no previous experience. The first edition was published in 2015. This blog post outlines the new content in the second edition with links to the content online so that readers of the first edition can immediately find the new content.

You can also buy a print book from the publisher, No Starch Press, and receive PDF/Kindle/epub ebooks for free with purchase (something you won't get from Amazon).

There are many small edit throughout the book, but here are the new sections:

Introduction

You Are Not Too Old to Learn Programming - A short section to remind you that you're not too old to learn to program, just like you don't need to be good at math to program.
Downloading and Installing Mu - You can use IDLE (which comes with Python) to type your code

Chapter 1 - Python Basics

No new sections.

Chapter 2 - Flow Control

A Short Program: Guess the Number - Not new, but refined and moved from Chapter 3.
A Short Program: Rock, Paper, Scissors - An example rock, paper, scissors game.

Chapter 3 - Functions

The Call Stack - Understanding the call stack helps you develop a mental model for function calls and scopes.
A Short Program: Zigzag - A fun animation program.

Chapter 4 - Lists

Identity and the id() Function - The id() function can help develop your mental model of objects and references in Python.
A Short Program: Conway's Game of Life - The classic simple cellular automata program.
Coin Flip Streaks - A practice project to collect coin flip statistics.

Chapter 5 - Dictionaries and Structuring Data

Chess Dictionary Validator - A practice project to write code to ensure a dictionary for a chess board is well-formed.

Chapter 6 - Manipulating Strings

Project: Multi-Clipboard Automatic Messages - The "password locker" project has been changed to a similar "multi-clipboard" project, since I don't want to encourage readers to keep their passwords in plain text on their hard drives.
A Short Program: Pig Latin - A fun program to turn English into Pig Latin.
Zombie Dice Bots - A practice project to write bots to play a game called, "Zombie Dice"

Chapter 7 - Pattern Matching with Regular Expressions

Date Detection - A practice project to use regex to make sure date strings are properly formatted.

Chapter 8 - Input Validation

This entire chapter is new, and covers the PyInputPlus module.

Chapter 9 - Reading and Writing Files

Files and File Paths - This entire chapter has been rewritten to use the new pathlib module and Path objects for file paths.
Using the / Operator to Join Paths - The / operator can join Path objects.

Chapter 10 - Organizing Files

No new sections.

Chapter 11 - Debugging

Mu's Debugger - Since the second edition uses the Mu editor instead of IDLE, the debugging chapter covers Mu's debugger.

Chapter 12 - Web Scraping

Project: Opening All Search Results - A project to search the Python Package Index and automatically open each search result link.

Chapter 13 - Working with Excel Spreadsheets

No new sections.

Chapter 14 - Working with Google Sheets

This entire chapter is new, and covers the EZSheets module.

Chapter 15 - Working with PDF and Word Documents

No new sections.

Chapter 16 - Working with CSV Files and JSON Data

No new sections.

Chapter 17 - Keeping Time, Scheduling Tasks, and Launching Programs

No new sections.

Chapter 18 - Sending Email and Text Messages

Sending and Receiving Email with the Gmail API - Using the EZGmail module to access Gmail accounts.

Chapter 19 - Manipulating Images

No new sections.

Chapter 20 - Controlling the Keyboard and Mouse with GUI Automation

Setting Up Accessibility Apps on macOS - Setting up PyAutoGUI to work on macOS.
Planning Your Mouse Movements - Covers the MouseInfo features of PyAutoGUI to log mouse coordinates.
Getting Window Information - Covers the PyGetWindow features of PyAutoGUI to obtain window information.
Displaying Message Boxes - Covers the PyMsgBox features of PyAutoGUI to display alert boxes.
Using the Clipboard to Read a Text Field - A practice project to read text from other applications using PyAutoGUI and Pyperclip.

Type Hints for Busy Python Programmers

2019-11-24T12:00:00-05:00

"Okay, I know that type annotations or type hints or whatever-"

Yes, "type annotation" and "type hint" mean the same thing.

"Right. I know what they are: they let you specify data types for your variables and function parameters & return values, which lets you catch certain kinds of bugs early and save you from lots of debugging and headache. I'm in. How do I use them?"

There's two parts. The first part is you add type hints to your source code. This involves the typing module that's a part of the Python Standard Library as of verison 3.5. The second part is you install the mypy module to do the actual checking.

"Wait, why are there two modules? That sounds complicated."

The first module, typing, lets you specify different data types. But the Python interpreter doesn't care if they're correct. The variable's actual value doesn't have to match the variable's type; the code will still run just fine.

"Doesn't that defeat the purpose?"

Nah, remember that in Python type hints are optional. If you're writing a quick script and don't care, you don't have to use type hints. The Python interpreter itself completely ignores type hints. No type checking happens at runtime. So, technically, type hints aren't "optional static typing" because "static typing" implies that variables always store values of a certain type. Python is still a dynamically typed language even with type hints. Type hints are just hints that third-party tools like Mypy can use to point out potential bugs.

It's the second module, mypy, that is the tool that actually checks that your source code is valid and all the types match. Mypy is made by a third-party, which is why we use two separate modules. You don't have to use Mypy. You could instead use any third-party module that does the checking that Mypy does.

"So what could I use instead of Mypy?"

Pyright, from Microsoft. Pyre, from Facebook. Pytype, from Google. They're all free and should work the same, but most people seem to use Mypy.

"So typing comes with Python 3.5 and later. How do I install Mypy?"

Run python -m pip install mypy. (Use python3 on macOS and Linux.) Add --user if you get error messages about permissions: python -m pip install --user mypy.

If the Python interpreter doesn't care about type hints, then how do I check if my source code matches the declared types?

Mypy installs a command line tool in Python's Scripts folder when you install Mypy. So you run mypy yourProgram.py from the command line (not from the Python interactive shell) and if your code is valid, it prints nothing. If it's not, it will display errors. I generally use the python -m mypy yourProgram.py style of running it.

But even easier is to get a plugin for whatever editor or IDE you use. This way, your editor runs Mypy in the background as you type code and can near-instantly show you any mistakes you make. For example, for Sublime Text, you just install the SublimeLinter and SublimeLinter-contrib-mypy using Package Control. Then, as you type Python code in Sublime Text, it displays any errors that Mypy finds automatically.

"When you say type hints in Python are optional, do you mean half my variables could use type hints and the other half doesn't have to?"

Yes. Python calls this gradual typing. If you want to add type hints to your Python code, you don't have do it all at once. It's like unit test coverage: you could just test some of your functions.

"Okay, I'll install Mypy and set up my editor to use it. Done. So what are all the types I use when writing type hints in my code?"

The Mypy site has a great cheat sheet. Basically, you use the same names as those type conversion functions, like int(), str(), and so on. That's because those are technically the class names for integers and strings. Just like you call datetime.date(2025, 10, 31) to create an object of the date class, int("42") creates an integer object of the int class. In Python, "class" and "type" and "data type" are the exact same thing.

"Okay. So how do I write type hints in my code?"

After the variable name, add a colon and the type name. Here's an example, with comments explaining each one:

numberOfTacos: int = 42  # This variable's type int declares it to be an int variable.
tacosEaten: int  # This declares tacosEaten to be an int variable, but doesn't set an initial value. It's not set to None: using it will result in NameError.

# Type hints without an initial value are handy when there's no one place where an initial value is set, like here:
if numberOfTacos < 10:
    tacosEaten = numberOfTacos
else:
    tacosEaten = 10

piesEaten: float = 3.14
myCatsName: str = 'Zophie'
isBestCat: bool = True
someBytes: bytes = b'HELLO'
randomValues: list = ['Zophie', 99, 3.1415]  # Note that the list can contain values of any type.
goodCats: tuple = ('Zophie', 'Pooka', 'Simon', 'Fat-tail', 'Footfoot')
fruitCount: dict = {'apples': 5, 'tomatoes': 7}
barbers: set = set(['Alice', 'Bob', 'Carol'])
shavers: frozenset = frozenset(['Alice', 'Bob', 'Carol'])

"Cool. So what happens when I write code that sets a variable to the wrong type of value?"

In Python, nothing. When you run the Python interpreter to run your program, it doesn't care about type hints. It just sets the variable to the value. But, before that point, when you're writing the source code in an editor that runs Mypy in the background, Mypy will report to the editor that there's a problem and the editor will show it to you as you're typing.

numberOfTacos: int = 42  # The numberOfTacos variable should only have ints.
numberOfTacos = 'bleventeen'  # Your editor will display a warning on this line. But Pyhton will still run this code just fine.

"What about the values inside of the list, tuple, dictionary, and other container types? Can I specify type hints for those?"

Yes, and you do this adding square brackets with the item types inside. But cats: list[str] = ['Zophie', 'Pooka'] isn't valid Python code. (The reasons why this style couldn't work is too long to go into here.) The solution that the Python core devs came up with is to have analogous classes in the typing module. Here's an example:

from typing import List, Tuple, Dict, Set, Frozenset

groceryList: List[str] = ['bread', 'eggs', 'tofu']
cityHall: Tuple[float, float, str] = (37.779, -122.419, 'San Francisco')
fruitCount: Dict[str, int] = {'apples': 5, 'tomatoes': 7}
barbers: Set[str] = set(['Alice', 'Bob', 'Carol'])
shavers: Frozenset[str] = frozenset(['Alice', 'Bob', 'Carol'])

"What if I want to have a list that can contain multiple types of values for its items?"

Use the Union type from the typing module. For example:

from typing import Union
favoriteLettersAndNumbers: List[Union[int, str]] = [42, 'x', 86]

You can also use Union to specify variables that can have more than one type:

from typing import Union
serialNumber: Union[int, str] = 42
serialNumber = '42b'

"Okay. So if I have a variable that contains integers, but could also contain None, should I use, uh, Union[int, NoneType]?

You can use Optional instead, which means the same thing. And technically, NoneType isn't a defined type the way int or str are. So you can't say type(None) == NoneType the way you can say type(42) == int. Instead, we'd just use None like in this example:

from typing import Union, Optional

# These two have the same type hint, but `Optional[int]` is easier to write and read:
eggs: Union[int, None] = 42
bacon: Optional[int] = 42

But here's the thing: you should avoid using "null" values like None at all. Computer scientist and inventer of the null value Tony Hoare called it his Billion Dollar Mistake because it's often the cause of bugs. I vaguely remember some study that said NullReferenceException was by itself the cause of something like 30% of all Java application crashes. Kotlin, a language that is a sort of modernized Java, by default doesn't let you set variables to null. You can still use None if you need to, but don't use it without forethought.

"What if I don't care what type of a value a variable has. Should I just not use type hints?"

No, remember that "explicit is better than implicit." You should explicitly use the Any type for variables that can be of any type:

from typing import Any
spam: Any = 42
spam = 'hello'  # This is fine. `spam` can be set to any type.

Can I do more specific checks? Like, specify that a variable should be an int, but never a negative integer?

Nope. Type hints are only for types, not for values. I'd recommend subclass the class or, since you can't subclass int, you create your own non-negative integer class. Anyway, remember that type hints only work before runtime. They don't do runtime checking of values. You should use assert or even just if statements for that.

"What about classes I write or other types like datetime.date or the match objects returned from re.search('[aeiou]', 'hello')?

You just use the class name as the type. Remember, in Python the terms type, data type, and class all mean the same thing. Also note that self isn't written with a type hint:

class Cat:
    def __init__(self, name: str, color: str, weightkg: float) -> None:
        self.name = name
        self.color = color
        self.weightkg = weightkg

def getZophieClone() -> Cat:
    return Cat('Zophie', 'gray', 4.9)

"What about weird types, like functions or sequences or mappings or iterables?"

The typing module has Callable, Sequence, Mapping, Iterable, and others. You can find them in the documentation.

"Alright, cool. So how about functions? How do I write type hints for parameters and return values?"

These are all done in the def statement. The return value's type hint is specified after a -> arrow. For example:

from typing import Optional, List

def getVowelsFromWord(word: str, maxVowels: Optional[int] = None) -> List[str]:
    vowels: List[str] = []
    for letter in word:
        if maxVowels is not None and len(vowels) >= maxVowels:
            break  # Break early since we've reached the maxmimum.

        if letter.upper() in 'AEIOU':
            vowels.append(letter) # Record this vowel letter.
    return vowels  # Return all the vowels fown in word.

In our getVowels() function, it has two parameters, word (which can be a string) and maxVowels (which can be an integer or None). The function itself returns a list of strings. A tool like Mypy can verify that the return statement returns the vowels variable, which has the type hint List[str], which in turn matches the function's return type hint.

"What about type hints in Python 2? Won't those colons cause syntax errors?"

Yes, but you can put type hints inside comments if you're writing Python 2 (or pre-Python 3.5) compatible code:

from typing import List # Required even for comment-style type hints.

spam = 42 # type: int
def sayHello():
    # type: () -> None
    """The docstring comes after the type hint comment."""
    print('Hello!')

def addTwoNumbers(listOfNumbers):
    # type: (List[float]) -> None
    listOfNumbers[0] += listOfNumbers.pop()

Note that you'll still need to import objects from typing even with the comment-style of type hints.

"I've started using type hints, but I've come across a warning that doesn't really apply to my code. How do I get Mypy to ignore that one line?"

You can add a comment # type: ignore to the end of that line:

from typing import Any

def raiseMyCustomException(val: Any):
    # Some code here...
    raise Exception('message here: ' + str(val))

def getLengthIfString(val: Any) -> int:
    # Some code here...

    # This function call always raises an exception, but mypy thinks
    # gives the error "missing return statement", so we tell mypy to ignore it:
    raiseMyCustomException(val)  # type: ignore

"Cool! Now I know enough to get started. Where can I learn more about type hints?"

Check out the official Python documentation or the Mypy documentation, starting with the cheat sheet. There was also a well-received talk at PyCon 2019 on type hints by Carl Meyer.

Book Review: Code This Game! by Meg Ray (Odd Dot 2019)

2019-11-12T12:01:00-05:00

5 Stars: An excellent project-based book for young readers who want to move beyond Scratch.

Amazon link

Code This Game is an excellent book that teaches Python programming by guiding the reader through making a tower-defense game from scratch. This is a book that doesn't shy away from programming detail, but manages to remain fun and engaging. If you have a student or child who wants to move beyond MIT's Scratch programming tool and do "real" programming, this is a great book.

The book features a tower defense game called Attack of the Pizza Vampires, and anyone who's ever played the popular Plants vs. Zombie games will recognize its influence here. The graphics are provided from a free website download, but the reader copies the code from the book, accompanied by explanations of the relevant programming concepts.

Don't let the 300+ page count intimidate you: The pages are short and colorful, and the chapters are well-paced and let you see the progress you've made as you go from absolutely nothing to a full game. The book covers Pygame, a free software library for Python that has been used in some commercial video games, but is still simple enough to be approachable by young adults. The book itself includes a small stand to prop the pages up, making it easy to read as the reader enters the Python code into their computer.

From my experience teaching with after school coding clubs, I agree with the stated 10 to 14 age range. This book would be suitable for motivated 9 or maybe even 8 year olds and for older teenagers if they look past the colorful cartoony presentation. The code and teaching itself is solid. Your student or child might be able to read this book on their own, but I think a parent or teacher (even one without programming experience) could be a great help to follow along with. I also think this book could be useful for an after school coding club or intro to programming class: the game project is split up in such a way that it makes for a good resource to work through over multiple sessions.

I like how the book doesn't mind going into technical topics, but at the same a hard understanding of these terms isn't necessary to create the Attack of the Pizza Vampires game and get a sense of accomplishment. The introductory chapter has lots of useful tips for setting up your computer (whether Windows, macOS , or another operating system) to get Python installed and running. These "environment setup" steps are often a large stumbling block in getting a single student or entire class started on programming games, so the presence of this information shows good foresight on behalf of the authors.

Python is excellent programming language for beginners. If you're looking for a resource that teaches actual programming skills while still be approachable, I recommend Code This Game.

Live Online Python Class on Twitch on October 21, 2019

2019-10-20T12:00:00-04:00

Hello, I'm Al Sweigart. I'm the author of Automate the Boring Stuff with Python, and I'll be doing a live online Python class for beginner- and intermediate-level programmers on Twitch on Monday evening, October 21, 2019. The URL is https://www.twitch.tv/alsweigart/ and the stream will begin at 6pm Pacific. If you want to join in the chat, you'll need to sign up for a (free) account on Twitch. However, you'll be able to watch the stream without an account. I'll post a link to the video if you're reading this after the stream.

I'll also be releasing a free code for my online course that follows the "Automate the Boring Stuff with Python" on the stream (and on this page after the stream). Unfortunately, due to changes in Udemy's policies, this code will only work for three days and will stop working after Wednesday, October 23. Udemy has limited how often I can make free codes, so I won't be able to create new ones for those who miss this one. You'll be still be able to watch the first 15 videos of the 50-video course at anytime on YouTube.

EDIT: The coupon code is OCT2019FREE, but is only valid until Wednesday, October 23, 2019.

Class Format: The format for the class is that I'll be working through several beginner level coding projects. I'll take a look at these programs, and show you how I write them step by step. You can follow along, or simply re-type the source code yourself and try running the programs. The programs are from a repo of small, simple Python games I've been developing.

The programs we'll be covering, in order starting at 6pm, are:

You can read through the code to familiarize yourself with them beforehand, but it isn't required. I expect the process for each of these programs will be:

Explaining what the game is or what the program does.
A demonstration of running the completed program.
Starting with a blank file, and stubbing out the general parts of the program with comments.
Filling in the code while describing the data structures/algorithms used.

I'll be copying the code from GitHub exactly, which is a bit artificial in the way that I normally write code, but I'm doing it this way so that the audience doesn't have to follow exactly along with code as I type. Instead, you can move slower or faster by copying the code from the repo. I recommend having a browser window open with the code and copying it by typing it yourself (as opposed to copy/pasting it).

Prerequisites: You'll be expected to have Python 3 installed on your computer along with an IDE or text editor for writing Python programs, such as IDLE or PyCharm or Visual Studio Code. This class is for beginners, but not complete beginners: I'll expect that you've written a "Hello world" program and gotten it to run on your computer. However, even if you're a complete beginner, feel free to watch along to get an idea for how programs are written by programmers.

I offer a blog post I wrote, "How to Ask for Programming Help" to read before the live stream. There are several techniques that make it much easier for folks to answer your questions (copy/pasting your code to a pastebin, stating the exact error message, describing what you've already tried, describing your OS and Python versions, etc.) that can make it much easier to answer your questions.

Questions are welcome, but unfortunately I cannot help you with environment setup on your computer. This tends to hold up the class for hours, and it'd mean I couldn't progress with the class. Please make sure you are able to run a print('Hello, world!') program on your computer. The projects are designed to not require any third-party modules or additional libraries that need to be installed.

Streaming Schedule: I hope to make this a regular occurring stream, and I'll be taking notes on the format and what works and what doesn't. I hope to make this a weekly or twice-weekly event. This is a casual streaming event on the internet, but you should treat it as a professional event with mixed company. The general rules for chat are stated as, "No harassment, offensive/edgy/"ironic" jokes, or complaining about moderators. Keep it classy and on topic. Young adults should be able to watch and participate without their parents cringing."

What's New in the 2nd Edition of "Automate the Boring Stuff with Python"

2019-10-07T12:00:00-04:00

The second edition of "Automate the Boring Stuff with Python" is almost out! You can preorder it on the No Starch Press website, where buying the print book will get you DRM-free ebooks in PDF, epub, and Kindle formats for free.

The second edition is about 100 pages longer than the first, with new chapters, programming projects, and revised editing. The third party module coverage has been updated to the latest available version (including OpenPyXL).

Like the first edition, the second edition will be released under a Creative Commons license and will be free to read online. The estimated online release is early November on the https://automatetheboringstuff.com.

Some of the new content includes:

The Mu editor - The second edition switches from IDLE to Mu, an editor specifically designed for education and beginners. Watch Nicholas Tollervey present Mu at PyCon 2018.
Explanation of the call stack - A description of the call stack, which helps the reader understand global and local scopes.
The enumerate() function - Using enumarate() in for loops and its advantages over using range().
The random.choice() and random.shuffle() functions - These functions in the random module weren't covered before.
Identity and the id() function - Added to help explain references and in-place modification.
The partition() method - A useful string method similar to join().
New chapter: PyInputPlus and input validation - Covers a third party module, PyInputPlus, for input validation and why input validation is important.
The pathlib module and Path objects - Explores a new, versatile way to write code that interacts with the file system.
OpenPyXL updates - This third party module made several backwards-incompatible changes, confusing some readers who installed the latest version instead of the version in the book. This chapter has been updated to the latest version.
New chapter: Working with Google Sheets - A new chapter covering the EZSheets module, allowing your Python scripts to read and update spreadsheets on Google Sheets.
New module: EZGmail - The email/SMS chapter now features the EZGmail module, which allows Python scripts to interact with Gmail accounts. Previously this was much more difficult to do via the smtplib and imapclient modules.
SMS email gateways - A new section on how to send SMS text messages via the phone carrier's email gateways. Now your Python scripts won't need to use a service such as Twilio to send occasional text messages.
MouseInfo app - A small GUI application that is a part of PyAutoGUI which reveals the current coordinates of the mouse. This information is useful for planning out GUI automation tasks.
The PyGetWindow module - A new module included in PyAutoGUI that retrieves the coordinates, size, and status of the desktop windows for running programs.
The PyMsgBox module - A new module included in PyAutoGUI that provides popup message boxes for your program when it needs to get the attention of the user.
Requirements.txt files - Available text files that make it easy to install the exact versions of the modules that the book covers. (See below.)

New projects and programs include:

"Rock, Paper, Scissors" game - The source code for a simple rock, paper, scissors game.
"Zig Zag" program - A small animation program to produce a zig zag line.
"Conway's Game of Life" program - The source code to the classic cellular automata program.
"Pig Latin" program - The source code for an "igpay atinlay" text converter.
"Zombie Dice" simulation - Instructions how to write your own bots that play the game Zombie Dice against each other.
Date Detection practice project - An exercise for using regular expressions to parse dates.
"How to Keep an Idiot Busy for Hours" program - The source code for a joke program.
"Multiplication Quiz" program - The source code for a math quiz program.
Practice projects: "Sandwich maker" and "Write your own multiplication quiz" - Exercises for using the PyInputPlus module.

To avoid installing third-party module versions that the book doesn't cover, I'm making available several requirements.txt files so that pip can easily install the exact versions that the book covers. Download the file for your operating system:

automate-win-requirements.txt for Windows
automate-mac-requirements.txt for macOS
automate-linux-requirements.txt for Linux

To install, download the file for your operating system. Then open a terminal or command prompt window and run pip install -r automate-<your os>-requirements.txt. If you're using pipenv to create a virtual environment, you'll need to run pipenv install -r automate-<your os>-requirements.txt.

Note that PyAutoGUI requires Pillow, which currently doesn't support Python 3.8 yet.

If you have questions about the second edition or its content, you can post them on the /r/inventwithpython subreddit.

Python Error Messages: Gotta Catch Em All

2019-08-15T12:00:00-04:00

Error messages can be intimidating for beginners to programming. They're often shown in red text, and may give the sense that the computer has been damaged or broken. Experienced programmers take them in stride; errors are just a casual fact of life, and correcting them is just a part of the programming process.

To make errors less intimidating, I've created a "Gotta Catch 'em All" worksheet that lists several common Python error messages. Instead of trying to avoid errors, beginners can try to hunt and collect them all. This makes errors less scary and gives an incentive for beginners to carefully read the error messages and figure out what causes them.

This worksheet can be useful for self-taught individuals or classroom and workshop instructors. As students encounter error messages, they can look them up on the worksheet to see if they've encountered them before. There's a space to write down the line of code that caused the error message, encouragement to do a web search for the error message, and a space to write down the solution they found.

PDF of the "Gotta Catch 'em All" worksheet (letter-sized)

Microsoft Word document of the worksheet

This worksheet could use some improvement. It'd be nice if the list of errors was expanded, or even if each kind of error (or error message) had a small Pokemon-like mascot. Perhaps putting these errors and mascots on cards instead of a worksheet would be good. I'm open to anyone who wants to take this idea and expand upon it.

If you have other ideas for how the worksheet could be improved or more error messages to add, email al@inventwithpython.com or contact me on Twitter at @AlSweigart.

Pythonic Ways to Use Dictionaries

2019-06-05T12:00:00-04:00

Python dictionaries are a useful part of the language. In addition to having the ability to store keys and values, you can also use dictionary methods to manipulate those values, and you can use dictionaries to write more concise code.

Use `get()` and `setdefault()` with Dictionaries

Trying to access a dictionary key that doesn’t exist will result in a KeyError error, so programmers often will write unpythonic code to avoid the situation like this:

>>> # Unpythonic Example
>>> workDetails = {}
>>> if 'hours' in workDetails:
...     hoursWorked = workDetails['hours']
... else:
...     hoursWorked = 0 # Default to 0 if the 'hours' key doesn't exist.
...
>>> hoursWorked
0

This pattern happens so often that dictionaries have a get() method that allows you specify a default value to return when a key doesn’t exist in the dictionary. The following code is equivalent to the previous example, but is pythonic:

>>> # Pythonic Example
>>> workDetails = {}
>>> hoursWorked = workDetails.get('hours', 0)
>>> hoursWorked
0

If you find yourself writing if statements that check whether a key exists and provide a default value when the key is absent, use the get() method instead.

Conversely, you may want to set a default value if a key doesn’t exist. For example, if the dictionary in workDetails doesn’t have an 'hours' key, then the instruction workDetails['hours'] += 10 would result in a KeyError error. You may want to add code that checks for the key’s absence and sets a default value:

>>> # Unpythonic Example
>>> workDetails = {}
>>> if 'hoursWorked' not in workDetails:
...     workDetails['hours'] = 0
...
>>> workDetails['hours'] += 10
>>> workDetails['hours']
10

The previous example is unpythonic. Because this pattern is also common, dictionaries have a more pythonic setdefault() method. The following code is equivalent to the previous example:

>>> # Pythonic Example
>>> workDetails = {}
>>> workDetails.setdefault('hours', 0) # Does nothing if 'hours' exists.
0
>>> workDetails['hours'] += 10
>>> workDetails['hours']
10

If you find yourself writing if statements that check if a key exists in a dictionary and sets a default value if the key is absent, use the setdefault() method instead.

Python Uses Dictionaries Instead of a Switch Statement

Languages such as Java have a switch statement, which is a kind of if-elif-else statement that runs code based on the values of a single variable or expression. Python doesn’t have a switch statement, but a switch statement is similar to the following Python code, which sets the holiday variable based on the value of the month variable:

>>> # Unpythonic Example
if season == 'Winter':
    holiday = 'Christmas'
elif season == 'Spring':
    holiday = 'Easter'
elif season == 'Summer':
    holiday = 'American Independence Day'
elif season == 'Fall':
    holiday = 'Halloween'
else:
    holiday = 'Personal day off'

Handling code by using if statements to mimic switch statements is unpythonic. By default, Java switch statements have “fall-through” that requires each block end with a break statement. Otherwise, the execution continues on the next block. Forgetting to add this break statement is a common source of bugs. However, all the if-elif statements in our Python example are not much better since they can be overly verbose. Some Python programmers prefer to set up a dictionary value instead of using if-elif statements. The following concise and pythonic code is equivalent to the previous example:

>>> # Pythonic Example
holiday = {'Winter': 'Christmas',
           'Spring': 'Easter',
           'Summer': 'American Independence Day',
           'Fall':   'Halloween'}.get(season, 'Personal day off')

This code is just a single assignment statement. The value stored in holiday is the return value of the get() method call, which returns the value for the key that season is set to. If the season key doesn’t exist, then get() returns 'Personal day off'. Using a dictionary will result in more concise code, but it can also make your code harder to read. It’s up to you whether to use this convention or not.

Hashable Objects Must Be Immutable

2019-02-01T12:00:00-05:00

A recent post to Reddit sparked some comments, so I wanted to clarify: In Python, hashable objects must be immutable and mutable objects cannot be hashable. (With one exception.)

Before the torches and pitchforks are gathered, let me explain some background.

If you want to make your classes hashable, you must follow two rules outlined in the Python Glossary for the entry for "hashable":

An object is hashable if [1] it has a hash value which never changes during its lifetime (it needs a __hash__() method), and can be compared to other objects (it needs an __eq__() method). [2] Hashable objects which compare equal must have the same hash value.

In Python, integers, floats, and bools are all immutable. And because 1 == 1.0 == True, then hash(1) == hash(1.0) == hash(True).

Let's create an immutable Point class, which has read-only x and y attributes, and it reuses the hashes for tuples:

>>> class ImmutablePoint:
...   def __init__(self, x, y):
...     self._x = x
...     self._y = y
...   def __eq__(self, other):
...     if not isinstance(other, ImmutablePoint):
...       return False
...     return self._x == other._x and self._y == other._y
...   def __hash__(self):
...     return hash((self._x, self._y))
...   @property
...   def x(self):
...     return self._x
...   @property
...   def y(self):
...     return self._y

We can create ImmutablePoint objects, and they are immutable: we can't change their x or y attributes:

>>> ip = ImmutablePoint(10, 20)

>>> ip.x, ip.y
(10, 20)

>>> ip.x = 'changed' # x and y are read-only
Traceback (most recent call last):
  File "stdin", line 1, in module
AttributeError: can't set attribute

>>> ip2 = ImmutablePoint(10, 20)

>>> ip == ip2
True

Since they are hashable, we can also use these objects as keys in a dictionary:

>>> d = {ip: 'hello'}

>>> d[ip]
'hello'

>>> d[ip2]
'hello'

Now, since hashes are based on an object's value and an object's hash never changes (according to the rule from the Python Glossary), this necessarily means that only immutable objects can be hashable. Notice that you can't use a mutable list or dictionary as a key in a dictionary, nor do they return anything from hash():

>>> {[1, 2, 3]: 'hello'}
Traceback (most recent call last):
  File "stdin", line 1, in module
TypeError: unhashable type: 'list'

>>> hash([1, 2, 3])
Traceback (most recent call last):
  File "stdin", line 1, in module
TypeError: unhashable type: 'list'

>>> hash({1:2, 3:4})
Traceback (most recent call last):
  File "stdin", line 1, in module
TypeError: unhashable type: 'dict'

But why is this so? What's so bad about making a mutable object hashable? We can just add a __hash__() method to our mutable class, right?

The reason has to do with how hashes are used in dictionaries. This will require some CS background on how dictionaries/hashmaps work (but you can watch Brandon Rhode's PyCon 2010 talk, The Mighty Dictionary). But the short answer is that if the object's value changes, then the hash must also change since hashes are based on values. However, if the object's value changes after it's used as a key in a dictionary, the hash will no longer refer to the correct bucket in the dictionary for that key. Let's use an example.

Here's a subclass of Python's built-in list data type (which is mutable) that we've added a __hash__() function to:

>>> import collections

>>> class HashableList(collections.UserList):
...     def __hash__(self):
...         return hash(tuple(self))

We can create a hashable list object and put it in a dictionary:

>>> h = HashableList([1, 2, 3])

>>> d = {h: 'hello'}

>>> d
{[1, 2, 3]: 'hello'}

It seems to work. We even make another hashable list with the same value and it seems to work too:

>>> d[h]
'hello'

>>> h2 = HashableList([1, 2, 3])

>>> d[h2]
'hello'

Now we change h. As expected, it creates a KeyError because [1, 2, 100] isn't a key in the dictionary, only [1, 2, 3] is (this turns out to be wrong, but ignore that for now):

>>> h[2] = 100

>>> d[h]
Traceback (most recent call last):
  File "stdin", line 1, in module
KeyError: [1, 2, 100]

But here's the thing. h2 no longer works as a key, even though it is [1, 2, 3]:

>>> d[h2]
Traceback (most recent call last):
  File "stdin", line 1, in module
KeyError: [1, 2, 3]

Why is this? Because the key in d isn't a copy of the [1, 2, 3] object, it's a copy of the reference. When we changed h, we also changed the dictionary key:

>>> d
{[1, 2, 100]: 'hello'}

So this means the key is now [1, 2, 100], but it's in the bucket/slot for [1, 2, 3]. But h2's [1, 2, 3] won't work because the key's value is now [1, 2, 100] and Python just assumes it happens to be a hash collision.

To make things even worse, try setting h[2] to 99. By sheer coincidence, [1, 2, 99] hashes to the same bucket/slot as [1, 2, 3]. And the values are the same (because the key has also changed to [1, 2, 99]) so it works perfectly fine even though it should cause a KeyError:

>>> h[2] = 99 # You might need to find another integer to reproduce this, depending on your Python version.

>>> d[h]
'hello'

So this is why it's a Bad Thing to have mutable items be hashable: changing them also changes the key in the dictionary. Sometimes this works even though it should cause a KeyError (when there's a hash collision by coincidence) and other times it'll cause a KeyError when it should work (because the dictionary key has changed when the mutable object has changed).

BUT WAIT, WHAT WAS THE ONE EXCEPTION? Well, a mutable object can be hashable and used as a dictionary key as long as it's hash and value are the same as its identity (or some other unique, unchanging integer). That is, it must have the following __eq__() and __hash__() implementations:

>>> class SomeClass:
...   def __eq__(self, other):
...     return other is self
...   def __hash__(self):
...     return id(self)

This also happens to be the default implementations for Python classes, so we can shorten our class to just the following:

>>> class SomeClass:
...   pass

In this case, we uphold the two rules for hashability. But we don't really have a useful class, because every object of type SomeClass is only equal to itself, and will always be False when compared to any other object, no matter what its value is.

>>> sc = SomeClass()

>>> {sc: 'hello'}
{<__main__.SomeClass object at 0x000001C6CEA57748>: 'hello'}

>>> sc2 = SomeClass()

>>> sc == sc2
False

So either you can follow Python's two hashability rules for your class, or you can create mutable, hashable objects that don't actually work in dictionaries. The only exception when you can have a mutable, hashable class is when the hash is based on the identity and not the value, which severely restricts its usefulness as a dictionary key. Which means that, effectively, only immutable objects can be hashable and mutable objects can't be hashable.

Fin.

Book Review: The Little Schemer

2018-12-09T12:01:00-05:00

(Also posted to Amazon.com.)

Alternative Title: The Little Schemer Wears No Clothes

Perhaps a software engineer or MIT professor friend of yours recommended this book to you. “Oh, you want to learn how to code? You should read The Little Schemer,” they’ll say. Your friend means well, but is completely wrong to recommend this book.

I really wanted to like this book. I wanted to be charmed by its Socratic, question-and-answer-format presentation. I have a computer science degree. I’ve taught kids and adults how to program. I have (full disclosure) written popular books teaching folks how to code. I have taught and given talks on recursion. I have read Godel Escher Bach by Douglas Hofstadter, which seems to have started the “whimsical Lewis Carroll” trope among computer-scientists-turned-writers. If anyone should be a person who likes this book, it should be me.

I don’t like this book. The problems are legion.

First: If you are in the, like, 5% of the population who likes manipulating abstract symbols according to arbitrary logical rules just for the sake of manipulating abstract symbols according to arbitrary logical rules, you’ll love this book. This is the book for you. Five-stars, disregard this review and send me a nasty email telling me I “just don’t get it” and “it’s not supposed to teach programming but a way of thinking”. You should read this book. You’ll get a lot out of it.

If you’re someone who wants to learn to code, or is a freshmen computer science student, or someone who likes popular science and wants to learn more about computing, put this book back on the shelf and back away. When you’ve got enough distance, turn and run.

Before I go into the problems, I think this book would have been great if it had a heavy-handed editor. The approach Friedman and Felleisen take is novel, and experimentation should be encouraged. But that doesn’t mean every experiment is a success. A good editor would have pointed out all the problems that I’ll bring up in this review, sent them back to the drawing board/writing desk, and they would’ve come back with something better. A few rounds of this, and they’d without a doubt have a great book. Instead, they don’t have a great book for beginners, they have a book that computer science professors with years of familiarity and experience think is a great book for beginners.

One of the largest problems is the question-and-answer format. Like alcohol, it’s great in moderation but several issues come up when you rely on literally nothing but it. This book literally never explains anything directly. Nothing is ever given a solid definition; you are left to infer it for yourself. Can’t figure it out, or worst, think you’ve figured it out but are actually working under the wrong assumption? Too bad. The book is moving on, and all the concepts in this book build on top of the previous work. A glossary is a standard part to have in any textbook and would be incredibly helpful in this one, but sadly the authors considered themselves above having one. In the preface, the authors state “We believe that you can form your own definitions and will thus remember them and understand them better than if we had written each one for you.” This is an utterly, completely erroneous belief. And conveniently it frees the authors from having to, you know, explain in simple language what exactly they mean.

Relying solely on a Socratic approach simply isn’t practical. And what exactly is going on in this book? Are we watching two people having a question-and-answer dialogue? Is the book asking the reader the question? (In which case, there is no possible way the reader could know the answer for most of them, which is hair-pulling levels of stressful the hundredth time you encounter it.) Are these questions the reader is posing to the book? It actually changes page to page. You’ll see the impracticality of the Socratic-only approach in some of the “questions” (which are really answers) and “answers” (which are really questions), especially in the later chapters. This book needs to stop being chained to the question-and-answer format; a few explanatory paragraphs would have done a world of good.

There were “The Ten Commandments” and “The Five Rules” at the start of the book, but they aren’t the most lucid statements: “When recurring on a list of atoms, lat, ask two questions about it: (null? lat) and else.” What? The word “else” is a question? How is the reader supposed to derive knowledge from a sentence that barely parses as English? It’d be nice if the listings of commandments had page number references to where they’re explained in the book, instead you’re left on your own. And by the way, the First Commandment is split up across three different places (the final one listed after the Fifth Commandment). Any editor would have told them “split this up into three commandments”. There’s a multitude of places where the simple advice from an editor would have saved the reader so much headache.

There are no objectives stated in the chapters. You’ll find yourself asking “what’s the point of this?” and “where are they going with this?” constantly. Constantly. The chapters launch into the content cold turkey and always end abruptly. Really, the dividing line between where one chapter ends and the next one starts could be made anywhere. And the chapter names don’t offer any hints either: “Toys”, “Cons the Magnificent”, “Shadows”. That last one has the especially infuriating questions: “What is (lat? ls) where ls is ((( )) (() ( )) (() ( )()))” answered with “It is very false.” and “Is that bad?” answered with “You must beware of shadows.” and then the chapter immediately ends. This is literally the only time the word “shadows” appears in the entire book. Oh yes, very mysterious. But they aren’t writing a mystery novel, they’re writing a textbook that should explain what the hell they mean. To someone with a CS degree it’s a bad metaphor, but to the beginner it’s simple inscrutable.

Because the book is a steady stream of question-and-answer, it forms a trail of breadcrumbs: lose your way once and you’re completely lost. You can’t skim this book, and when you pick it up to start where you left off, it’s hard to remember what you were looking at and trying to understand. Everything is built on the previous content, so this book requires you to load everything into your short-term memory. Some will say this is a “feature”, but I say it’s a staggering bug.

That guy who loved this book and is recommending it to you is well-intended, but clueless as to what makes for an effective teaching tool. And that’s the reason I wrote this scathing review (which I’ve sat on for a year, wondering if I should actually post it). My prime worry, nay, chilling fear, is that a lot of people will be handed this book, read it, not get it at all, and conclude that they are simply too stupid to learn computer science. "If I can't understand the book with the cute elephant drawings, how am I suppose to understand the harder computer science textbooks?"

This book needs better titles for its chapters. It needs a glossary and explanatory paragraphs. It needs objectives and summaries in each chapter. It needs to drop the cutesy metaphors and coy figure-out-for-yourself-what-we-mean approach (or at least add straightforward explanation afterwards). It needs an editor. But all of these things make for a book that isn’t as fun to write as a whimsical Socratic book of recursive algorithms. The Little Schemer is simply not a good guide for beginners; it’s a vanity project.

A Curriculum for Python Packaging

2018-10-22T12:00:00-04:00

Python's packaging ecosystem contains multitudes. It can be intimidating for new Python developers to try to crack into, especially given the rapid evolution of Python packaging. Writing a *helloworld.py* file and running it on your computer is simple, but getting it to run on someone else's computer (and doing this the "right" way) involves a tangle of terms, tools, and techniques. What are wheel files? What is distutils? Do I use distutils or easy_install or pip?

To get to the bottom of this myself, I've compiled a curriculum of PyCon talks, online documentation, and my own personal notes to finally get a complete handle on Python packaging. The following list is my recommended order: start from the beginning, and continue until whatever level of satisfaction you require. I've tried to put the easy/simple/quick resources first, and the rest become progressively more detailed and specialized.

I've also added my own summary and notes, which you may or may not find useful. If you have any comments about this curriculum, please email me or message me (and follow me!) on Twitter. (Note that this blog post was written in October 2018. I might update this every few months (or years).)

NOTE: The information in the official Python documentation for the distutils module is out of date (note that it says "Legacy version" in the title), as well as the Installing Python Modules (Legacy version) documentation. The latter was replaced by Installing Python Modules.

Python Packaging Curriculum

The following are also packaging-related, but I haven't had time to organize them into this curriculum:

1 - Dustin Ingram - Inside the Cheeseshop: How Python Packaging Works - PyCon 2018

Link to YouTube video.

My summary of this talk: A great history lesson on the Python Package Index (PyPI), it’s previous incarnations, and the distutils/setuptools/easy_install/twine tools for getting your packages on it.

History: The first package index was a web site called The Vaults of Parnassus, which was a simple, fairly unstructured, GeoCities-looking website.
Then came distutils (“distribution utilities”) in Python 1.6 gave us python setup.py ... Had a “just use Python code instead of a domain-specific language or anything fancy” attitude; very barebones.
python setup.py build became the standard, makefile-like way to build packages. To package source code for sharing, we used the now-familiar python setup.py sdist (“source distributions”)
python setup.py bdist (“build distributions”) would package up pre-built code for your OS/platform for you.
The problem was, before running python setup.py bdist, how do you get everything together for the bdist part? This was solved on Linux by package managers like RPM, but not on Windows/macOS/obscure platforms.
To solve this, the Python Package Index was made as a general Python package manager for all platforms.
PyPI is “Pie-pea-eye”, not “Pie-pie”. “Cheese shop” was the old name for PyPI.
setuptools was a monkey-patch (bad idea) to distutils to install package dependencies.
easy_install intrduced the “Egg Distribution”. Egg files are just zip files with some metadata files included in them. (Pythons, the snake, lay eggs.)
easy_install couldn’t uninstall stuff or tell you the packages you had installed.
pyinstall was created to solve these problems. You’ve probably never heard of this, because it was soon renamed to pip, which stands for “PIP Installs Packages”.
Pip ignores eggs, and only handles source distributions. Pip begins to be used to install applications, not just library modules.
Pip introduces requirements.txt, which contains a list of depended-on packages (and the specific version of the package) that the package depends on: pip install -r requirements.txt is used to install all these dependencies listed in the file.
Pip mainly depended on installing from whoever was hosting the package from their website. This was a problem; this random person’s website could be slow, or could be hacked so that it spread malware when you installed from it. So PyPI begins hosting modules on its own website.
There are still problems with source distributions that were solved with built distributions, but the Egg format was poorly defined, so Wheel files becomes the new Egg file: a way to distribute built modules. Wheel files (named after cheese wheels, a reference to cheese shop) are also like Egg files in that they are just zip files but they are more well-defined (see PEP 427) that learned from the mistakes of easy_install and Egg files.
Twine came out to solve the problem that python setup.py upload doesn’t use HTTPS. The name comes from using twine to bundle up boxes & packages. The name doesn’t really make a lot of sense. Twine doesn’t bundle stuff, so much as just upload already-bundled packages using encrypted HTTPS.
PyPI was showing its age, and so it was rewritten from scratch. This was the “warehouse” project, started in 2011 and became the new PyPI in 2018. Yay!
Current problems: Packaging is still kinda hard. There’s tons of tools and history. Read the Python Packaging Guide at https://packaging.python.org, and sampleproject at https://github.com/pypa/sampleproject (a nice skeleton project that follows best practices).
Current problems: Packaging is a little too easy; typo squatting and spamming PyPI. Solution: conda, a Python-agnostic packaging tool.
Current problems: Reproducible environments. Solution: pipfile and pipfile.lock from https://github.com/pypa/pipfile
Current problem: setup.py executes arbitrary code, which is a security/standards/maintenance concern.
Current problem: The “distutils/setuptools” dance; these are old/hard-to-maintain standard library modules. Updating them is hard to do. PEP 517 and PEP 518 detail solutions, which is where pyproject.toml files come in. These are files that specify dependencies, etc. in an agnostic way: distutils & setuptools can use pyproject.toml files to install dependencies, or some other tool can use them.

2 - Dave Forgac Share Your Code! Python Packaging Without Complication PyCon 2017

Link to YouTube video.

My summary of this talk: This video goes into detail about setup.py files, but otherwise it’s great in listing things that you should go off and learn more about. It also touches on the associated things you need to get together for a package (docs, tests, continuous integration, etc). The slides for this talk are available at daveops.com/pycon2017

The things you need to share your code with other people:

Package the code
Documentation
Source Hosting (GitHub, etc.)
Tests
Continuous Integration (CI)
License
Contributing guide

This is a lot stuff, but you can just use cookiecutter to make all of this stuff for you.
Terminology:

Module (Python code saved in a file)
Import Package (a folder that stores Python modules)
Distribution Package (a file that has bundled up your code into a shareable/installable file)
Source Distribution (source code that is shared with other people, include C source code for C extensions, these are built/compiled when the package is downloaded/installed)
Built Distribution (eggs and wheel files, wheel is the modern current one, these are pre-compiled so they only need to be unpacked when downloaded/installed)

Types of wheel files:

Universal wheels (contains only Python code that works with Python 2 and 3 and can be installed anywhere.)
Pure Python wheels (contains only Python code, but only for Python 2 or Python 3.)
Platform wheels (files that contain compiled code for a target platform/OS)

History (this was covered more in Dustin Ingram’s talk).
PyPA (Python Packaging Authority) starts creating standards for packaging in the Python ecosystem. PyPUG is the Python Packaging User Guide at https://packaging.python.org/
setup.py is just a Python file, but don’t do anything clever or add custom logic to it.
setup.cfg holds wheel settings and various other settings
MANIFEST.in will list any non-Python files (data files, configuration files, documentation, etc.) that need to be packaged up too.
README.rst is the Restructured Text file (note, not Markdown) that will be used for the package’s PyPI page.
PEP 440 covers the format to use for version strings.
setup.py is a file basically just calls setuptools.setup().
(There’s a lot of details about the various keyword arguments in setup.py's setuptools.setup() function call.)
Use piptools to manage the requirements.txt file.
Don’t use setup.py's own upload feature, use twine instead.
Develop Mode (any file changes made to your source won’t have to be reinstalled with pip): pip install -e .

3 - Packaging a python library - Ionel Cristian Mărieș's Blog

Link to the blog post.

My summary of this blog post: This is about packaging libraries for other Python software developers to use in their applications, not on packaging applications. It’s a good list of how to layout all the different parts of a library.

Put your Python module in /src/packagename, not in /packagename. This gives you “import parity”: it forces you to install the package just like your users would have to. Otherwise, if you run Python from the root of your repo, import packagename would import /src/packagename just fine, but this means you don’t have to go through the install process that your users would and you could miss potential errors they’d face.
Don’t import your package from your setup.py file, i.e. your setup.py shouldn’t have import packagename in it. You don’t want to do this, because if your package imports other dependencies, those dependencies might not be installed yet and this causes distribution installation errors.
Having a /src folder lets you just add graft src to your MANIFEST.in file, which is simple.
“Flat is better than nested” but not for data.
Don’t put your tests folder inside your src or packagename folder.
Whenever the setup.py file opens a file, it specifies an encoding. Note that for python 2/3 compatibility, it uses io.open() instead of open(), since Python 2’s open() doesn’t have an encoding keyword argument.
Don’t use python setup.py test to run your tests; that’s outdated. Travis-CI has become the de factor standard for running tests after checking in code. Tox is a good way to run tests locally.
Ionel has a sample project layout here: https://github.com/ionelmc/python-nameless
Use cookiecutter to generate these files (tox.ini, MANIFEST.in, etc.)

4 - Testing & Packaging - Hynek Schlawack's Blog

Link to the blog post.

My summary of this blog post: This blog article sort of assumes you are already familiar with tox and coverage.py. It doesn't really hold your hand with its examples. Though it did introduce me to detox, which is a drop-in replacement (rather, an addition) to tox that lets you run the different tox environment tests in parallel.

Put your modules in a separate src folder. This simplifies what you need in your setup.py:

    setup(
        ...
        packages=find_packages(where='src'),
        package_dir={'': 'src'},
    )

"Combined coverage" means not just measuring your code coverage with one version of Python, but across all the versions you test with tox. If you have 100% coverage in Python 3, but less with Python 2, then that affects your overall combined coverage percentage.

5 - Grug make fire! Grug make wheel! by Russell Keith-Magee - PyCon Australia 2014

Link to YouTube video.

My summary of this talk: Kind of old, being from 2014, but has some good basic information about setup.py. He also covers the difference between universal wheels and platform wheels. A good, basic overview of Python packaging, and I think this talk touched on things the other basic Python packaging talks didn’t touch on, so it makes sense to watch this along with other basic packaging talks.

Wheel files - Contains binary files & compiled code. This is much more ready-to-use than a source distribution (sdist).
Eggs were intended to be an executable file, not just a distribution file. Wheels are just for distribution, you don’t “execute a wheel file” or “run a wheel file”.
Russ goes into a project folder layout, which includes: README, LICENSE, package folder, docs folder, tests folder.
Other tools you might find useful: tox (for running unit tests on different versions of Python all at once), sphinx (for creating documentation, which can then be uploaded to readthedocs.org).
To put your module into a package, you need: setup.py, setup.cfg, MANIFEST.in.
Note: python setup.py bdist_wheel might come up with an error because the bdist_wheel command was used in older versions of pip. I believe python setup.py bdist replaces it, or you can run pip install wheel to get the bdis_wheel command just in case older scripts require it.
setup.cfg is a config file is optional, but includes options for setup.py so you don’t need to specify them as command line arguments.
MANIFEST.in describes what files need to be in the distributable that isn’t a .py file (docs, tests, etc.)
Use check-manifest can check the MANIFEST.in file.
Use bumpversion to be sure to update the version number in your file.
If your code is pure-Python, only runs on Python 2 & 3 and has no C extensions, you can create a “universal wheel” with python setup.py bdist_wheel --universal (or you can have a setup.cfg with universal set to 1 there).
If you do have C extensions, you need to create a wheel file.
If all else fails, you can use a source distribution python setup.py sdist, but any C extensions will have be compiled by the user.
Don’t use python setup.py register because it passes in your username/password unencrypted. Instead, log in to PyPI with your web browser and create it through the website.
Twine uses encryption, but also lets you test your package that you created with python setup.py before uploading it with Twine.
Bootstrapping pip: If you don’t have it, then (for pre Python 3.4) you can run python get-pip.py or (for Python 3.4 and later) you can run python -m ensurepip. But pip should automatically be included with Python 3.4 and later.
Python 3.4 also includes virtualenv.

6 - Glyph - Shipping Software To Users With Python - PyCon 2016

Link to YouTube video.

My summary of this talk: Getting software onto a production server or running on end user’s desktop still requires a few different steps, but the tools for doing this are out there and exist. This talk touches on many of those tools and the issues in using them. This talk also has a great set of “bad practices” that can help you avoid making some common mistakes.

“Package” in most software senses (like a Redhat Package Manager package) is called a “distribution” in Python (specifically a “distutils distribution”. “Package” in Python refers to those folders that contain a init.py and main.py and so on. They’re more of a namespace.
A distutils distribution comes, for example, in a wheel file.
PYTHONPATH was used in the past, but don’t use it today.
Don’t use sudo pip install. Don’t install stuff using your operating system’s Python installation (i.e. “System Python”).
Don’t use python setup.py install, instead use pip. For one, there’s no python setup.py uninstall
Virtualenv creates lightweight Python environments. They’re about a 1/10 of the full Python environment but safely isolated (for the most part).
Don’t have a C compiler on the server machine, since it’ll compile to different compiled bits in each deployment. The “Ana Karenina Principal” comes from a line in Tolstoy’s novel: “All happy families are alike, but all unhappy families are unhappy in different ways.” Also true of unhappy servers. Having a C compiler can also slow down your deployments. Don’t have build tools on your production server, which means you don’t want to ship source distributions to your servers.
For library module developers Requirements.txt should have exact versions specified.
Shipping software to end users is more rocky. (Let’s assume that getting Python is easy to install, and we can get pip. )
pip install --user can install stuff to the user’s home directory, but now they also have to configure their shell so that Python can find it. This is less than ideal for deploying applications.
GUI applications in Python: using py2app to get Python GUI applications on Macs. Py2App builds effectively a self-contained Python environment that is an application by itself.
py2exe and py2installer does the same thing on Windows.
cx_Freeze is cross-platformed.
These tools that can distribute GUI desktop applications to users tend to over-optimize: they read the source for import statements so they only include them and not everything. This goes against Python’s dynamic nature; namespace packages (import zope.interface, import flufl.enum) will likely break.
You can just import all of these modules in your initial script. It’s kind of tedious.
PyBee’s Briefcase project is good for packaging up stuff for various platforms.
pynsist is great for making Windows installers.
My takeaway: The Python packaging ecosystem is large and intimidating, but there’s a lot of really cool tools that have been made for taking on this problem from a variety of angles. It can be hard to know where to start, and there seems to be a “last mile” problem: it’s still not obvious to non-developers how to install Python software.

7 - Python Packaging User Guide

Link to documentation.

My summary of this website: This is the official Python packaging documentation, so it has complete information but may be a bit much all at once. I'd start here: Installing Packages

8 - Mahmoud Hashemi - BayPiggies September 2017 at LinkedIn: The Packaging Gradient

Link to YouTube video.

My summary of this talk: With some humor, Mahmoud covers a lot of the issues devs face when they don’t know about Python’s packaging ecosystem and start reinventing things from scratch. “The Packing Gradient” is his concept of how deep into the packaging ecosystem you need to get depending on how complicated your software is. There’s info about Anaconda & packaging that I didn’t see anywhere else. But in general, not directly related to how to do Python packaging.

https://speakerdeck.com/mhashemi/the-packaging-gradient-extended-edition
“Packaging” is getting your code into some kind of file to send to other people.
Packaging is something developers don’t consider until the end of development, but this is a mistake and leads to reinventing existing tools.
Packaging a standalone Python module (one .py file). “Standalone” means it only imports from the standard library. For example, bottle.py (which inspired Flask (and the name “Flask”)) is a single file. Standalone modules are easy to distribute and integrate, you basically just copy the file.
“Vendoring” is including software you didn’t write in your software.
“Artifacts” are the files you want your build process to produce: .dll or .exe for compiled stuff, or a .zip file or .whl file for a Python distribution.
Packaging a pure-Python package: Note that “package” in Python means a folder with a init.py file in it. They only have Python files in them. For example: Django, requests. These are easy to install with pip.
PIP stands for “PIP Installs Packages”
“Distribution” is a file (like a zip file) that contains zero or more Python packages. (“Distribution” is what Python calls what most package managers like RPM would call a “package”.)
Distributions are built by setuptools with a setup.py file. Making a distribution file is great for pure-Python modules.
“You can have multiple distributions providing the same package”, for example, PIL and Pillow where someone forked PIL to make Pillow. PIL wasn’t updated and Pillow has PIL’s code but with a new distribution name on PyPI but the same package names. That is, you can run pip install pillow but still use the old from PIL import Image code you’ve always been using before Pillow.
He mentions the left-pad incident which is a good case study to read on: https://www.theregister.co.uk/2016/03/23/npm_left_pad_chaos/
“Python is slow” is misleading: One of Python’s strengths is its interoperability: after all, numpy isn’t slow.
If you distribute sdist (“source distributions”) you’ll be sending out uncompiled C code, which isn’t ready to use on the platform you’re installing to. We have wheel files: they have binary distributions (bdist) for compiled C code. Supports most Windows, Mac, and Linux. The “manylinux 1” tag is used as for generic Linux platform that wheel files target.
(Wheel files replace egg files, so you can forget about egg files. Egg files are obsolete.)
Note: He has python setup.py sdist bdist_wheel upload as the modern way to build and upload a Python package, but these days Twine replaces the upload command. (This talk was in September 2017.)
But wheel files aren’t what you use to install, say, applications on your phone or whatever.
“PyPI is not an app store” (it’s free for one thing, but also Python is too general purpose for just apps). Installing by pip from PyPI requires a working Python & pip installation, an internet connection, preinstalled system libraries (like lxml requires libxml2), and build tools for target packages (like gcc/clang). But more than anything, pip requires a knowledgeable software developer. Pip isn’t that great for end users who don’t know how to debug pip’s install error messages.
So how do we ship applications like Sublime Text or EVE Online or whatever?
PEX (Python EXecutable) results in a single runnable file. No setup or install step. You can wget this file and then just run it. It uses Python’s zipimport module. (zipapp is more or less PEX.) PEX is good for distributing standalone Python scripts. A 15-minute lightning talk on PEX: “WTF is PEX?” https://www.youtube.com/watch?v=NmpnGhRwsu0 (The lightning talk is a bit hard to follow, but I did learn about python . runs the main.py file in the current folder)
Anaconda has conda install your_application, for example, you can conda install postgres and conda install nginx or even install other versions of Python! Anaconda is a whole new ecosystem. It’s not just Python-specific.
Anaconda is a cross-platform, Python-first package management and social app store. It’s like a Python version of Steam, pkgsrc, and Nix/Enlambda.
Mahmoud likes to recommend conda install over pip install for non-developers.
Freezers: Provide installers, include Python. Dropbox, EVE Online, Civilization IV, any Kivy apps have a full runtime Python included with the app. Examples: cx_Freeze, PyInstaller, osnap, bbFreee, py2exe, py2app, pynsist, nuitka.
Freezers represent the best option for consumer software.
“Enterprise” Freezer like Omnibus. Example: GitLab. Best for shipping applications with multiple components (services, queues, etc)
Userspace images - include their own environment.
Containers - like userspace images but also with sandboxing. Example: Flatpak/Snappy, Docker. These only work on Linux, reuire a container runtime, has a “pull” step. Can easily be gigabytes in size.
Virtual machine - includes an entire OS kernel, along with everything containers have. Can work on any OS, is gigabytes in size. There is no “VM Image” app store, users have to download it directly from your site.
Hardware - ha! They just ship you the computer: they’re basically appliances that sit on a server rack. Think: routers that let you include your own Python code.

9 - Kenneth Reitz - Pipenv: The Future of Python Dependency Management - PyCon 2018

Link to YouTube video.

Packaging history: We had the Cheeseshop, which was only an index of packages; you had to host your packages on your own website. Packages were installed with python setup.py install but you couldn’t uninstall them. Easy_install made this process easier, but there was still no uninstall. From 2010 onward, pip & virtualenv & requirements.txt files were the norm.
Ruby doesn’t have virtual environments because they can have multiple versions of a package installed at the same time, unlike Python.
Other communities (Node.js’s yarn & npm, PHP’s Composer, Rust’s Cargo, Ruby’s Bundler) all use a lockfile.
Venv has downsides: it’s hard for new-comers to understand, its a manual process (though virtualenv-wrapper helps with this).
The requirements.txt file has a problem: it can represent what you want installed, and it can represent what you need installed. (pip-tools was created to ease the pain of installing packages you need.)
pip freeze shows you a pre-flattened list of required packages: it includes the project’s dependencies, but also the dependencies’ dependencies. So it can be hard to see which packages are really required for your project and what packages are installed because they are dependencies of those required packages. (This is what we mean by “pre-flattened”; you can’t tell which is which between dependencies and dependencies’ dependencies.)
You could just specify the few packages you need, but then you have non-deterministic builds: the subdependencies will be whatever latest version is out there. So building one day may have different (that is, newer) subdependency packages installed. This uncertainty and different behavior can cause hard-to-debug bugs.
The requirements.txt file can be a lockfile and not a lockfile depending on how you use it. We need to split this up into two files.
The pipfile is a new standard from the PyPA (Python Packaging Authority) (specifically from Donald Stufft) that is replacing the requirements.txt file. It’s written in TOML (an .ini-like language)
Example pipfile:

[[source]]
url = "https://pypi.python.org/simple"
verify_ssl = true
name = "pypi"

[packages]
flask = "*"

[dev-packages]
pytest = "*"

Pipenv lets you use pipfile & pipfile.lock, it uses virtualenv but hides all the details of it from you. Pipenv mostly replaces virtualenvwrapper. The [dev-packages] section specifies what will be installed when pipenv install --dev is run.
Demo:

pipenv install requests (Creates the virtual environment, the pipfile, and the pipfile.lock file.)

Once this virtual environment is created by pipenv, you can run pipenv shell to activate it. The virutal environment exists in HOME/.virtualenvs. Running pipenv -- venv will show you where the virtual environment files are stored.
The created pipfile file only has the requests library in it, while the pipfile.lock file has all of its subdependencies with exact version numbers (and hashes, in case the package maintainer changes it but reuses the version number) for each one.
According to https://github.com/pypa/pipenv/issues/598 you should commit pipfile.lock to source control.
Pipenv is very folder-specific. If you move the project folder to a new location, you’ll lose the virtual environment. But that’s okay, because you can just run pipenv install and it will use the existing Pipfile.lock file to install all the modules again.
Running pipenv graph will give a nice dependency tree.
Running pipenv check will check for security vulnerabilities.
Running pipenv install --deploy will do ???. It also checks if Pipfile nad Pipfile.lock are in sync (they must be kept in sync with each other).
If you have an existing .venv folder in your project folder, than pipenv install will use it instead of the central folder for all virtual environments.
Running pipenv --three creates a virtual environment with Python 3. You can later run pipenv --two and it destroys the old virtual environment and creates a new one with Python 2.
Running pipenv lock -r will output a requirements.txt file.
Running pipenv sync will uninstall any packages you no longer need.
Pipenv does NOT replace setup.py. Pipenv is for applications, while setup.py is used for libraries. Kenneth would not check in the lockfile for libraries that could be targetting multiple versions of Python.
Don’t get pipenv confused with pyenv.

Updated 2021/12/12: New recorded talks added.

Writing Bots to Play Zombie Dice

2018-10-17T12:00:00-04:00

Note: I'm looking for feedback for my Zombie Dice simulator, as well as for this set of instructions. If there's any part that you feel could be improved, please email me at al@inventwithpython.com.

Programming games are a games genre where instead of playing the game directly, players write bot programs to play the game autonomously. I've created a Zombie Dice simulator, allowing programmers to practice their skills while having fun making game-playing AIs. Zombie Dice bots can be simple or incredibly complex, and are great for a class exercise or an individual programming challenge.

How to Play Zombie Dice

Zombie Dice is a quick, fun dice game from Steve Jackson Games. The players are zombies trying to eat as many human brains as possible without getting "shotgunned". There is a cup of 13 dice with icons of brains, footsteps, and shotguns on their faces. The dice are colored green (brains are more likely), red (shotguns are more likely), and yellow (evenly split between brains and shotguns).

On their turn:

The player randomly pulls dice from the cup until they have three in their hand, and rolls them. Players always roll exactly three dice.
They set aside any brains (humans whose brains were eaten) and shotguns (humans who fought back).
If the player has set aside three shotguns on this turn, their turn ends with zero points.
The player keeps any dice that came up footsteps in their hand if they decide to roll again.
Otherwise, the player can choose to end their turn, where they'll collect one point per brain and return all dice to the cup for the next player.
Or the player can choose to continue their turn and roll again. Go back to step 1, noting any dice already in hand that came up footsteps will be reused.

Zombie Dice has a "push your luck" game mechanic: the more you re-roll the dice, the more brains you can get but the more likely you'll eventually accrue three shotguns and lose everything. Once a player reaches 13 points, the rest of the players get one more turn (to potentially catch up) and the game ends. The player with the most points wins.

More complete rules for Zombie Dice can be found here:

Bot Programming Challenge

To install the simulator with pip, run pip install zombiedice (on Windows) or pip3 install zombiedice (on macOS and Linux). To run a demo with some pre-made bots, run python -m zombiedice (on Windows) or python3 -m zombiedice (on macOS and Linux) to see an example of the simulator's web gui:

The simulator can quickly run hundreds of games, noting how many wins and ties each bot got.

You'll create bots by writing a class with a turn() method, which is called by the simulator when it's your bot's turn. Inside this turn() method, you'll call the zombiedice.roll() function as often as you want to roll the dice (though you should call it at least once on your turn, of course). Classes are beyond the scope of this article, but you can simply change the turn() code in myzombie.py:

import zombiedice

class MyZombie:
    def __init__(self, name):
        self.name = name

    def turn(self, gameState):
        # gameState is a dict with info about the current state of the game.
        # You can choose to ignore it in your code.

        diceRollResults = zombiedice.roll() # first roll
        # roll() returns a dictionary with keys 'brains', 'shotgun', and
        # 'footsteps' with how many rolls of each type there were.
        # The 'rolls' key is a list of (color, icon) tuples with the
        # exact roll result information.
        # Example of a roll() return value:
        # {'brains': 1, 'footsteps': 1, 'shotgun': 1,
        #  'rolls': [('yellow', 'brains'), ('red', 'footsteps'),
        #            ('green', 'shotgun')]}

        # The code logic for your zombie goes here:
        brains = 0
        while diceRollResults is not None:
            brains += diceRollResults['brains']

            if brains < 2:
                diceRollResults = zombiedice.roll() # roll again
            else:
                break

class AlwaysRollsTwicePerTurn:
    def __init__(self, name):
        self.name = name

    def turn(self, gameState):
        zombiedice.roll()
        zombiedice.roll()


zombies = (
    zombiedice.examples.RandomCoinFlipZombie(name='Random'),
    zombiedice.examples.RollsUntilInTheLeadZombie(name='Until Leading'),
    zombiedice.examples.MinNumShotgunsThenStopsZombie(name='Stop at 2 Shotguns', minShotguns=2),
    zombiedice.examples.MinNumShotgunsThenStopsZombie(name='Stop at 1 Shotgun', minShotguns=1),
    MyZombie(name='My Zombie Bot'),
    AlwaysRollsTwicePerTurn(name='Rolls Twice'),
    # Add any other zombie players here.
)

# Uncomment one of the following lines to run in CLI or Web GUI mode:
#zombiedice.runTournament(zombies=zombies, numGames=1000)
zombiedice.runWebGui(zombies=zombies, numGames=1000)

The code in the MyZombie class's turn() method keeps calling zombiedice.roll() until it has rolled at least two brains. A second bot is implemented in the AlwaysRollsTwicePerTurn class, which has a turn() method that simply rolls the dice twice on every turn. Running this program calls runWebGui() and brings up the web browser as shown in Figure 6-1, ready to run the simulation. You can examine the source code in the zombiedice package's examples.py file to see how the other bots work.

Try writing some of your own bots to play Zombie Dice, and see how they compare against the other bots. And if you find yourself playing this game in the real world, you'll have the benefit of thousands of simulated games telling you that one of the best strategies is to simply stop once you've rolled two shotguns. But you could always try pressing your luck...

Constructing MyZombie, Step by Step

I'll describe the though process of creating the MyZombie class in the previous section. Start with this basic template that imports the zombiedice module, creates a class with a turn() method that calls zombiedice.roll(), and then runs a tournament:

import zombiedice

class MyZombie:
    def __init__(self, name):
        self.name = name

    def turn(self, gameState):
        zombiedice.roll()

zombies = (
    zombiedice.examples.RandomCoinFlipZombie(name='Random'),
    MyZombie(name='My Zombie Bot'),
)

# Uncomment one of the following lines to run in CLI or Web GUI mode:
zombiedice.runWebGui(zombies=zombies, numGames=1000)

The MyZombie so far only rolls the dice one, which is a very conservative strategy that is unlikely to get many points. To decide if it should roll again, we'll need to examine the return value of zombiedice.roll(), which is a dictionary that shows the results of the roll of the three dice. It would look something like this:

{'brains': 1, 'footsteps': 1, 'shotgun': 1,
 'rolls': [('yellow', 'brains'), ('red', 'footsteps'),
           ('green', 'shotgun')]}

This dictionary has a 'brains', 'footsteps', and 'shotgun' key with values that are the number of that kind of roll. The exact rolls are in the 'rolls' key's value: a list of tuples. Each tuple represent a die, composed of a color and the icon that came up.

Let's say we want to program the strategy that our zombie will keep rolling until it has at least two brains rolled. We would need to keep track of how many brains have been rolled so far on this turn (in a brains variable), which starts at 0. If a future call to zombiedice.roll() ever returns None, then we know that we've reached or exceeded three shotguns on this turn and will get zero points. Update turn() so that it looks like this:

    def turn(self, gameState):
        diceRollResults = zombiedice.roll()
        brains = 0
        while diceRollResults is not None:
            diceRollResults = zombiedice.roll()

Now the code will keep rolling the dice until it returns None. But at that point, we've reached three shotguns and lost the turn. We need to add in logic so that at some point the method returns before zombiedice.roll() starts returning None. Let's examine diceRollResults to see how many brains were rolled:

    def turn(self, gameState):
        diceRollResults = zombiedice.roll()
        brains = 0
        while diceRollResults is not None:
            brains += diceRollResults['brains']

            if brains < 2:
                diceRollResults = zombiedice.roll()

That's better, now zombiedice.roll() is only called as long as we've yet to reach two brain rolls on our turn. However, there's no condition where this method changes. It'd just loop forever! Let's add a bit more code:

    def turn(self, gameState):
        diceRollResults = zombiedice.roll()
        brains = 0
        while diceRollResults is not None:
            brains += diceRollResults['brains']

            if brains < 2:
                diceRollResults = zombiedice.roll()
            else:
                break

This new code says that if we've rolled at least two brains, go ahead and break out of the loop and eventually return from the method, which tells the simulator that the bot is done with its turn.

The value passed for the gameState parameter is a dictionary with the following keys:

'CURRENT_ZOMBIE' - string of the zombie whose turn it is currently
'CURRENT_CUP' - list of dice strings (i.e. 'red', 'yellow', 'green') in the cup
'CURRENT_HAND' - list of dice being rolled (should always be length of three)
'SHOTGUNS_ROLLED' - number of shotguns rolled so far on this turn
'BRAINS_ROLLED' - number of brains rolled so far on this turn
'ROLLED_BRAINS_DETAILS' - list of dice strings for each brain rolled, used in the rare event we run out of brain dice
'TURN_START_TIME' - time since unix epoch that the current turn began

Ideas for Other Bots

There's plenty of strategies you can try in Zombie Dice. Try writing bots that do the following:

A bot that has a 50% chance of choosing to re-roll. See how this bot compares against a bot with a 25% or 75% chance to re-roll.
A bot that stops re-rolling when it reaches two shotguns.
A bot that stops re-rolling when it reaches two shotguns, unless it isn't in the lead. (Check the gameState dictionary to find this information.)
A bot that rolls as long as there are green dice left in the cup. (Check the gameState dictionary to find this information.)

Be sure to check out the examples.py file in the module for the code to some bots that have already been made. Then load them up in the simulator and see how they perform!

PyOhio 2018 Recursion Tutorial

2018-08-24T12:00:00-04:00

This page has materials for folks taking my two-hour tutorial, A Beginner's Guide to Tackling Recursion at PyOhio 2018 or following its video recording.

You can watch the recorded video of this tutorial on YouTube.

Note: I don't think I did a particularly good job with this tutorial. You may want to watch my North Bay Python talk on recursion instead.

Pre-Tutorial Setup

To take this tutorial, you'll need:

A computer with Python installed.
To know how to launch the interactive shell, so you can follow along with the examples.
To know how to launch a text editor, so you can save and run .py files.
A beginner's level understanding of Python, including variables, loops, defining functions, lists, and dictionaries. That's it, really.

It's strongly recommended that you type the code as you follow along with this tutorial. This helps build the "muscle memory" of coding, and is much more effective for learning than simple watching the tutorial.

Handout form

(Filled out handout form)

Slides

Objectives

By the end of this tutorial, you'll learn:

What recursion is, in terms of actual code.
How recursion isn't a difficult so much as a poorly taught one.
What are stacks and the callstack, and how does recursion use them?
What is a stack overflow, and how does a base case prevent it?
What are recursive and base cases?
How recursive algorithms can't do anything that an iterative solution can do.
How caching/memoization and tail call elimination prevent common problems in recursive algorithms.
What are the types of problems where recursion is better than iteration.

Code Examples

Not all of the programs in this git repo are featured in the tutorial, but you can find code examples here: https://github.com/asweigart/recursion_examples

It isn't necessary to review this code before the tutorial.

The visualization tool used to explore these programs is http://pythontutor.com/

The Zen of Python, Explained

2018-08-17T12:00:00-04:00

The Zen of Python by Tim Peters are 20 guidelines for the design of the Python language. Your Python code doesn’t necessarily have to follow these guidelines, but they’re good to keep in mind. The Zen of Python is an Easter egg, or hidden joke, that appears if you run import this:

>>> import this
The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

NOTE: Mysteriously, only 19 of the guidelines are written down. Guido van Rosum reportedly said that the missing 20th aphorism is “some bizarre Tim Peters in-joke.”

In the end, these guidelines are opinions that can be argued for or against. Like all good sets of moral codes, they sometimes contradict themselves to provide the most flexibility. Here’s my own interpretation of these aphorisms:

Beautiful is better than ugly.

Programmers often write code quickly without concern for readability. While code doesn’t have to be readable, the code of the Python language itself must be thought out, consistent, and a joy to use. Of course, not every script needs to be beautiful, and beauty is subjective, but much of Python’s popularity is a result of being so easy to work with.

Explicit is better than implicit.

“This aphorism is self-explanatory,” that would be a terrible explanation for any aphorism. Similarly, it’s better for code to be verbose and explicit. You should avoid hiding code’s functionality behind obscure language features that require familiarity to fully understand.

Simple is better than complex. Complex is better than complicated.

These two aphorisms remind us that building anything can be done using simple or complex techniques. With a simple problem, such as building a birdhouse, a simple solution is better. Building a diesel train engine, on the other hand, is a complex problem that requires complex techniques. Even if you could technically make a diesel train engine using birdhouse techniques, you probably would end up with a complicated, Rube Goldberg arrangement of birdhouse parts that wouldn’t be an ideal solution. Prefer simplicity to complexity, but know the limits of simplicity.

Flat is better than nested.

Programmers love to organize things into categories, especially categories that contain subcategories which contain other sub-subcategories. These hierarchies often don’t add organization so much as they add bureaucracy. It’s okay to have code in just one top-layer module or class instead of split up across multiple submodules or subclasses. If you make packages and modules that require code like import spam.eggs.bacon.ham.foo.bar, then you’re making your code too complicated.

Sparse is better than dense.

Programmers often like to cram as much functionality into as little code as possible, such as one-liners like the following: print('\n'.join("%i bytes = %i bits which has %i possible values." % (j, j*8, 256**j-1) for j in (1 << i for i in range(8)))). While code like this may impress their friends, it’ll infuriate their coworkers who have to try to understand it. Code that is spread out over multiple lines is often easier to read than dense one-liners.

Readability counts.

While strcmp() may obviously mean the “string compare” function to someone who has been programming in C since the 1970s, modern computers have enough memory to write out the full function name. Don’t drop vowels from your names or write overly terse code. Code is read more often than it’s written, so explicit, readable code is more important than terse, undocumented code.

Special cases aren’t special enough to break the rules. Although practicality beats purity.

These two aphorisms, which come as a set, contradict each other. Programming is full of “best practices” that programmers should strive for in their code. Skirting these practices for a quick hack may be tempting, but can lead to a rat’s nest of inconsistent, unreadable code. However, bending over backwards to adhere to rules can result in highly-abstract, unreadable code. The Java programming language’s attempt to fit all code to its object-oriented paradigm often results in lots of boilerplate code for even the smallest program. Walking the line between these two aphorisms becomes easier with experience. And in time, you’ll not only learn the rules, but also learn when to break them.

Errors should never pass silently. Unless explicitly silenced.

Just because programmers often ignore error messages doesn’t mean the program should stop emitting them. Silent errors can happen when functions return error codes or None instead of raising exceptions. These two aphorisms tell us that it’s better for a program to fail fast and crash than to silence the error and continue running the program. The bugs that inevitably happen later on will be harder to debug since they are far removed from the original cause. Though you can always choose to explicitly ignore the errors your programs cause, just be sure you are making the conscious choice to do so.

In the face of ambiguity, refuse the temptation to guess.

Computers have made humans superstitious: To exorcise the demons in our computers we perform the sacred ritual of turning them off and then on. Supposedly this will fix any mysterious problem. However, computers are not magic. If your code isn’t working, there is a reason and only careful, critical thinking will solve it. Refuse the temptation to blindly try solutions until something seems to work; often you have merely masked the problem rather than solved it.

There should be one—and preferably only one—obvious way to do it.

This is a broadside against the Perl programming language’s motto, “There’s more than one way to do it!” It turns out that having three or four different ways to write code that does the same thing is a double-edged sword: you have flexibility in how you write code, but now you have to learn every possible way it could have been written in order to read it. This flexibility isn’t worth the 3x or 4x effort needed to learn a programming language.

Although that way may not be obvious at first unless you’re Dutch.

This line is a joke. Guido van Rossum, the creator and BDFL (Benevolent Dictator for Life) of Python, is Dutch. However, not even this aphorism prevented Python from incorporating three different ways of formatting strings.

Now is better than never. Although never is often better than right now.

These two aphorisms tell us that code that hangs or gets caught in infinite loops is obviously worse than code that doesn’t. However, it’s almost certainly better to wait for your program to finish than to have it finish too early with incorrect results.

If the implementation is hard to explain, it’s a bad idea. If the implementation is easy to explain, it may be a good idea.

Python strives to make the programmer’s job easier rather than accommodate the computer so a program runs faster. And programs need to be understandable not just by the programmer who wrote it, but also by other programmers who maintain the code. These two aphorisms remind us that if “high-performance” code is so complicated as to be impossible for programmers to understand and debug, then it’s bad code. But alas, just because it’s easy to explain a program’s code to someone else doesn’t mean it isn’t bad code. Programming is hard.

Namespaces are one honking great idea—let’s do more of those!

Namespaces (and also global and local scopes) are key for preventing names in one module or scope from conflicting with names in another. But also remember that flat is better than nested: As great as they are, namespaces should be made only to prevent naming conflicts, and not to add needless categorization.

Like all opinions about programming, the ones I’ve written here can be argued against or may simply be irrelevant to your situation. Arguing over how code should be written is rarely as productive as you think it is. (Unless you’re writing an entire book full of programming opinions.)

Python's Fake Increment and Decrement Operators

2018-05-21T12:00:00-04:00

In Python, you can increase the value of a variable by 1 or reduce it by 1 using the augmented assignment operators. The code spam += 1 and spam -= 1 increments and decrements the numeric values in spam by 1, respectively.

Other languages such as C++ and Java have the ++ and -- operators for incrementing and decrementing variables. (The name of C++ itself reflects this; the name is a tongue-in-cheek joke that indicates it's an enhanced form of the C language.) Code in C++ and Java could have ++spam or spam++. Python wisely doesn't include these operators; they are notoriously susceptible to subtle bugs.

However, it is perfectly legal to have the following Python code:

>>> spam = 42
>>> spam = ++spam
>>> spam
42
>>> spam = --spam
>>> spam
42

The first thing you notice is that the ++ and -- "operators" in Python don't actually increment or decrement the value in spam. Rather, the leading - is Python's unary negation operator. It allows you to have code like this:

>>> spam = 42
>>> print(-spam)
-42

It's legal to have multiple unary negative operators in front of a value. With two of them, you'd get the negative of the negative of the value, which for integer values just evaluates to the original value:

>>> print(--spam)
42
>>> --42
42

This is a quite silly thing to do, and you won't ever see a unary negation operator used twice in real-world code. (Though if you did, it's probably because the programmer learned to program in another language has just written buggy Python code!) There is also a + unary operator. It evaluates an integer value to the same sign as the original value, which is to say, it does absolutely nothing:

>>> +42
42
>>> spam = -42
>>> print(+spam) # +spam is not the same as abs(spam)
-42

Being able to write +42 (or ++42) seems just as silly as --42, so why does Python even have this unary operator? It exists only to complement the – operator if you need to overload these operators for your own classes. (See the documentation for the __pos__ special method.)

The + and – unary operators are only valid when in front of a Python value, not after it. While spam++ and spam-- might be legal code in C++ or Java, they produce syntax errors in Python:

>>> spam++
  File "<stdin>", line 1
    spam++
         ^
SyntaxError: invalid syntax

Python doesn't have increment and decrement operators, it's only a quirk of the langauge syntax that can make it seem like it does.

Python Tuples are Immutable, Except When They're Mutable

2018-02-05T12:00:00-05:00

Prologue

'When I use a word,' Humpty Dumpty said, in rather a scornful tone, 'it means just what I choose it to mean — neither more nor less.'

'The question is,' said Alice, 'whether you can make words mean so many different things.'

'The question is,' said Humpty Dumpty, 'which is to be master — that's all.'

Are Tuples Mutable or Immutable?

In Python, tuples are immutable, and "immutable" means the value cannot change. These are well-known, basic facts of Python. While tuples are more than just immutable lists (as Chapter 2 of Luciano Ramalho's excellent "Fluent Python" explains), there is a bit of ambiguity here. Luciano has written up a great blog post on this topic as well.

Before we can get a nuanced answer to "Are tuples mutable or immutable?", we need some background information.

Some Background Information

According to the Python data model, "objects are Python's abstraction for data, and all data in a Python program is represented by objects or by relations between objects". Every value in Python is an object, including integers, floats, and Booleans. In Java, these are "primitive data types" and considered separate from "objects". Not so, in Python. Every value in Python is an object, and Ned Batchelder's fantastic PyCon 2015 talk Facts and Myths About Python Names and Values" goes into more detail about this.

So not only is the datetime.datetime(2018, 2, 4, 19, 38, 54, 798338) datetime object an object, but the integer 42 is an object and the Boolean True is an object.

All Python objects have three things: a value, a type, and an identity. This is a bit confusing, because we often casually say, for example, "the value 42", although 42 is also called an object which itself has a value. But never mind that, let's continue with our 42 example. Enter the following into the interactive shell:

>>> spam = 42
>>> spam
42
>>> type(spam)
<class 'int'>
>>> id(spam)
1594282736

The variable spam refers to an object that has a value of 42, a type of int, and an identity of 1594282736. An identity is a unique integer, created when the object is created, and never changes for the lifetime of the object. An object's type also cannot change. Only the value of an object may change.

Let's try changing an object's value by entering the following into the interactive shell:

>>> spam = 42
>>> spam = 99

You may think you've changed the object's value from 42 to 99, but you haven't. All you've done is made spam refer to a new object. You can confirm this by calling the id() function and noticing spam refers to a completely new object:

>>> spam = 42
>>> id(spam)
1594282736
>>> spam = 99
>>> id(spam)
1594284560

Integers (and floats, Booleans, strings, frozen sets, and bytes) are immutable; their value doesn't change. Lists (and dictionaries, sets, arrays, and bytearrays), on the other hand, are mutable. This can lead to a common Python gotcha:

>>> spam = ['dogs', 'cats']
>>> eggs = spam  # copies the reference, not the list

>>> spam
['dogs', 'cats']
>>> eggs
['dogs', 'cats']

>>> spam.append('moose') # modifies the list referred by spam
>>> spam
['dogs', 'cats', 'moose']
>>> eggs
['dogs', 'cats', 'moose']

The reason eggs has changed even though we only appended a value to spam is because spam and eggs refer to the same object. The eggs = spam line made a copy of the reference, not the object. (You can use the copy module's copy() or deepcopy() functions if you want to copy a list object.)

The glossary in Python's official documentation says this about "immutable" (emphasis mine):

"An object with a fixed value. Immutable objects include numbers, strings and tuples. Such an object cannot be altered. A new object has to be created if a different value has to be stored."

The official Python documentation (and every other book, tutorial, and StackOverflow answer I've found) describes tuples as immutable. Conversely, the glossary says this about "mutable":

"Mutable objects can change their value but keep their id(). See also immutable."

Let's move on to discuss how value and identity affect the == and is operators.

`==` vs `is`

The == equality operator compares values, while the is operator compares identities. You can consider x is y to be shorthand for id(x) == id(y). Enter the following into the interactive shell:

>>> spam = ['dogs', 'cats']
>>> id(spam)
41335048
>>> eggs = spam
>>> id(eggs)
41335048
>>> id(spam) == id(eggs)
True
>>> spam is eggs  # spam and eggs are the same object
True
>>> spam == eggs  # spam and eggs have the same value, naturally
True
>>> spam == spam  # Just like spam and spam are the same object and have the same value, naturally
True

>>> bacon = ['dogs', 'cats']
>>> spam == bacon  # spam and bacon have the same value
True
>>> id(bacon)
40654152
>>> id(spam) == id(bacon)
False
>>> spam is bacon  # spam and bacon are different objects
False

Two different objects may share the same value, but they will never share the same identity.

Hashability

According to the glossary in the official Python documentation, "An object is hashable if it has a hash value which never changes during its lifetime", that is, if the object is immutable. (There are a couple other requirements concerning the __hash__() and __eq__() special methods, but that's beyond the scope of this post.)

A hash is an integer that depends on an object's value, and objects with the same value always have the same hash. (Objects with different values will occasionally have the same hash too. This is called a hash collision.) While id() will return an integer based on an object's identity, the hash() function will return an integer (the object's hash) based on the hashable object's value:

>>> hash('dogs')
-4064183437113369969

>>> hash(True)
1

>>> spam = ('hello', 'goodbye')
>>> eggs = ('hello', 'goodbye')
>>> spam == eggs  # spam and eggs have the same value
True
>>> spam is eggs  # spam and eggs are different objects with different identities
False
>>> hash(spam)
3746884561951861327
>>> hash(eggs)
3746884561951861327
>>> hash(spam) == hash(eggs)  # spam and eggs have the same hash
True

Immutable objects can be hashable, mutable objects can't be hashable. This is important to know, because (for reasons beyond the scope of this post) only hashable objects can be used as keys in a dictionary or as items in a set. Since hashes are based on values and only immutable objects can be hashable, this means that hashes will never change during the object's lifetime.

In the interactive shell, try to create a dictionary with immutable objects for keys by entering the following:

>>> spam = {'dogs': 42, True: 'hello', ('a', 'b', 'c'): ['hello']}
>>> spam.keys()
dict_keys(['dogs', True, ('a', 'b', 'c')])

All the keys in spam are immutable, hashable objects. If you try to call hash() on a mutable object (such as a list), or try to use a mutable object for a dictionary key, you'll get an error:

>>> spam = {['hello', 'world']: 42}
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unhashable type: 'list'

>>> d = {'a': 1}
>>> spam = {d: 42}
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unhashable type: 'dict'

Tuples, being immutable objects, can be used as dictionary keys:

>>> spam = {('a', 'b', 'c'): 'hello'}

...or can they?:

>>> spam = {('a', 'b', [1, 2, 3]): 'hello'}
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: unhashable type: 'list'

It seems that if a tuple contains a mutable object, it can't be hashed. (Raymond Hettinger explains, with lots of context, why immutable tuples can contain mutable values.) This fits with what we know: immutable objects can be hashable, but this doesn't necessarily mean they're always hashable. And remember, the hash is derived from the object's value.

This is an interesting corner case: a tuple (which should be immutable) that contains a mutable list cannot be hashed. This is because the hash of the tuple depends on the tuple's value, but if that list's value can change, that means the tuple's value can change and therefore the hash can change during the tuple's lifetime. But if we go back to the glossary definition of hashable, a hash is never supposed to change during the object's lifetime.

Does this mean that the value of tuples can change? Are tuples mutable?

So, Are Tuples Mutable or Immutable?

Before we can finally answer this question, we should ask, "Is mutability a property of data types or of objects?"

(Update: Our BDFL generally thinks it's of data types.)

Python programmers often say things like "strings are immutable, lists are mutable", which makes us think that mutability is a property of types: all string objects are immutable, all list objects are mutable, etc. And in general, I agree.

But in the previous section, we saw how some tuples are hashable (implying they're immutable) but some other tuples aren't hashable (implying they're mutable).

Let's go back to the official Python documentation's definition of immutable and mutable: "An object with a fixed value" and "Mutable objects can change their value", respectively.

So perhaps mutability is a property of objects, and some tuples (that contain only immutable objects) are immutable and some other tuples (that contain one or more mutable objects) are mutable. But every Pythonista I've run into says and continues to say that tuples are immutable, even if they're unhashable. Why?

In one sense, tuples are immutable because the objects in a tuple cannot be deleted or replaced by new objects. Just like spam = 42; spam = 99 doesn't change the 42 object in spam; it replaces it with an entirely new object, 99. If we use the interactive shell to look at a tuple that contains a list:

>>> spam = ('dogs', 'cats', [1, 2, 3])
>>> id(spam[0]), id(spam[1]), id(spam[2])
(41506216, 41355896, 40740488)

The same objects will always be in this tuple, and they will always have the same identities in the same order: 41506216, 41355896, and 40740488. Tuples are immutable.

However in another sense, tuples are mutable because their values can be changed. Enter the following into the interactive shell:

>>> a = ('dogs', 'cats', [1, 2, 3])
>>> b = ('dogs', 'cats', [1, 2, 3])
>>> a == b
True
>>> a is b
False

In this example, the tuples referred to by a and b have equal values (according to ==) but are different objects (according to is). Let's change the list in a's tuple:

>>> a[2].append(99)
>>> a
('dogs', 'cats', [1, 2, 3, 99])
>>> a == b
False

We have changed the a's value. We must have, because a is no longer equal to b and we didn't change b's value. Tuples are mutable.

Epilogue

'The question is,' said Humpty Dumpty, 'which is to be master — that's all.'

Humans are the masters of words, not the other way around. Words are invented by humans to convey ideas to other humans. Personally, I'm going to continue to say that tuples are immutable, because this is more accurate than not and the most helpful term in most contexts.

However, at the same time we should also be aware that from our definitions of "mutable" and "value", we can see that tuples' values can sometimes change, i.e. mutate. It isn't technically wrong to say that tuples can be mutable, though it will certainly raise eyebrows and require more explanation.

Thank you for sitting through my, what turned out to be lengthy, explanation on tuples and mutability. I certainly learned a lot in writing this post, and hope I conveyed it to you as well.

How To Ask For Programming Help

2018-02-02T12:00:00-05:00

Hello! If you've asked for programming help and then someone gave you a link to this page, you probably need to give more information about your problem. In the next section I explain why I'm so slow to reply (or often don't reply at all) but you can skip directly to instructions for how to ask programming questions.

Why I Didn't Reply To Your Email Yet (or Ever)

I often get emails say little more than "Why doesn't my program work?" Often I can't answer them; either I don't have enough information about your problem or you're asking me about something I don't know anything about.

I like helping people learn to code. My books, videos, and online courses (most of which are free) have taught tens of thousands of people how to program. This is great! I'm amazed that the internet lets me cheaply share knowledge. I can reach more people in a few years online than a lifetime at the front of a classroom. But when people send me emails, I can only help one person at a time.

This article teaches you how to ask effective programming questions.

Is Email the Best Way to Ask Your Programming Question?

These are bad programming questions:

"Why doesn't my program work? I tried so many ways but no luck. Can you please help me out?" (What is your program? What's it supposed to do, and what's it doing instead?)
"Sometimes my program works, but sometimes I get an error when I run it." (What error? What's different between when you get it and when you don't?)
"My program can't find the file." (What file? What does your code look like?)
"My program doesn't work. Can you help me?" (Don't ask to ask, just ask.)

They're bad because they don't have enough information for your helper to answer them in one reply. In email conversations, there's a lot of waiting in between emails. To answer your question effectively, we need to cut down the amount of back-and-forth. The best way to do that is to not use email at all! Run through this checklist before clicking Send:

Before you email, consider posting the problem to the /r/inventwithpython subreddit or StackOverflow.

The /r/inventwithpython subreddit can answer your questions about code in my books faster than I can reply to your email.

StackOverflow is good for general programming questions, but read the short How do I ask a good question? page first. (This page is also good to read for anyone asking for programming help in general.)

Before you email, google your question. If you got an error message, copy and paste the exact error message into google.

You're not the first person to encounter this error, and someone else has probably answered your questions already. In this case, you'll get an answer much faster by searching the web for it.

Before you email, learn to use the debugger, and use the debugger.

A debugger lets you run through your code one step at a time, and examine what values are in your variables. IDLE comes with a debugger, and you can also always use the pdb debugger module. A debugger saves you much more time than it takes to learn how to use a debugger.

Put As Much Informataion in Your First Email As Possible

The next best way to cut down on the back-and-forth is to put as much information as possible in your first email. Go through the following checklist:

In your email, don't ask to ask. Just ask.

You don't have to say "I have a question about (something). Can you help me with this?" It isn't rude to just ask your programming question if you've taken the time to include all the information your helper needs to answer it.

In your email, use a descriptive subject line.

Pretend you're talking to a busy colleague and have to sum up your entire question in one sentence. Don't use "I need help" or "Can I ask you a question?" These subjects don't describe your question. I have dozens of emails like these, and it's hard to re-find an email later on.

If you are posting your question somewhere online, descriptive post titles make it easier for search engines to guide future people with your same question to your post (and the followup answers!)

It's rude to use a vague, demanding headline like, "HELP!!! My program keeps CRASHING. WHY DOESN'T ANYONE ANSWER ME?!?!?!1" Please don't do that.

In your email, show that you've done research.

Add something like, "I googled for (terms) and found a StackOverflow post at (url), but I don't understand what this person means when they say (something)." This shows that you respect your helper's time and tried to answer it yourself first. It also gives your helpers some leads to go off of.

In your email, don't just say what your program is doing, but also what the overall goal of your program. Make sure your questions have a question mark!

Emails like "I'm trying download a web page using Requets, but I'm getting stuck while return json format." aren't actually asking a question: There's no question mark! Your helper can't assume what the problem is or what you want your program to do: What do you mean by "getting stuck?" What web page are you downloading and why? What would your program specifically be doing if it was working properly?

With context, your helper can figure out if you're on the wrong path entirely. Maybe this is a problem you don't even need to solve!

In your email, copy and paste the full error message. If there is no error message, explicitly say that there was no error message.

Python error messages will look something like this:

Traceback (most recent call last):
File "test1.py", line 18, in <module>
spam()
File "test1.py", line 16, in spam
bar()
File "test1.py", line 13, in bar
foo()
File "test1.py", line 4, in foo
int(x)
ValueError: invalid literal for int() with base 10: 'twelve'

Your helper needs all of this information, especially the line numbers! The line numbers tell your helper exactly where the error is happening. Just telling your helper, "I got SyntaxError" doesn't tell them enough to know what's wrong.

In your email, send a pastebin link to the full source code of your program.

Your helper needs the complete, full source code to figure out what's wrong. Go to a "pastebin" site like https://pastebin.com/ or https://gist.github.com/. This way, your helper can run your program themselves.

Do not copy and paste the source code into the email itself. Blank lines at the top of the code will throw off the line numbers in the error message, and many email programs will get rid of the indentation, which renders the code unrunnable.

Do not send a screenshot of the code (or take a photo of your screen with your smartphone). Your helper often needs to run the code to figure out what's wrong, and they can't copy and paste the code from the image. It's rude to expect them to retype all of your code because you didn't want to.

In your email, say what operating system, operating system version, and version of Python you are using.

There are minor but possibly important differences between operating systems and Python versions. Telling me, "I'm running Python 3.6.2 on Windows 10" helps narrow down what could be causing your problem.

In your email, if you have a question about something in one of my books, tell me which book, chapter, and page number you were reading.

I've written several books, so "I can't get the program in your book to work" doesn't tell me which book and which program.

Conclusion

Going through this checklist makes it much more likely that you'll get a quick answer. It's always better to include too much information than not enough. Providing more information helps me help you. And posting to an online forum like the /r/inventwithpython subreddit allows many people to answer your question while creating a page that people in the future with a similar problem can find.

Good luck, and keep coding!

PS

A common question I get from readers is "what should I study/read/learn next?" If you've read Automate the Boring Stuff with Python, you might want to read my other books for free online. I also recommend Python Crash Course (you can skip directly to the second half if you're comfortable with Python) and Fluent Python and Effective Python. If you want practice writing simple programs, try the practice problems on Exercism.io or the /r/dailyprogrammer subreddit.

Lessons Learned from Creating a Udemy Course

2017-04-05T12:00:00-04:00

I've created two online courses through Udemy.com for my books. I initially created them to promote my books, but have actually made significant income from the courses themselves:

This post contains the lessons I've learned and my process for creating video tutorials, and I hope others who want to do the same find it useful. While this post is specific to Udemy and programming courses, the same lessons probably apply to all online courses.

The TL;DR

If you want to sell your course, you're limited to Udemy.
If you want to make a free course, post it to Udemy as well as YouTube.
Don't expect to make enough money to justify it as your job.
Don't expect to make any significant amount of money at all.
Almost all of your paying students bought your course through a huge discount, not the original price.
Your primary way of pushing your course is offering large discount codes that reduce the price to $10 or $15.
It'll take on the order of months to create a course.
Do several takes for each video, but record each of them as though they were the final take.
I prefer practicing the lines doing multiple takes over writing and reading off of a script.
I use Camtasia Studio ($200) to record my screen and edit the video.
I use Audacity (free) and the Noise Gate plugin (free) for post-production of the audio.
I use a Yeti USB microphone ($130) and Logitech c920 webcam ($65) because they're the best tradeoff between quality and cost.
You don't need to use a webcam to add a "talking head" to your videos.
You don't need to spend much money on your bedroom recording studio. Thick blankets hanging from ceiling hooks work well enough for sound-proofing.
Lower your screen resolution to 1280 x 720 so that video is quicker to stream and the text isn't too small to read.
Do a quick test video before each recording session. Make sure your mute button isn't on!
For the first couple of weeks, make your course free with discount codes. This builds the initial audience and reviews, which gives your course credibility.
Don't worry about people pirating your course to watch it for free.
Worry about people pirating your course and selling it themselves.

Which Site to Choose for Your Course

You're pretty much limited to Udemy.com if you want to charge for your course. EdX, Coursera, and most online course sites unless you're a professor affiliated with a university. Even if you're creating a free course to host on YouTube or Vimeo, Udemy can be an additional place to put your videos. The Udemy content requirements are good guidelines for YouTube and Vimeo videos anyway.

You could host the videos yourself, though you'd have to create the website, handle payments, and do all your own promotion. I recommend against this, especially for your first course, unless you know what you're doing.

How Much Money You'll Make and How

The Automate course, as of April 2017, has over 46,000 students signed up. Many of these students signed up for free with discount codes I provided. Most paying students will buy the course after being referred by a Udemy promotion with a substantial discount code. Through this promotion, no matter if you set your course for $50 or $500, these students probably paid $10 or $15 for the course. This is normal. Udemy will pay you about $1 or $2 for the students it signs up for your course. I didn't realize Udemy was selling my course at a discount at first. But I don't complain because most of my course's income comes from Udemy discount promotions. Don't worry about the steep discount and (generally) trust that Udemy knows how to sell your course.

Udemy, like a department store, is always running sales. I've paid for courses on the site myself, and can tell you that you should never pay full price for a course. Almost no one ends up buying your course at the original full price.

You can (and most definitely should) create discount codes. Udemy pays you almost the full price (less a dollar or two) for students who sign up using your discount code. If a student signs up for your $100 course using a 90% discount code you provided, Udemy will pay you about $8 or $9 of that $10. Again, this is normal. But it's also a great incentive to advertise your own course. I always push the discount code that lowers the price of my $50 course to $10, hence the FOR_LIKE_TEN_BUCKS discount code.

Again, even though I could make a lot more money per student by referring them myself, most of my Udemy income comes from students that Udemy found just because they find so many for me.

I'm really pleased that my Automate course has done so well: most courses get very few students to the point where it's really not worth the time to create the course. It'll get you beer money, but not much else. My course gets me a 4-figure sum per month (before taxes). Not nearly as much as I could make as a software developer, but enough to keep me from living entirely off savings.

I put a lot of hard work into my Automate course, but also I got lucky with it. On the other hand, my Scratch Programming Playground course only got me about $170 last month. And there's no telling what the popularity of my courses will be next year, or two years from now, or five years from now.

The Course's Videos

The Automate course took about four months to create its 50 videos totaling 9.5 hours. (Factor in that I originally wrote the course's content for the Automate book.) But it has definitely paid off considering that I now have it as a passive income stream and only need to answer maybe a half dozen student questions each week. This was my full-time job, but I had other projects too. If I focused only on creating the course, it could probably have been done in two or three months.

My videos are screencasts, where I use software to record the screen while I do a voice-over explanation. This format works well for programming courses: The students can see the code that I type into an interactive shell and hear me explain how it works.

You don't necessarily need a script, but:

Write down a detailed outline that you can consult while recording.
Expect to do three or four takes for each video. I'm almost never satisfied with the first take.
If you do practice takes, record them anyway as if you were doing a real take. There's something about having it recorded that makes me treat the take more seriously.
When you do a practice take, do the entire video from start to finish just as you would do for a real take.
Rather than immediately edit the video after recording it, I record several videos at a time, then edit several videos at time. It takes me a while to get comfortable recording, and I like to keep the ball rolling once I'm warmed up.

The most important thing about your videos is that they are concise and get to the point. The optimal video length is apparently 6 minutes. Udemy caps individual videos at 20 minutes. Most of my Automate course videos were between 9 and 13 minutes.

For my Python course, I also sometimes made use of pythontutor.com's visualization tool. Upload a program (it can't have third-party modules, text input, or file access) and it will create a debugger-like trace for each step of your program. To visualize the evaluation of individual expressions, I use my own ShowEval tool.

Recording Software

I'm on Windows 7 and I use Camtasia Studio (available for Windows and Mac) to record the screen and edit the videos. It can also record from a webcam and place it in your videos. Camtasia costs $200 ($170 for students and educators), though if leave your order in your shopping cart for a few days, they'll email you a discount to encourage you to complete the purchase. (This trick works on other websites, though not Amazon.)

CamStudio for Windows is free but fairly bare bones. It only records the screen so you'll need separate video editing software.

You'll also want to download the free Audacity software and the Noise Gate plugin. While Camtasia's noise reduction is okay, the noise gate plugin will detect periods where there is minimal sound (i.e. when you pause your speaking) and replace it with dead silence. This is a large improvement over just the noise reduction algorithm.

Recording Hardware

I have the following in my amateur bedroom recording studio:

I record with a Blue Yeti USB Microphone and a pop filter over it. For convenience, I bought a microphone stand that attaches to my desk. It frees me from having to awkwardly stack books to lift the microphone closer to my mouth. Don't record from your laptop's built-in microphone; it picks up the vibrations from your CPU fan and the audio quality is simply unacceptable for an online course.

If you want to do a talking-head recording with a webcam, your laptop's built-in webcam is not high-quality enough (and the low camera angle isn't flattering). The standard USB webcam that streamers use is the Logitech c920 which runs about $65. Cheaper webcams tend to be no better than your built-in webcam, more expensive webcams are more quality than you need. Although the newer Logitech c922x is nicer for $95 (they're compared in this PC World article).

You'll also need lighting and a green screen. You can spend a lot of time researching these topics, but I've found that getting 100 watt equivalent, "cool" bulbs (with blue/white-ish light) such as this 4-pack from Phillips works for me. You don't want to use "warm" yellow/orange-ish light bulbs.

A standing lamp or cheap clamp lamps with reflectors are all you need. There's no such thing as a high-quality clamp lamp: the cheap ones will do fine. Also, don't bother buying a photography light reflector: you can make one out of cardboard, aluminum foil, and tape that works just as well. Photo reflectors are nice if you don't want to shine the lamps directly on yourself but instead shine the lamp on the reflector and catch the reflected light.

Remember to shave and wash your face before recording it.

For a green screen, I bought a cheap one off Amazon that is little more than a green bed sheet. The creases need to be ironed out, but your video editor's green screen feature will work well enough even if it isn't perfect. You'll need a few more lights to prevent shadows from falling on the green screen.

Unless you're setting up a dedicated room to act as a studio, you don't necessarily need to buy foam sound-proofing tiles. My solution was to get some used duvets from the thrift store, poke some zip ties through one edge and form a loop, and then hang them from ceiling hooks. I have two duvets to form a sort of cylindrical blanket fort around my bedroom desk that I can take down when I'm done recording.

I didn't really notice the echo when before I had this setup, but I do notice a slight improvement when I compare recordings with and without them. I'd recommend at least some kind of sound proofing for everyone.

Connect your laptop to a monitor. This second screen won't be recorded for the screencast, but can hold notes or web pages you want to look at while recording.

Scripts, Speaking, and Recording

I favor doing multiple repeat takes to practice my delivery, as opposed to writing a script. Scripts take time to write, and while you might be able to do the recording in one take you could end up sounding robotic by reading off a script. Multiple takes can be tiresome, but the final take usually sounds more natural. I almost never pull footage from different takes for the single final video.

You'll come up with ideas and rewordings while doing a take, so a script would need rewrites anyway. Think of each video as a short speech you'll give: you don't need to memorize every word, but you should have all the topics you want to hit memorized.

Position the mic close to your mouth. The Yeti mic is a side address microphone, so have it facing you rather than pointed at you.

Read the rest of Blue's Yeti microphone FAQ. Do a quick test recording to make sure it sounds okay and is not muted. (More than once I've finished an entire take, then realized my laptop's mute setting was on the whole time.) Also, between your laptop's built-in microphone, the webcam's microphone, and the Yeti microphone, make sure that you have the Yeti microphone selected as the audio source before you record.

It's better to speak slowly than quickly. Udemy, YouTube, and other video sites often have video speed-up options. A normal conversation speed is best for videos. Keep in mind that many of your students won't speak English as their first language.

Do a few tongue twisters before recording to get into a presenter mindset. You don't want to be low-energy sounding. I find it helps to smile while speaking. If you aren't recording your face, open your mouth wider than usual to keep yourself from muttering. Keep a glass of water nearby, but not on the desk. Make sure it won't spill on anything if you accidentally knock it over.

I lower my screen resolution to 1280 x 720 (720p) to record. Compared to my laptop's normal 1920 x 1080 resolution, this makes the video files smaller, quicker to download, and fit on more screens (including phones). People watching on 1920 x 1080 screens can have your video open but also fit other windows on their screen simultaneously. But most important for programming screencasts, it makes text larger and easier to read. Sometimes I'll increase the text editor's font size as well.

Don't make videos composed of just a PowerPoint presentation. A screencast is much more information-rich. It's one thing to say "compile the program", and another to actually see someone navigate menus and click buttons to start the compilation process.

If I get flustered while recording, I just take a quick 10 or 20 seconds to compose myself. It's easy to find these silent pauses in the video editor and cut them.

Here's the pre-recording checklist I run through:

Close instant messaging programs that could have pop-ups while recording.
Make sure the Yeti microphone is selected as the audio source.
Have a glass of water nearby.
If I'm recording my face: shave and wash my face.
Do some tongue twister warm ups.
Make sure the mic is unmuted.
Position the mic close to your mouth.
Set screen resolution to 1280 x 720.
Do a quick test recording to make sure the audio sounds okay.
Smile!

Promotion

The worst approach to take is protectively caging up your course. A paywall is biggest wall to getting paid. If you want to make money, you need to start by giving your course out for free to build up a respectable number of students and reviews. I'm always hesitant to buy courses that only have a couple hundred students and a dozen reviews. You won't get paying students until a lot of students have vetted your course.

Announce your course on social media and Reddit with a free code to generate initial interest. Don't offer just a discount for this promotion: make it entirely free. A 90%-off discount still looks like spam. Be sure to note that this free code is for a limited time and make it sound personal like, "I've finished my new Python course and made it free this week with code THANKS_REDDIT". You'll probably get people messaging you after the period asking if they could also get a coupon. Be generous and generate a coupon for them, along with something like "If you like the course, please do rate it." Don't make it sound like you're demanding a positive review in exchange for the code.

Be generous with how many videos you make available for free previews. Of the 50 videos in my Automate course, I have the first 15 free to view (along with some other random videos later in the course). Also make these videos available on a YouTube channel, with links back to the Udemy course page. Better yet, have links using a discount code you made for YouTube viewers (this will also let you track how many students YouTube is bringing you.)

Udemy also allows you to make as many or as few of your videos available for students to download. I go ahead and make all of my videos available for download. It's a large convenience for students. And anyway it's fairly easy to google for instructions on how to download them regardless.

Don't worry about people pirating your course and watching it for free. The only way your course won't be put on torrent sites is if no one likes it to begin with. The kind of piracy you do need to worry about are other people taking your videos and selling them on Udemy or other sites. These sites will have a DMCA or infringement notice form that you can fill out. It's good practice to do searches for your course every now and then.

The promo video that people will see on your course page when they're deciding to buy it or not is incredibly important. Spend as much time as you can and follow Udemy's promo video guidelines religiously. You may want to consider spending money on background music or intro/extro video clips. I like using Pond5.com for buying sound clips.

You might not want to use Udemy's free service to generate a logo. The quality is okay but they tend to reuse them for other courses with just a color palette change. You may want to consider commissioning a logo from a graphic designer. Think of it like a getting a tattoo: keep it simple and spend more than $5 on it.

Good luck!

These are the tips I figured out about my process over a long time, and I wanted to compile them all into a blog post to give others a head start. If you want to learn more, here are some topics to google:

How to Install Django 1.10.6 and Python 3.6.0 on Dreamhost Shared Hosting

2017-03-14T12:00:00-04:00

Django is a web app framework for Python (similar to Rails for Ruby). It implements common web app features so you don't have to write that code. Dreamhost is a web host that offers cheap but reliable web servers. Their shared hosting plan is $11 a month, and provides more than enough disk space and bandwidth for personal sites.

(If you'd like to help Invent with Python, use this link to sign up for Dreamhost.)

I wanted to create a Django web app for my https://turtleappstore.com site to let others share Minecraft code projects for ComputerCraft. The process took some time to figure out, so I documented it here. Note that this tutorial is specific to Dreamhost, Django 1.10.6, and Python 3.6. The steps may vary if you use different versions or web hosts.

Setup

After you have purchased a shared hosting plan from Dreamhost, go to https://panel.dreamhost.com/ and log into your Dreamhost account. This tutorial assumes you have also registered for a domain name. From the sidebar, click Domains > Manage Domains, then click the Edit link next to the domain name you want to host the Django app. In this tutorial, I will be using example.turtleappstore.com for the domain name. Replace this with your domain name in any commands in this tutorial.

You will see the configuration details for this domain name. Make sure that the Passenger (Ruby/NodeJS/Python apps only) checkbox is checked. This will also make the web directory end with public, such as /home/username/example.turtleappstore.com/public. The page will look like this:

Aside: If you have multiple domain names with Dreamhost, I recommend creating a separate user for each one. (From the sidebar, click Users > Manage Users.) If the account or site is hacked, it will only affect that single domain instead of possibly all of your domains.

The user account that manages this domain name must have "shell access". From the sidebar, click Users > Manage Users, then click the Edit link next to the user. Next to User Type, select "Shell user". This will allow you to SSH into the shared hosting server that the web server is running on.

SSH into the Server

Using an SSH program (such as Putty on Windows, or the SSH program on Mac/Linux). Connect to your server (in my case, example.turtleappstore.com) using your shell user's username and password (not the Dreamhost username/password you used for https://panel.dreamhost.com/.)

Download and Install Python 3.6.0

Enter the following commands (not the [server]$ part, that's the shell prompt):

[server]$ cd ~
[server]$ cd example.turtleappstore.com/
[server]$ mkdir tmp
[server]$ cd tmp
[server]$ wget https://www.python.org/ftp/python/3.6.0/Python-3.6.0.tgz
[server]$ tar zxvf Python-3.6.0.tgz
[server]$ cd Python-3.6.0
[server]$ ./configure --prefix=$HOME/opt/python-3.6.0
[server]$ make
[server]$ make install

Some of these commands will take a few minutes to run and output a lot of text. You shouldn't encounter any error messages, but if you do you'll need to figure out what is causing them. Try googling the error message to see if others have encountered it and described the solution.

Next, add export PATH=$HOME/opt/python-3.6.0/bin:$PATH to the bottom of your ~/.bashrc and ~/.bash_profile files so that when your web server runs Python, it runs the Python 3.6.0 program you just installed and not Dreamhost's default Python (which is 2.7, as of 2017/03/14). Use a text editor such as vi or vim to do this.

Then run the following to set the system path in your current SSH session (or logout and log back in):

[server]$ source ~/.bash_profile

Confirm that python3 and pip3 will use the Python you just installed by running the following and checking their output:

[server]$ which python3
/home/your_username/opt/python-3.6.0/bin/python3
[server]$ which pip3
/home/your_username/opt/python-3.6.0/bin/pip3

With Python installed, you can now delete the temporary install files by running the following:

[server]]$ rm ~/example.turtleappstore.com/tmp/* -rf

Download and Install Virtualenv

Virtualenv is a tool to keep installed modules separate for separate projects. This way, if you are working on one Python project that requires Django 1.10.6 and another that requires Django 1.3, you won't be constantly installing and uninstalling Django modules as you work on them. Virtual environments are a good idea to have.

Run the following to install the virtualenv Python module:

[server]$ pip3 install virtualenv

Confirm that virtualenv was installed by running the following and checking the output:

[server]$ which virtualenv
/home/[username]/opt/python-3.6.0/bin/virtualenv

According to the venv documentation, in Python 3.6 you don't use virtualenv or pyenv but instead python3 -m venv to prevent confusion as to which Python interpreter the virtual environment will be based on.

Next, create a virtual environment for your project. I'll call mine tas_venv:

[server]$ python3 -m venv ~/tas_venv

From now on, before you install/unintall Python modules or run any Django scripts such as manage.py, you will need to make sure the virtual environment for your web app project is activated. Run the following:

[server]$ source ~/tas_venv/bin/activate
(tas_venv) [server]$

You'll see the (tas_venv) prompt come up. To exit the virtual environment, just run deactivate.

Download and Install Django

With the tas_venv (or whatever you named it) virtual environment set up, install Django by running this:

(tas_venv) [server]$ pip3 install django==1.10.6

You can verify Django installed properly from the Python interactive shell:

(tas_venv) [server]$ python3
Python 3.6.0 (default, Mar 14 2017, 18:13:54)
[GCC 4.6.3] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import django
>>> django.VERSION
(1, 10, 6, 'final', 0)

Create the Django project for your site. I'm going to name mine tasproject:

(tas_venv) [server]$ cd ~/example.turtleappstore.com/
(tas_venv) [server]$ python3 ~/tas_venv/bin/django-admin.py startproject tasproject

Setup Passenger & Django

To finish setting up your site, create a file passenger_wsgi.py in the root of your website directory using a text editor. Add the following to it:

import sys, os
cwd = os.getcwd()
sys.path.append(cwd)
sys.path.append(cwd + '/tasproject')

INTERP = os.path.expanduser("~/tas_venv/bin/python3")

if sys.executable != INTERP: os.execl(INTERP, INTERP, *sys.argv)

sys.path.insert(0,'$HOME/tas_venv/bin')
sys.path.insert(0,'$HOME/tas_venv/lib/python3.6/site-packages/django')
sys.path.insert(0,'$HOME/tas_venv/lib/python3.6/site-packages')

os.environ['DJANGO_SETTINGS_MODULE'] = "tasproject.settings"
from django.core.wsgi import get_wsgi_application
application = get_wsgi_application()

(tas_venv is the name of the virtual environment, while tasproject is the name of the Django project.)

Also add the following line to the ~/example.turtleappstore.com/tasproject/tasproject/settings.py file:

STATIC_ROOT = os.path.dirname(BASE_DIR) + '/static/'

Passenger causes Django to handle web server requests. However, I've been having problems getting static files to work correctly on Dreamhost, so I use the public folder to server all static files by placing a static subfolder under the public folder. I'll update this blog post if I figure out a way to get static files to work properly through Django. Note that Dreamhost will check the public folder first for URL requests, and then check Django's urls.py file next.

Finally, create a restart.txt file to cause Passenger to reload your passenger_wsgi.py script:

[server]$ touch ~/example.turtleappstore.com/tmp/restart.txt

At this point, you should be able to open example.turtleappstore.com in a web browser and see Django's default "It worked!" page. Whenever you make a change, you need to re-touch the restart.txt file for Passenger to pick up the changes. Note that Passenger will handle all requests made to the example.turtleappstore.com. You can now start creating apps and working on your Django project as you normally would.

"Automate the Boring Stuff with Python" online course now available!

2015-09-21T12:00:00-04:00

For the last few months I've been putting together an online course that follows my latest (and free) book, "Automate the Boring Stuff with Python".

The first 15 videos are also freely available on YouTube.

APIs, not apps: What the future will be like when everyone can code

2015-09-15T12:00:00-04:00

I've written an article for OpenSource.com called APIs, not apps: What the future will be like when everyone can code, where I write about a coming future where programming ability is in the hands of everyone.

Excerpt:

Despite this hype, I do think that coding will become a more widespread and routine skill in the years to come. Programmable technology will continue to pervade more parts of our life, computers will continue to become more accessible to a wider population, and the world will continue to become more complex. Understanding coding (and debugging) will naturally go with it.

...

These are areas where non-programmers can significantly boost their productivity by learning to code. This is different from everyone becoming a software engineer. When I say learn to code, I don't mean develop software professionally. Almost every adult has a driver's license, but only a minority are cab drivers or NASCAR racers.

...

Universal coding literacy doesn't increase the supply of web services so much as increase the sophistication in how web services are used. Programming—by which I mean being able to direct a computer to access data, organize it, and then make decisions based on it— will open up not only a popular ability to make more of online services, but also to demand more.

3rd Edition of "Invent Your Own Computer Games with Python" Released

2015-03-10T12:00:00-04:00

Download the PDF

The 3rd edition of "Invent Your Own Computer Games with Python" is now available. The 3rd edition has been streamlined to provide the same content but in 50 fewer pages, making it an easier read. If you've already read the 2nd edition, there's no need to read the 3rd (unless you want to sharpen your Python skills). But for new readers, Invent with Python should be even easier to pick up.

Buy the 3rd Edition on Amazon

Read the 3rd Edition online for free

Read the 2nd Edition

The 3rd edition is also being used for the translations. Currently the Spanish translation is online (though incomplete). The German and Dutch versions are nearing completion as well.

Translate Your Python 3 Program with the gettext Module

2014-12-20T12:00:00-05:00

You've written a Python 3 program and want to make it available in other languages. You could duplicate the entire code-base, then go painstakingly through each .py file and replace any text strings you find. But this would mean you have two separate copies of your code, which doubles your workload every time you need to make a change or fix a bug. And if you want your program in other languages, it gets even worse.

Fortunately, Python provides a solution with the gettext module.

A Hack Solution

You could hack together your own solution. For example, you could replace every string in your program with a function call (with the function name being something simple, like _())) which will return the string translated into the correct language. For example, if your program was:

print('Hello world!')

...you could change this to:

print(_('Hello world!'))

...and the _() function could return the translation for 'Hello world!' based on what language setting the program had. For example, if the language setting was stored in a global variable named LANGUAGE, the _() function could look like this:

def _(s):
    spanishStrings = {'Hello world!': 'Hola Mundo!'}
    frenchStrings = {'Hello world!': 'Bonjour le monde!'}
    germanStrings = {'Hello world!': 'Hallo Welt!'}

    if LANGUAGE == 'English':
        return s
    if LANGUAGE == 'Spanish':
        return spanishStrings[s]
    if LANGUAGE == 'French':
        return frenchStrings[s]
    if LANGUAGE == 'German':
        return germanStrings[s]

This would work, but you'd be reinventing the wheel. This is pretty much what Python's gettext module does. gettext is a set of tools and file formats created in the early 1990s to standardize software internationalization (also called I18N). gettext was designed as a system for all programming languages, but we'll focus on Python in this article.

The Example Program

Say you have a simple "Guess the Number" game written in Python 3 that you want to translate. The source code to this program is here. There are four steps to internationalizing this program:

Modify the .py file's source code so that the strings are passed to a function named _().
Use the pygettext.py script that comes installed with Python to create a "pot" file from the source code.
Use the free cross-platform Poedit software to create the .po and .mo files from the pot file.
Modify your .py file's source code again to import the gettext module and set up the language setting.

Step 1: Add the _() Function

First, go through all of the strings in your program that will need to be translated and replace them with _() calls. The gettext system for Python uses _() as the generic name for getting the translated string since it is a short name.

Note that using string formatting instead of string concatenation will make your program easier to translate. For example, using string concatenation your program would have to look like this:

print('Good job, ' + myName + '! You guessed my number in ' + guessesTaken + ' guesses!')

print(_('Good job, ') + myName + _('! You guessed my number in ') + guessesTaken + _(' guesses!'))

This results in three separate strings that need to be translated, as opposed to the single string needed in the string formatting approach:

print('Good job, %s! You guessed my number in %s guesses!' % (myName, guessesTaken))

print(_('Good job, %s! You guessed my number in %s guesses!') % (myName, guessesTaken))

When you've gone through the "Guess the Number" source code, it will look like this. You won't be able to run this program since the _() function is undefined. This change is just so that the pygettext.py script can find all the strings that need to be translated.

Step 2: Extract the Strings Using pygettext.py

In the Tools/i18n of your Python installation (C:\Python34\Tools\i18n on Windows) is the pygettext.py script. While the normal gettext unix command parse C/C++ source code for translatable strings and the xgettext unix command can parse other languages, pygettext.py knows how to parse Python source code. It will find all of these strings and produce a "pot" file.

On Windows, I've run this script like so:

C:\>py -3.4 C:\Python34\Tools\i18n\pygettext.py -d guess guess.py

This creates a pot file named guess.pot. This is just a normal plaintext file that lists all the translated strings it found in the source code by search for _() calls. You can view the guess.pot file here.

Step 3: Translate the Strings using Poedit

You could fill in the translation using a text editor, but the free Poedit software makes it easier. Download it from http://poedit.net. Select File > New from POT/PO file... and select your guess.po file.

Poedit will ask what language you want to translate the strings to. For this example, we'll use Spanish:

Then fill in the translations. (I'm using http://translate.google.com, so it probably sounds a bit odd to actual Spanish-speakers.)

And now save the file in it's gettext-formatted folder. Saving will create the .po file (a human-readable text file identical to the original .pot file, except with the Spanish translations) and a .mo file (a machine-readable version which the gettext module will read. These files have to be saved in a certain folder structure for gettext to be able to find them. They look like this (say I have "es" Spanish files and "de" German files):

./guess.py
./guess.pot
./locale/es/LC_MESSAGES/guess.mo
./locale/es/LC_MESSAGES/guess.po
./locale/de/LC_MESSAGES/guess.mo
./locale/de/LC_MESSAGES/guess.po

These two-character language names like "es" for Spanish and "de" for German are called ISO 639-1 codes and are standard abbreviations for languages. You don't have to use them, but it makes sense to follow that naming standard.

Step 4: Add gettext Code to Your Program

Now that you have the .mo file that contains the translations, modify your Python script to use it. Add the following to your program:

import gettext
es = gettext.translation('guess', localedir='locale', languages=['es'])
es.install()

The first argument 'guess' is the "domain", which basically means the "guess" part of the guess.mo filename. The localedir is the directory location of the locale folder you created. This can be either a relative or absolute path. The 'es' string describes the folder under the locale folder. The LC_MESSAGES folder is a standard name

The install() method will cause all the _() calls to return the Spanish translated string. If you want to go back to the original English, just assign a lambda function value to _ that returns the string it was passed:

import gettext, os
FOLDER_OF_THIS_FILE = os.path.dirname(os.path.abspath(__file__))
esLang = gettext.translation('guess', localedir=os.path.join(FOLDER_OF_THIS_FILE, 'locale'), languages=['es'])
esLang.install()  # All _() calls return Spanish strings after this point.
print(_('Hello! What is your name?'))  # prints Spanish

You can view the translation-ready source code for the "Guess the Number". If you want to run this program, download and unzip this zip file with it's locale folders and .mo file set up.

Programming a Bot to Play the "Sushi Go Round" Flash Game

2014-12-17T12:00:00-05:00

Update 2015/01/08: If you attended my NCSS class on making a bot for this game, you can download the sushi.zip file which has all the code in bot5.py.

This tutorial teaches how to write a bot that can automatically play the Flash game Sushi Go Round. The concepts in this tutorial can be applied to make bots that play other games as well. It's inspired by the How to Build a Python Bot That Can Play Web Games by Chris Kiehl. The primary improvement of this tutorial is it uses the cross-platform PyAutoGUI module to control the mouse and take screenshots. It is documented on its ReadTheDocs page.

Sushi Go Round is a resource management game similar to "Dine N Dash". You fill customer orders for different types of sushi and place them on the conveyor belt. Incoming customers may take other customer's sushi orders, forcing you to remake orders. Customers who wait too long to get orders end up leaving, costing you reputation. Angry customers can be placated with saki, but this bot does not make use of that feature. Ingredients will have to be ordered as they get low.

I've refined this bot so that it can successfully play all the way through the game, ending up with a score of about 38,000. The top scores are a little over 100,000, so there is still room for improvement with this bot. You can watch a YouTube video of the bot playing.

The source code and images for the bot can be downloaded here or viewed on GitHub.

Step 1 - Install PyAutoGUI and Download Images

First, install PyAutoGUI by downloading it from PyPI or installing it through the pip program that comes with Python 3. If you've installed PyAutoGUI before, use the -U option to update it to the latest version. This tutorial uses Python 3, though PyAutoGUI and the bot code work with either Python 2 or 3.

You can check if PyAutoGUI has been installed correctly by running import pyautogui in the interactive shell. Full documentation for PyAutoGUI is available at http://pyautogui.readthedocs.org.

PyAutoGUI provides basic image recognition by finding the screen coordinates of a provided image. To save yourself time of taking screenshots and making these images yourself, download them from the zip file here. All of the images should be stored in an /images folder:

Step 2 - Basic Setup

Create a sushigoround.py file and enter the following code:

#! python3
"""Sushi Go Round Bot
Al Sweigart [email protected] @AlSweigart

A bot program to automatically play the Sushi Go Round flash game at http://miniclip.com/games/sushi-go-round/en/
"""

import pyautogui, time, os, logging, sys, random, copy

logging.basicConfig(level=logging.DEBUG, format='%(asctime)s.%(msecs)03d: %(message)s', datefmt='%H:%M:%S')
#logging.disable(logging.DEBUG) # uncomment to block debug log messages

This generic code sets up a shebang line, some comments to describe the program, imports for several modules, and setting up logging so that the logging.debug() function will output debug messages. (I explain why logging is preferable to print() calls in this blog post.

Step 3 - Constants Setup

Next, there are several variable constants set up for this program. I use constants as a way to detect typos; mistyping a string value as 'califrnia_roll' will cause bugs but Python won't directly point out the typo. Mistyping a variable name as CALIFRNIA_ROLL will cause Python to raise a NameError exception, letting you quickly fix it.

First, set up constants for each type of order in the game, as well as a tuple of all the orders:

# Food order constants (don't change these: the image filenames depend on these specific values)
ONIGIRI = 'onigiri'
GUNKAN_MAKI = 'gunkan_maki'
CALIFORNIA_ROLL = 'california_roll'
SALMON_ROLL = 'salmon_roll'
SHRIMP_SUSHI = 'shrimp_sushi'
UNAGI_ROLL = 'unagi_roll'
DRAGON_ROLL = 'dragon_roll'
COMBO = 'combo'
ALL_ORDER_TYPES = (ONIGIRI, GUNKAN_MAKI, CALIFORNIA_ROLL, SALMON_ROLL, SHRIMP_SUSHI, UNAGI_ROLL, DRAGON_ROLL, COMBO)

Next, set up constants for each of the ingredients and the recipes for each order. (This tutorial saves you from having to look up the recipe information in the game yourself.)

# Ingredient constants (don't change these: the image filenames depend on these specific values)
SHRIMP = 'shrimp'
RICE = 'rice'
NORI = 'nori'
ROE = 'roe'
SALMON = 'salmon'
UNAGI = 'unagi'
RECIPE = {ONIGIRI:         {RICE: 2, NORI: 1},
          CALIFORNIA_ROLL: {RICE: 1, NORI: 1, ROE: 1},
          GUNKAN_MAKI:     {RICE: 1, NORI: 1, ROE: 2},
          SALMON_ROLL:     {RICE: 1, NORI: 1, SALMON: 2},
          SHRIMP_SUSHI:    {RICE: 1, NORI: 1, SHRIMP: 2},
          UNAGI_ROLL:      {RICE: 1, NORI: 1, UNAGI: 2},
          DRAGON_ROLL:     {RICE: 2, NORI: 1, ROE: 1, UNAGI: 2},
          COMBO:           {RICE: 2, NORI: 1, ROE: 1, SALMON: 1, UNAGI: 1, SHRIMP: 1},}

Next are several constants and global variables used in the program. Although using global variables is generally a bad idea for making maintainable programs, this Python script is just a one off and I didn't want to make it complicated for newer programmers who don't yet know object-oriented programming concepts. The variables are described in the comments:

LEVEL_WIN_MESSAGE = 'win' # checkForGameOver() returns this value if the level has been won

# Settings
MIN_INGREDIENTS = 4 # if an ingredient gets below this value, order more
PLATE_CLEARING_FREQ = 8 # plates are cleared every this number of seconds, roughly
NORMAL_RESTOCK_TIME = 7 # the number of seconds it takes to restock inventory after ordering it (at normal speed, not express)
TIME_TO_REMAKE = 30 # if an order goes unfilled for this number of seconds, remake it

# Global variables
LEVEL = 1 # current level being played
INVENTORY = {SHRIMP: 5, RICE: 10,
             NORI: 10,  ROE: 10,
             SALMON: 5, UNAGI: 5}
GAME_REGION = () # (left, top, width, height) values coordinates of the game window
ORDERING_COMPLETE = {SHRIMP: None, RICE: None, NORI: None, ROE: None, SALMON: None, UNAGI: None} # unix timestamp when an ordered ingredient will have arrived
ROLLING_COMPLETE = 0 # unix timestamp of when the rolling of the mat will have completed
LAST_PLATE_CLEARING = 0 # unix timestamp of the last time the plates were cleared
LAST_GAME_OVER_CHECK = 0 # unix timestamp when we last checked for the Game Over or You Win messages

Note: a "unix timestamp" is the number of seconds since midnight, January 1, 1970. It is returned by the time.time() function. For example, if time.time() is called at 10:36:54.392 PM on December 16, 2014, it will return the value 1418798214.392. Ten seconds later it will return the value 1418798224.392. Subtracting these values is how the bot can measure how much time has passed.

And finally set up some global variables which will store coordinates for various things in the game window. The GAME_REGION variable stores the position of the Sushi Go Round game itself. Once that value has been acquired, the setupCoordinates() function (described later) will populate the values in these variables:

# various coordinates of objects in the game
GAME_REGION = () # (left, top, width, height) values coordinates of the entire game window
INGRED_COORDS = None
PHONE_COORDS = None
TOPPING_COORDS = None
ORDER_BUTTON_COORDS = None
RICE1_COORDS = None
RICE2_COORDS = None
NORMAL_DELIVERY_BUTTON_COORDS = None
MAT_COORDS = None

Step 4 - The main() Function

The main() ties together the code that runs from the very start of the bot program. It assumes that the Sushi Go Round game is visible on the screen and at the opening start screen (which has the flashing "PLAY" button).

Because PyAutoGUI takes control of the mouse, it can be hard to get the program's terminal window back in focus to shut it down. PyAutoGUI has a fail-safe feature; if you move the mouse cursor to the top-left corner of the screen PyAutoGUI will raise an exception and terminate the program.

def main():
    """Runs the entire program. The Sushi Go Round game must be visible on the screen and the PLAY button visible."""
    logging.debug('Program Started. Press Ctrl-C to abort at any time.')
    logging.debug('To interrupt mouse movement, move mouse to upper left corner.')
    getGameRegion()
    navigateStartGameMenu()
    setupCoordinates()
    startServing()

Step 5 - Image Recognition and Finding the Game Screen

Computer vision and optical character recognition (OCR) are major topics of computer science. The good thing about Sushi Go Round is that you don't need to know any of that because the game uses static 2D sprites. A california roll in the game will always look the same down to the pixel. So we can use PyAutoGUI's pixel-recognition functions to "see" where on the screen different objects are.

The pyautogui.locateOnScreen() function takes a string filename argument and returns a (left, top, width, height) tuple of integer coordinates for where the image is found on the screen. (The "left" value is the X-coordinate of the left edge, the "top" value is the Y-coordinate of the top edge. With the XY coordinates of the top-left corner and the width and height, you can completely describe the region.)

If the image isn't found on the screen, the function returns None. An optional region keyword argument can specify a smaller region of the screen to search (a smaller region means faster detection). Without a region specified, the entire screen is searched.

The location of the game window itself will be stored later in the GAME_REGION variable, which holds a (left, top, width, height) tuple of integers. (The (left, top, width, height) tuples are used throughout PyAutoGUI.) These values are visualized in the following graphic:

To find the game window, we search for the top-right corner image, which is stored in top_right_corner.png. (These image files are included in the zip file download.) Once this image is located on the screen, the GAME_REGION variable can be populated.

def imPath(filename):
    """A shortcut for joining the 'images/'' file path, since it is used so often. Returns the filename with 'images/' prepended."""
    return os.path.join('images', filename)


def getGameRegion():
    """Obtains the region that the Sushi Go Round game is on the screen and assigns it to GAME_REGION. The game must be at the start screen (where the PLAY button is visible)."""
    global GAME_REGION

    # identify the top-left corner
    logging.debug('Finding game region...')
    region = pyautogui.locateOnScreen(imPath('top_right_corner.png'))
    if region is None:
        raise Exception('Could not find game on screen. Is the game visible?')

    # calculate the region of the entire game
    topRightX = region[0] + region[2] # left + width
    topRightY = region[1] # top
    GAME_REGION = (topRightX - 640, topRightY, 640, 480) # the game screen is always 640 x 480
    logging.debug('Game region found: %s' % (GAME_REGION,))

Note that running PyAutoGUI's image recongition takes a relatively long time to execute (several hundred milliseconds). This can be mitigated by searching a smaller region instead of the entire screen. And since some objects will always appear in the same place in the game window, you can rely on using static integer coordinates instead of image recognition to find them.

Step 6 - Dealing with Coordinates

Many of the buttons in the game's user interface will always be in the same location. The coordinates for these buttons can be pre-programmed ahead of time. You could take a screenshot, paste the image into a graphics program such as Photoshop or MS Paint, and find all of the XY coordinates yourself. But this tutorial has done this step for you. The other coordinate global variables are populated in the setupCoordinates() function. Note that they are all relative to where the game window (whose coordinates are in GAME_REGION) is.

For example, the coordinates for the Salmon ordering button are set to (GAME_REGION[0] + 496, GAME_REGION[1] + 329). This is visualized in the following graphic:

def setupCoordinates():
    """Sets several of the coordinate-related global variables, after acquiring the value for GAME_REGION."""
    global INGRED_COORDS, PHONE_COORDS, TOPPING_COORDS, ORDER_BUTTON_COORDS, RICE1_COORDS, RICE2_COORDS, NORMAL_DELIVERY_BUTTON_COORDS, MAT_COORDS, LEVEL
    INGRED_COORDS = {SHRIMP: (GAME_REGION[0] + 40, GAME_REGION[1] + 335),
                     RICE:   (GAME_REGION[0] + 95, GAME_REGION[1] + 335),
                     NORI:   (GAME_REGION[0] + 40, GAME_REGION[1] + 385),
                     ROE:    (GAME_REGION[0] + 95, GAME_REGION[1] + 385),
                     SALMON: (GAME_REGION[0] + 40, GAME_REGION[1] + 425),
                     UNAGI:  (GAME_REGION[0] + 95, GAME_REGION[1] + 425),}
    PHONE_COORDS = (GAME_REGION[0] + 560, GAME_REGION[1] + 360)
    TOPPING_COORDS = (GAME_REGION[0] + 513, GAME_REGION[1] + 269)
    ORDER_BUTTON_COORDS = {SHRIMP: (GAME_REGION[0] + 496, GAME_REGION[1] + 222),
                           UNAGI:  (GAME_REGION[0] + 578, GAME_REGION[1] + 222),
                           NORI:   (GAME_REGION[0] + 496, GAME_REGION[1] + 281),
                           ROE:    (GAME_REGION[0] + 578, GAME_REGION[1] + 281),
                           SALMON: (GAME_REGION[0] + 496, GAME_REGION[1] + 329),}
    RICE1_COORDS = (GAME_REGION[0] + 543, GAME_REGION[1] + 294)
    RICE2_COORDS = (GAME_REGION[0] + 545, GAME_REGION[1] + 269)

    NORMAL_DELIVERY_BUTTON_COORDS = (GAME_REGION[0] + 495, GAME_REGION[1] + 293)

    MAT_COORDS = (GAME_REGION[0] + 190, GAME_REGION[1] + 375)

    LEVEL = 1

This tutorial does the tedious coordinate-finding work for you, but if you ever need to do it yourself you can use the pyautogui.displayMousePosition() function to display the XY coordinates of the mouse cursor. The coordinates update as you move the mouse, so you can move the mouse to the desired location on the screen, then view its current coordinates. The displayMousePosition() function also shows that pixel's RGB color value.

You can also pass X and Y offsets to the function to set the (0, 0) origin somewhere besides the top-left corner of the screen. When you are done, press Ctrl-C to return from the function.

Step 7 - Controlling the Mouse

PyAutogui has a pyautogui.click() function that can be passed a (x, y) tuple argument of the coordinates on the screen to click on. Often you can use the return value of pyautogui.locateCenterOnScreen() for this argument. The click is done immediately, but the optional duration keyword argument will specify the number of seconds PyAutoGUI spends moving to the (x, y) coordinate. A small delay makes it easier to visually follow along with the bot's clicking.

Since the SKIP button in the game is flashing, the pyautogui.locateCenterOnScreen(imPath('skip_button.png'), region=GAME_REGION) call might not be able to find it if it is flashing in the other color than skip_button.png has. This is why there is a while loop that keeps searching until it finds it. Remember, locateCenterOnScreen() will return None if it can't find the image on the screen.

def navigateStartGameMenu():
    """Performs the clicks to navigate form the start screen (where the PLAY button is visible) to the beginning of the first level."""
    # Click on everything needed to get past the menus at the start of the game.

    # click on Play
    logging.debug('Looking for Play button...')
    while True: # loop because it could be the blue or pink Play button displayed at the moment.
        pos = pyautogui.locateCenterOnScreen(imPath('play_button.png'), region=GAME_REGION)
        if pos is not None:
            break
    pyautogui.click(pos, duration=0.25)
    logging.debug('Clicked on Play button.')

    # click on Continue
    pos = pyautogui.locateCenterOnScreen(imPath('continue_button.png'), region=GAME_REGION)
    pyautogui.click(pos, duration=0.25)
    logging.debug('Clicked on Continue button.')

    # click on Skip
    logging.debug('Looking for Skip button...')
    while True: # loop because it could be the yellow or red Skip button displayed at the moment.
        pos = pyautogui.locateCenterOnScreen(imPath('skip_button.png'), region=GAME_REGION)
        if pos is not None:
            break
    pyautogui.click(pos, duration=0.25)
    logging.debug('Clicked on Skip button.')

    # click on Continue
    pos = pyautogui.locateCenterOnScreen(imPath('continue_button.png'), region=GAME_REGION)
    pyautogui.click(pos, duration=0.25)
    logging.debug('Clicked on Continue button.')

Once the buttons at the start of the game have been navigated past, the main part of the bot code can begin.

Step 8 - The startServing() Function

The startServing() function handles all of the main game play. This includes:

Seeing which orders are being requested from customers.
Creating dishes to fill orders.
Ordering more ingredients when running low on them.
Checking if customers haven't received their orders in a long time and remaking those orders.
Clearing finished plates.
Checking if ordered ingredients have arrived.
Checking if the game has been lost or if the level has been won.

Much of this functionality is passed on to other functions, which are explained later. The first part of startServing() sets up all the variables for a new game:

def startServing():
    """The main game playing function. This function handles all aspects of game play, including identifying orders, making orders, buying ingredients and other features."""
    global LAST_GAME_OVER_CHECK, INVENTORY, ORDERING_COMPLETE, LEVEL

    # Reset all game state variables.
    oldOrders = {}
    backOrders = {}
    remakeOrders = {}
    remakeTimes = {}
    LAST_GAME_OVER_CHECK = time.time()
    ORDERING_COMPLETE = {SHRIMP: None, RICE: None, NORI: None,
                         ROE: None, SALMON: None, UNAGI: None}

The next part scans the region where customers orders are displayed:

This is handled by the getOrders() function. Since you'll be repeatedly scanning for the orders but don't want to remake orders each time you scan them, you need to find out which new orders have appeared since the last scan, and which orders have disappeared since the last scan (either because the customer is eating or has left). This is handled by the getOrdersDifference().

The keys in these "orders dictionaries" will be the (left, top, width, height) tuple of where the order image was identified. This is just to keep the customers distinct. The values will be the strings in one of the ingredient constants like CALIFORNIA_ROLL or ONIGIRI. The remakeTimes dictionary has similar keys, but it's values are unix timestamps (returned from time.time()) for when the dish should be remade if it is still being requested by the customer.

    while True:
        # Check for orders, see which are new and which are gone since last time.
        currentOrders = getOrders()
        added, removed = getOrdersDifference(currentOrders, oldOrders)
        if added != {}:
            logging.debug('New orders: %s' % (list(added.values())))
            for k in added:
                remakeTimes[k] = time.time() + TIME_TO_REMAKE
        if removed != {}:
            logging.debug('Removed orders: %s' % (list(removed.values())))
            for k in removed:
                del remakeTimes[k]

The next part goes through the remakeTimes dictionary and checks if any of those timestamps are before the current time (as returned by time.time()). In that case, add this order to the remakeOrders dictionary (which is similar but separate to the added orders dictionary of new orders.)

        # Check if the remake times have past, and add those to the remakeOrders dictionary.
        for k, remakeTime in copy.copy(remakeTimes).items():
            if time.time() > remakeTime:
                remakeTimes[k] = time.time() + TIME_TO_REMAKE # reset remake time
                remakeOrders[k] = currentOrders[k]
                logging.debug('%s added to remake orders.' % (currentOrders[k]))

Next, the program loops through all the newly requested orders in the added dictionary and attempts to make them. The makeOrder() function (described later) will return None if the order was successfully made. Otherwise, it will return a string of the ingredient it doesn't have enough of. In that case, orderIngredient() (described later) is called and the order is placed on the backOrders dictionary.

        # Attempt to make the order.
        for pos, order in added.items():
            result = makeOrder(order)
            if result is not None:
                orderIngredient(result)
                backOrders[pos] = order
                logging.debug('Ingredients for %s not available. Putting on back order.' % (order))

When a customer picks up their meal, they'll spend a few seconds eating and then leave behind a dirty dish. Click this dirty dish so that a new customer will take that seat. Instead of using image recognition (which is slow), the bot can just occassionally click on all six plates. There's no penalty to clicking on the plate when the customer is eating or if there is no plate at that seat.

Since this doesn't need to be done frequently, the if random.randint(1, 10) == 1 or time.time() - PLATE_CLEARING_FREQ > LAST_PLATE_CLEARING: statement will only do this roughly once every 10 iterations, or if more than 6 seconds (the value in PLATE_CLEARING_FREQ) has passed since the last plate clearing (according to the timestamp in LAST_PLATE_CLEARING).

The actual clicking is done by the clickOnPlates() function, described later.

        # Clear any finished plates.
        if random.randint(1, 10) == 1 or time.time() - PLATE_CLEARING_FREQ > LAST_PLATE_CLEARING:
            clickOnPlates()

It's easy to keep track of ingredient quanties as you make dishes. Each level starts with a set quantity of ingredients, encoded in the INVENTORY = {SHRIMP: 5, RICE: 10, NORI: 10, ROE: 10, SALMON: 5, UNAGI: 5} lines. You can subtract values in the INVENTORY dictionary as you use ingredients.

When you order ingredients they don't arrive immediately. If you used image recognition for the numbers in the lower left corner of the game window it would require grabbing tons of screenshots and slow down the bot. Instead, since orders take less than 7 seconds to arrive (which is why the NORMAL_RESTOCK_TIME is set to 7), the ORDERING_COMPLETE can store unix timestamps for 7 seconds in the future when INVENTORY can be updated.

The values in ORDERING_COMPLETE are None if they are not currently being ordered and delivered.

The next part of code checks if the current time (as returned by time.time()) has passed. If so, the INVENTORY dictionary's values are updated.

        # Check if ingredient orders have arrived.
        updateInventory()

        # Go through and see if any back orders can be filled.
        for pos, order in copy.copy(backOrders).items():
            result = makeOrder(order)
            if result is None:
                del backOrders[pos] # remove from back orders
                logging.debug('Filled back order for %s.' % (order))

The remakeOrders dictionary contains orders that (for whatever reason) didn't make it to the customer. This code is similar to the previous dish-making code:

        # Go through and see if any remake orders can be filled.
        for pos, order in copy.copy(remakeOrders).items():
            if pos not in currentOrders:
                del remakeOrders[pos]
                logging.debug('Canceled remake order for %s.' % (order))
                continue
            result = makeOrder(order)
            if result is None:
                del remakeOrders[pos] # remove from remake orders
                logging.debug('Filled remake order for %s.' % (order))

The next part checks the INVENTORY dictionary to see if there is less than 4 (the value stored in the MIN_INGREDIENTS constant) of any ingredient. If so, more is ordered by calling the orderIngredient() function (described later). This isn't something that needs to be checkeded frequently, so it is enclosed in an if statement that runs 1 in 5 times:

        if random.randint(1, 5) == 1:
            # order any ingredients that are below the minimum amount
            for ingredient, amount in INVENTORY.items():
                if amount < MIN_INGREDIENTS:
                    orderIngredient(ingredient)

The next part checks for the "You Win" or "You Fail" message. Since this check doesn't need to happen frequently at all, the if time.time() - 12 > LAST_GAME_OVER_CHECK: statement only runs it once every 12 seconds. LAST_GAME_OVER_CHECK is updated with the current time from time.time() every time the check is performed. The checkForGameOver() function (described later) terminates the program if the player has lost, or returns the string in the LEVEL_WIN_MESSAGE constant if the level has been beaten.

If the level has been beaten, the code resets many of the variables:

        # check for the "You Win" or "You Fail" messages
        if time.time() - 12 > LAST_GAME_OVER_CHECK:
            result = checkForGameOver()
            if result == LEVEL_WIN_MESSAGE:
                # player has completed the level

                # Reset inventory and orders.
                INVENTORY = {SHRIMP: 5, RICE: 10,
                             NORI: 10, ROE: 10,
                             SALMON: 5, UNAGI: 5}
                ORDERING_COMPLETE = {SHRIMP: None, RICE: None,
                                     NORI: None, ROE: None,
                                     SALMON: None, UNAGI: None}
                backOrders = {}
                remakeOrders = {}
                currentOrders = {}
                oldOrders = {}

Also, the bot will let the user view the end-level stats for 5 seconds before clicking Continue to move on to the next level.

                logging.debug('Level %s complete.' % (LEVEL))
                LEVEL += 1
                time.sleep(5) # give another 5 seconds to tally score

                # Click buttons to continue to next level.
                pos = pyautogui.locateCenterOnScreen(imPath('continue_button.png'), region=GAME_REGION)
                pyautogui.click(pos, duration=0.25)
                logging.debug('Clicked on Continue button.')
                pos = pyautogui.locateCenterOnScreen(imPath('continue_button.png'), region=GAME_REGION)

For every level except for the last, there will be a second Continue button to click on. On the last level, the bot doesn't do this so the user can view the game ending.

                if LEVEL <= 7: # click the second continue if the game isn't finished.
                    pyautogui.click(pos, duration=0.25)
                    logging.debug('Clicked on Continue button.')

        oldOrders = currentOrders

Step 9 - Clearing the Plates

The clickOnPlates() function blindly clicks on all six places where there could be a dirty plate to clean up. This works because there is no penalty for clicking when there isn't a dirty plate, freeing the bot from having to use performance-costly image recognition to first identify the dirty plate.

The LAST_PLATE_CLEARING global variable contains the timestamp of the last time the plates were cleared. This is used to determine if a long time has passed since the plates have been cleared.

def clickOnPlates():
    """Clicks the mouse on the six places where finished plates will be flashing. This function does not check for flashing plates, but simply clicks on all six places.

    Sets LAST_PLATE_CLEARING to the current time."""
    global LAST_PLATE_CLEARING

    # just blindly click on all the places where a plate should be
    for i in range(6):
        pyautogui.click(83 + GAME_REGION[0] + (i * 101), GAME_REGION[1] + 203)
    LAST_PLATE_CLEARING = time.time()

Step 10 - Getting the Orders from Customers

Customer orders appear as dish images in word bubbles above their heads. PyAutoGUI's image recognition can be used to scan this region of the game screen and match them to the images in california_roll_order.png, gunkan_maki_order.png, onigiri_order.png, and so on:

The getOrders() function finds all the current orders being requested. Figuring out which of these orders have been seen before (and possible already fulfilled) is done by the getOrdersDifference() function, explained in the next section.

def getOrders():
    """Scans the screen for orders being made. Returns a dictionary with a (left, top, width, height) tuple of integers for keys and the order constant for a value.

    The order constants are ONIGIRI, GUNKAN_MAKI, CALIFORNIA_ROLL, SALMON_ROLL, SHRIMP_SUSHI, UNAGI_ROLL, DRAGON_ROLL, COMBO."""
    orders = {}
    for orderType in (ALL_ORDER_TYPES):
        allOrders = pyautogui.locateAllOnScreen(imPath('%s_order.png' % orderType), region=(GAME_REGION[0] + 32, GAME_REGION[1] + 46, 558, 44))
        for order in allOrders:
            orders[order] = orderType
    return orders

The newOrders and oldOrders parameters have values that were returned from different calls to getOrders(). The orders that are new to newOrders are returned in the added dictionaries and the orders that have since been removed are returned in the removed dictionary.

def getOrdersDifference(newOrders, oldOrders):
    """Finds the differences between the orders dictionaries passed. Return value is a tuple of two dictionaries.

    The first dictionary is the "added" dictionary of orders added to newOrders since oldOrders. The second dictionary is the "removed" dictionary of orders in oldOrders but removed in newOrders.

    Each dictionary has (left, top, width, height) for keys and an order constant for a value."""
    added = {}
    removed = {}

    # find all orders in newOrders that are new and not found in oldOrders
    for k in newOrders:
        if k not in oldOrders:
            added[k] = newOrders[k]
    # find all orders in oldOrders that were removed and not found in newOrders
    for k in oldOrders:
        if k not in newOrders:
            removed[k] = oldOrders[k]

    return added, removed

Step 11 - Making the Orders

Creating a dish involves clicking on the correct ingredients and then clicking on the rolling mat. The dish is place on a conveyor belt and eventually makes its way to a customer. The first part of the function is just the docstring and a few global statements.

def makeOrder(orderType):
    """Does the mouse clicks needed to create an order.

    The orderType parameter has the value of one of the ONIGIRI, GUNKAN_MAKI, CALIFORNIA_ROLL, SALMON_ROLL, SHRIMP_SUSHI, UNAGI_ROLL, DRAGON_ROLL, COMBO constants.

    The INVENTORY global variable is updated in this function for orders made.

    The return value is None for a successfully made order, or the string of an ingredient constant if that needed ingredient is missing."""
    global ROLLING_COMPLETE, INGRED_COORDS, INVENTORY

The next part of the code ensures that the bot doesn't try to make a dish when it's not possible. One of the reasons is that the mat is still in the process of rolling the previous dish. Also, a dish will stay on the mat after being rolled if there isn't space on the conveyor belt. (This happens when orders aren't picked up by a customer.)

This is an important check: if the bot starts clicking on ingredients when the rolling mat is occupied, then the bot's INVENTORY dictionary will contain an inaccurate count of ingredients, leading to other mistakes and eventually losing the game.

The mat takes about 1.5 seconds to complete, which is why the ROLLING_COMPLETE = time.time() + 1.5 is run after clicking the mat to begin rolling it. This is a simple check that doesn't take long to run.

But if the conveyor belt is occupied, then the previous order could still be on the mat waiting for a clear space on the belt. After performing the cheap ROLLING_TIME check, the bot then uses pyautogui.locateOnScreen() to see if the mat is clear. This guarantees that when the bot starts clicking on ingredients they will be moved to the mat.

    # wait until the mat is clear. The previous order could still be there if the conveyor belt has been full or the mat is currently rolling.
    while time.time() < ROLLING_COMPLETE and pyautogui.locateOnScreen(imPath('clear_mat.png'), region=(GAME_REGION[0] + 115, GAME_REGION[1] + 295, 220, 175)) is None:
        time.sleep(0.1)

But before the bot begins making a dish, it consults the INVENTORY dictionary to make sure it has enough of each of the ingredients in the dish's recipe. The recipes for each dish are held in the RECIPES constant.

If there isn't enough of an ingredient, the string in the ingredient's constant is returned. This information will be used to place an order for more of that ingredient.

    # check that all ingredients are available in the inventory.
    for ingredient, amount in RECIPE[orderType].items():
        if INVENTORY[ingredient] < amount:
            logging.debug('More %s is needed to make %s.' % (ingredient, orderType))
            return ingredient

Once it has been confirmed there is enough of each ingredient, calls to pyautogui.click() cause the bot to click on the appropriate ingredients, then click on the mat to roll it. The ROLLING_COMPLETE global variable is updated with the timestamp of when the mat rolling will be finished (1.5 seconds in the future) so the next dish can be prepared.

Just before the rolling mat is clicked though, the bot will check the conveyor belt for any excess dishes that weren't picked up by customers. While this is a waste of ingredients, these excess dishes tend to pile up (especially in the later levels), and slow down the bot from serving dishes to the point that it could lose the game. The call to findAndClickPlatesOnBelt() (described next) gets rid of any excess dishes that happen to be on the conveyor belt.

    # click on each of the ingredients
    for ingredient, amount in RECIPE[orderType].items():
        for i in range(amount):
            pyautogui.click(INGRED_COORDS[ingredient], duration=0.25)
            INVENTORY[ingredient] -= 1
    findAndClickPlatesOnBelt() # get rid of any left over meals on the conveyor belt, which may stall this meal from being loaded on the belt
    pyautogui.click(MAT_COORDS, duration=0.25) # click the rolling mat to make the order
    logging.debug('Made a %s order.' % (orderType))
    ROLLING_COMPLETE = time.time() + 1.5 # give the mat enough time (1.5 seconds) to finish rolling before being used again

Sometimes other customers will swoop in and grab dishes that were intended for other customers. To prevent the customers from leaving, the remakeTimes dictionary keeps track of when orders will need to be remade. However, if the customer leaves before picking up this remade dish, then it will circle endlessly on the conveyor belt. Eventually these excess dishes can pile up and stall new dishes from being added. The findAndClickPlatesOnBelt() will scan the conveyor belt next to the rolling mat for any dishes and click on them to remove them.

It does this by identifying the pink, blue, or red coloring of the plates. These colors are stored in the pink_plate_color.png, blue_plate_color.png, red_plate_color.png images.

def findAndClickPlatesOnBelt():
    """Find any plates on the conveyor belt that can be removed and click on them to remove them. This will get rid of excess orders."""
    for color in ('pink', 'blue', 'red'):
        result = pyautogui.locateCenterOnScreen(imPath('%s_plate_color.png' % (color)), region=(GAME_REGION[0] + 343, GAME_REGION[1] + 300, 50, 80))
        if result is not None:
            pyautogui.click(result)
            logging.debug('Clicked on %s plate on belt at X: %s Y: %s' % (color, result[0], result[1]))

Step 12 - Ordering More Ingredients

When the bot needs more ingredients, it must navigate the menu buttons on the phone in the lower right corner of the game window. This tutorial has already figured out these coordinates for you, but you could use the pyautogui.displayMousePosition() function to find coordinates for any pixel on the screen.

The first step is to click on the phone:

def orderIngredient(ingredient):
    """Do the clicks to purchase an ingredient. If successful, the ORDERING_COMPLETE dictionary is updated for when the ingredients will arive and INVENTORY can be updated. (This is handled in the updateInventory() function.)"""
    logging.debug('Ordering more %s (inventory says %s left)...' % (ingredient, INVENTORY[ingredient]))
    pyautogui.click(PHONE_COORDS, duration=0.25)

The next part of the code handles pressing the buttons to order rice. The timestamp in ORDERING_COMPLETE is checked to make sure a previous rice order hasn't been made. Then the screen is scanned for the cant_afford_rice.png image. The rice ordering button takes on a dimmed appearance if the player does not have enough money to order rice. In this case, the function returns.

    if ingredient == RICE and ORDERING_COMPLETE[RICE] is None:
        # Order rice.
        pyautogui.click(RICE1_COORDS, duration=0.25)

        # Check if we can't afford the rice
        if pyautogui.locateOnScreen(imPath('cant_afford_rice.png'), region=(GAME_REGION[0] + 498, GAME_REGION[1] + 242, 90, 75)):
            logging.debug("Can't afford rice. Canceling.")
            pyautogui.click(GAME_REGION[0] + 585, GAME_REGION[1] + 335, duration=0.25) # click cancel phone button
            return

Otherwise, the bot will click on the rice button. The code doesn't update INVENTORY quite yet, as it will take time for the rice to be delivered. (For simplicity, the bot will never use the Express Delivery option, though you could certainly build in the intelligence to do that.) The expected delivery time is set in the ORDERING_COMPLETE dictionary.

The INVENTORY will be updated with the new quantity in the updateInventory() function.

        # Purchase the rice
        pyautogui.click(RICE2_COORDS, duration=0.25)
        pyautogui.click(NORMAL_DELIVERY_BUTTON_COORDS, duration=0.25)
        ORDERING_COMPLETE[RICE] = time.time() + NORMAL_RESTOCK_TIME
        logging.debug('Ordered more %s' % (RICE))
        return

The next part does something similar except it navigates the phone menu for the non-rice ingredients. The same general logic is used; if an ingredient isn't affordable, the dimmed button image will inform the bot that it can't be purchased.

    elif ORDERING_COMPLETE[ingredient] is None:
        # Order non-rice ingredient.
        pyautogui.click(TOPPING_COORDS, duration=0.25)

        # Check if we can't afford the ingredient
        if pyautogui.locateOnScreen(imPath('cant_afford_%s.png' % (ingredient)), region=(GAME_REGION[0] + 446, GAME_REGION[1] + 187, 180, 180)):
            logging.debug("Can't afford %s. Canceling." % (ingredient))
            pyautogui.click(GAME_REGION[0] + 597, GAME_REGION[1] + 337, duration=0.25) # click cancel phone button
            return

Note that the bot doesn't have to keep track of how much money it has. It only needs to know if it can afford an ingredient or not. For simplicity, the "normal delivery" option is always used instead of the costly "express delivery" option:

        # Order the ingredient
        pyautogui.click(ORDER_BUTTON_COORDS[ingredient], duration=0.25)
        pyautogui.click(NORMAL_DELIVERY_BUTTON_COORDS, duration=0.25)
        ORDERING_COMPLETE[ingredient] = time.time() + NORMAL_RESTOCK_TIME
        logging.debug('Ordered more %s' % (ingredient))
        return

If it turns out the bot couldn't afford the desired ingredient, the next part will close the phone menu by clicking on the coordinates for the "hang up" button:

    # The ingredient has already been ordered, so close the phone menu.
    pyautogui.click(GAME_REGION[0] + 589, GAME_REGION[1] + 341) # click cancel phone button
    logging.debug('Already ordered %s.' % (ingredient))

The updateInventory() function is frequently called to check if the timestamps in ORDERING_COMPLETE indicate that the ordered ingredients have arrived. In that case, it updates INVENTORY with the new values. Shrimp, unagi, and salmon deliveries always add 5. Nori, roe, and rice deliveries always add 10.

def updateInventory():
    """Check if any ordered ingredients have arrived by looking at the timestamps in ORDERING_COMPLETE.
    Update INVENTORY global variable with the new quantities."""
    for ingredient in INVENTORY:
        if ORDERING_COMPLETE[ingredient] is not None and time.time() > ORDERING_COMPLETE[ingredient]:
            ORDERING_COMPLETE[ingredient] = None
            if ingredient in (SHRIMP, UNAGI, SALMON):
                INVENTORY[ingredient] += 5
            elif ingredient in (NORI, ROE, RICE):
                INVENTORY[ingredient] += 10
            logging.debug('Updated inventory with added %s:' % (ingredient))
            logging.debug(INVENTORY)

Step 13 - Checking for the End of the Level

The bot can tell when the level is over by doing image recognition for the you_win.png or you_fail.png images. If the game is over, the program terminates by calling sys.exit(). If the level has been beaten, the bot clicks on the "You Win" window so that it immediately tallies the stats and returns the string in the LEVEL_WIN_MESSAGE.

def checkForGameOver():
    """Checks the screen for the "You Win" or "You Fail" message.

    On winning, returns the string in LEVEL_WIN_MESSAGE.

    On losing, the program terminates."""

    # check for "You Win" message
    result = pyautogui.locateOnScreen(imPath('you_win.png'), region=(GAME_REGION[0] + 188, GAME_REGION[1] + 94, 262, 60))
    if result is not None:
        pyautogui.click(pyautogui.center(result))
        return LEVEL_WIN_MESSAGE

    # check for "You Fail" message
    result = pyautogui.locateOnScreen(imPath('you_failed.png'), region=(GAME_REGION[0] + 167, GAME_REGION[1] + 133, 314, 39))
    if result is not None:
        logging.debug('Game over. Quitting.')
        sys.exit()

Finally, the main() function is called if this script is being run (as opposed to imported as a module):

if __name__ == '__main__':
    main()

That's it!

If you download and run the bot, it doesn't have much problem beating all 7 levels of Sushi Go Round. But as you can tell from the leaderboard, if doesn't compare to the best human players. Feel free to modify the code to try to improve the performance of the bot.

Sushi Go Round is a good candidate for creating a bot since it's 2D sprite graphics are static and easy to identify from screenshots. If you find any other similar such games, please list them in the comments below! I've found that the "Skill" genre on Newgrounds, "puzzle", "gathering", and "rhythm" games are usually bot-friendly since their images are easier to identify. (There's a list of Flash game genres here.) Look for ones that have retro pixel graphics. In particular, these games seem like good candidates for making bots:

Color Finger
Cardinal
Sagacious Saga (helps if you know the floodfill algorithm)
Apple Catcher
Cold Runner
GatherX
Next Avoider
Dodge Copter
Rockocroco
Holy Stomping

And some trickier games, but still possible to make bots for:

Update: roddds on Reddit posted a link to his own Sushi Go Round bot he had made previously. He also has code and a video for a Diamond Dash-playing bot.

Making a Text Adventure Game with the cmd and textwrap Python Modules

2014-12-11T12:00:00-05:00

Text adventures are an old game genre where the entire world is textually described as a series of rooms. Play involves entering simple text commands such as "move north" or "eat pie". Each room in the game world has its own text description, items on the ground, and exits to adjacent rooms. "Room" is a general name for a single area in the game world: a room can be a large open canyon or the inside of a wardrobe. Multi-user text adventures, called MUDs or Multi-User Dungeons, were the precursor to modern MMORPGs. You can still play MUDs today by finding them on The Mud Connector.

Text adventures are easyto make because they don't require graphics. This tutorial uses two Python modules, cmd and textwrap and makes minimal use of object-oriented programming, but you don't have to know OOP concepts to follow. (But in general, text adventures would do very well with an object-oriented approach.) This tutorial is for beginner Python 3 programmers.

The code for Text Adventure Demo is available on GitHub.

The cmd module provides a generic command-line interface that has several useful features:

Tab-completion - Type a partial command and press tab, and the game can guess the rest of the command.
History browsing - Press the up arrow key to bring up the previously entered commands.
Automatic help - A help system for commands is automatically generated for your commands.

The Python Debugger (tutorial here) in the pdb module makes use of the cmd module for its command line interface.

To get tab-completion to work on Windows, download and install this module: https://pypi.python.org/pypi/pyreadline/2.0 (On Windows with Python 3, open a command window and type cd c:\Python34\Scripts and then pip install pyreadline.

Our program will be about turn-based, single-player, and about 800 lines long. You can download the complete version from here: Download textadventuredemo.py or look at the GitHub page.

Demo of Game Play

Here's what our text adventure game will look like. It won't have combat, but will have a small town that you can navigate while picking up and looking at different things. Money isn't implemented, but shops to buy and sell at are.

Text Adventure Demo!
====================

(Type "help" for commands.)

Town Square
===========
The town square is a large open space with a fountain in the center. Streets
lead in all directions.

A welcome sign stands here.
A bubbling fountain of green water.

North: North Y Street
South: South Y Street
East: East X Street
West: West X Street

> look sign
The welcome sign reads, "Welcome to this text adventure demo. You can type
"help" for a list of commands to use. Be sure to check out Al's cool programming
books at http://inventwithpython.com"

> look fountain
The water in the fountain is a bright green color. Is that... gatorade?

> north
You move to the north.
North Y Street
==============
The northern end of Y Street has really gone down hill. Pot holes are everywhere, as are stray cats, rats, and wombats.

A sign stands here, not bolted to the ground.

South: Town Square
East: Bakery
West: Thief Guild

> look sign
The sign reads, "Do Not Take This Sign"

> take sign
You take a sign.

> inventory
Inventory:
Do Not Take Sign Sign
Donut
Sword
README Note

> look readme
The README note reads, "Welcome to the text adventure demo. Be sure to check out the source code to see how this game is put together."

> eat donut
You eat a donut

> eat readme
You eat a README note

> eat sword
You cannot eat that.

> inventory
Inventory:
Sword
Do Not Take Sign Sign

> e
You move to the east.
Bakery
======
The delightful smell of meat pies fills the air, making you hungry. The baker flashes a grin, as he slides a box marked "Not Human Organs" under a table with his foot.

A "Shopping HOWTO" note rests on the ground.

South: East X Street
West: North Y Street

> list
For sale:
- Meat Pie
- Donut
- Bagel

> buy pie
You have purchased a meat pie

> buy pie
You have purchased a meat pie

> buy pie
You have purchased a meat pie

> inventory
Inventory:
Meat Pie (3)
Sword
Do Not Take Sign Sign

> quit
Thanks for playing!

The "Choose Your Own Adventure" Mistake

Beginners tend to write code that looks like a "Choose Your Own Adventure" book: the execution starts at the beginning of the program, then it jumps to another part of the code (just like the reader would turn to some page at a branching point in the book). I have an example of this type of program in my dragon2.py game. This works, but the program becomes unwieldy as it gets larger.

You won't have a townSquare() function that displays the Town Square text when called like so:

def townSquare():
    print('The town square is a large open space with a fountain in the center. Streets lead in all directions.')
    print()
    if TOWN_SQUARE_HAS_SIGN == True:
        print('A welcome sign stands here.')
    if TOWN_SQUARE_HAS_FOUNTAIN == True:
        print(getFountainDescription())
    print()
    print('North: North Y Street')
    print('South: South Y Street')
    print('East: East X Street')
    print('West: West X Street')

A better way to program a game is a more data structure-centric approach. This sounds very abstract. Here's an example of the data structure you'll have for locations in your game:

worldRooms = {
    'Town Square': {
        DESC: 'The town square is a large open space with a fountain in the center. Streets lead in all directions.',
        NORTH: 'North Y Street',
        EAST: 'East X Street',
        SOUTH: 'South Y Street',
        WEST: 'West X Street',
        GROUND: ['Welcome Sign', 'Fountain']},
    'North Y Street': {
        DESC: 'The northern end of Y Street has really gone down hill. Pot holes are everywhere, as are stray cats, rats, and wombats.',
        WEST: 'Thief Guild',
        EAST: 'Bakery',
        SOUTH: 'Town Square',
        GROUND: ['Do Not Take Sign Sign']},
        ...

You can see that the general structure of the worldRooms dictionary is:

worldRooms = {
    'Room Name': {
        DESC: 'Description of room.',
        NORTH: 'Name of room to the north.',
        GROUND: ['Name of an item on the ground in this room', 'Another item name']
    },
        ...
}

And here's a data structure to hold the different types of items in the game:

worldItems = {
    'Welcome Sign': {
        GROUNDDESC: 'A welcome sign stands here.',
        SHORTDESC: 'a welcome sign',
        LONGDESC: 'The welcome sign reads, "Welcome to this text adventure demo. You can type "help" for a list of commands to use. Be sure to check out Al\'s cool programming books at http://inventwithpython.com"',
        TAKEABLE: False,
        DESCWORDS: ['welcome', 'sign']},
    'Fountain': {
        GROUNDDESC: 'A bubbling fountain of green water.',
        SHORTDESC: 'a fountain',
        LONGDESC: 'The water in the fountain is a bright green color. Is that... gatorade?',
        TAKEABLE: False,
        DESCWORDS: ['fountain']},
        ...

You can see that the general structure of the worldRooms dictionary is:

worldItems = {
    'Item Name': {
        GROUNDDESC: 'How this item is described when on the ground.',
        SHORTDESC: 'A short description of this item.',
        LONGDESC: 'A long description of this item, used when the player looks at it.',
        TAKEABLE: True, # whether this item can be taken and put in your inventory
        DESCWORDS: ['a word the player can use to refer to this item', 'another word']
    },
        ...
}

By putting the rooms and items into data structures, now you can write a single displayLocation() function that can display any room in the game because it works off of the values in the worldRooms data structure. You can write code that deals with rooms and items generically. Writing a big game world will be much faster, just like how interchangeable parts speed up manufacturing and factories.

A map of the full world looks something like this:

        +---------+    +---------+
        | Thief   O    | Bakery  |
        | Guild   |    |         |
+------++------O--+    +----O----+
| Used |
|Anvils|        Town Square     +--------+
|      O                        |Obs Deck|
+------++----O----+    +----O----/  /
        | Black-  O    | Wizard /  /
        | smith   |    | Tower    /
        +---------+    +---------+

(Data structures like these are normally put into classes in objet-oriented programming. To keep this text adventure demo simple, I'm using dictionaries and lists.)

Constant Variables and Global Variables

Start from scratch with a blank textadventuredemo.py file. Add a #! python3 shebang line, some comments describing the program, and the worldRooms and worldItems data structures. Since this is mostly text and not code, you might want to just copy and paste the code from the snippet on GitHub.

The keys in the above data structures are constant variables:

DESC = 'desc'
NORTH = 'north'
SOUTH = 'south'
EAST = 'east'
WEST = 'west'
UP = 'up'
DOWN = 'down'
GROUND = 'ground'
SHOP = 'shop'
GROUNDDESC = 'grounddesc'
SHORTDESC = 'shortdesc'
LONGDESC = 'longdesc'
TAKEABLE = 'takeable'
EDIBLE = 'edible'
DESCWORDS = 'descwords'

The reason that constant variables are used instead of typing the string directly is to minimize the chance of errors. If you mistype the string 'desc' as 'dsec', Python will not immediately complain because since 'dsec' is a valid string. Later there will be a KeyError when you try to use 'dsec' as a key, but this is a vague error message that could have many causes.

But if you are using constant variables instead, mistyping DESC as DSEC will immediately crash the program with a NameError exception since DSEC isn't a variable name. The sooner your program crashes, the easier it is to find the crash-causing bug. If your program silently continued to work, it will take longer to trace the original bug.

There is also the SCREEN_WIDTH constant, which will be used by the textwrap module to determine how wide the program should assume the screen is:

SCREEN_WIDTH = 80

Th SCREEN_WIDTH constant will be explained in the next section.

The location and inventory global variables will keep track of the player's position and inventory. The showFullExits variable tracks whether to show full or brief versions of the current room's exits (this is explained later in the displayLocation() function). Add the following code to your program:

location = 'Town Square' # start in town square
inventory = ['README Note', 'Sword', 'Donut'] # start with blank inventory
showFullExits = True

(Normally your programs should avoid using global variables, but they're used here to keep the text adventure demo code simple.)

Also, import the following modules into you program:

import cmd, sys, textwrap

The textwrap Module

The textwrap module can intelligently break up a string into multiple lines of a given width. You might think this is easily done with code such as the following, which breaks the desc string up into lines 80 characters wide:

desc = 'The town square is a large open space with a fountain in the center. Streets lead in all directions.'

for i in range(0, len(desc), 80):
    print(desc[i:i + 80])

But this can cut off a line right in the middle of words, like this:

The town square is a large open space with a fountain in the center. Streets lea
d in all directions.

The textwrap.wrap() function is smart enough to avoid chopping lines in the middle of a word. It returns a list, with each line as a string in the list:

import textwrap
desc = 'The town square is a large open space with a fountain in the center. Streets lead in all directions.'

for line in textwrap.wrap(desc, 80):
    print(line)

The town square is a large open space with a fountain in the center. Streets
lead in all directions.

To make it easy to change the screen width that textwrap.wrap() uses, pass the SCREEN_WIDTH constant for the second argument. That way, if you want to change the screen width you only need to change the SCREEN_WIDTH value.

Location and Movement Functions

When the player walks into a room, the displayed text looks something like this:

Town Square
===========
The town square is a large open space with a fountain in the center. Streets
lead in all directions.

A welcome sign stands here.
A bubbling fountain of green water.

North: North Y Street
South: South Y Street
East: East X Street
West: West X Street

The data for each room is tied up in the worldRooms variable. You need a function that, given the name of the room as a string, will print out text like the above. This will need to print out:

The room's name
The room's description
A list of the items on the ground in this room
A list of all the available exits

Add the following code to your program:

def displayLocation(loc):
    """A helper function for displaying an area's description and exits."""
    # Print the room name.
    print(loc)
    print('=' * len(loc))

    # Print the room's description (using textwrap.wrap())
    print('\n'.join(textwrap.wrap(worldRooms[loc][DESC], SCREEN_WIDTH)))

    # Print all the items on the ground.
    if len(worldRooms[loc][GROUND]) > 0:
        print()
        for item in worldRooms[loc][GROUND]:
            print(worldItems[item][GROUNDDESC])

    # Print all the exits.
    exits = []
    for direction in (NORTH, SOUTH, EAST, WEST, UP, DOWN):
        if direction in worldRooms[loc].keys():
            exits.append(direction.title())
    print()
    if showFullExits:
        for direction in (NORTH, SOUTH, EAST, WEST, UP, DOWN):
            if direction in worldRooms[location]:
                print('%s: %s' % (direction.title(), worldRooms[location][direction]))
    else:
        print('Exits: %s' % ' '.join(exits))

There will also be a moveDirection() function that, given a north/south/east/west/up/down string argument, will change the location global variable to the new location.

But it will only do this if the direction was a valid one to make. If the player is able to move in the given direction, the new room's description will be displayed on the screen. Add the following code to your program:

def moveDirection(direction):
    """A helper function that changes the location of the player."""
    global location

    if direction in worldRooms[location]:
        print('You move to the %s.' % direction)
        location = worldRooms[location][direction]
        displayLocation(location)
    else:
        print('You cannot move in that direction')

You'll see how these functions are used by the command line interface in a bit. But if you want to see how the code you have so far works, add the following temporary code:

# TEMPORARY CODE:
while True:
    displayLocation(location)
    response = input()
    if response == 'quit':
        break
    if response in (NORTH, SOUTH, EAST, WEST, UP, DOWN):
        moveDirection(response)

Your program will now look like this source code on GitHub. When you run this program, you will be able to move around the game world by typing north, south, east, west, up, and down.

Notice a few things about this game world:

Moving in an invalid direction results in 'You cannot move in that direction' printed to the screen.
At the top of the wizard's tower, the "Magical Escalator to Nowhere" room's up exit leads to itself. This means if you exit up from this room, you will arrive in the same room. You can effectively go up an infinite amount of times. This is a side effect of the way the room data structures are set up.

There are just a few more helper functions you'll need.

Item Helper Functions

These functions all work with the item data structure you have already set up. You won't quite see how these functions are needed right now, but they will be explained later.

Remember that the worldItems variable is a dictionary with key-value pairs that look like this:

    'Fountain': {
        GROUNDDESC: 'A bubbling fountain of green water.',
        SHORTDESC: 'a fountain',
        LONGDESC: 'The water in the fountain is a bright green color. Is that... gatorade?',
        TAKEABLE: False,
        DESCWORDS: ['fountain']},

The helper functions for items are:

getAllDescWords() - Given a list of strings of item names, return a list with all of these items' DESCWORDS strings.
getAllFirstDescWords() - Given a list of strings of item names, return a list with all of these items' first DESCWORDS strings.
getFirstItemMatchingDesc() - Given a string and a list of item names, return a string of the name of the first item that has a DESCWORD string that matches the given string argument.
getAllItemsMatchingDesc() - Given a string and a list of item names, return a list of strings of item names for items that have the given string argument as one of their DESCWORD strings.

Add the following code to your programs:

def getAllDescWords(itemList):
    """Returns a list of "description words" for each item named in itemList."""
    itemList = list(set(itemList)) # make itemList unique
    descWords = []
    for item in itemList:
        descWords.extend(worldItems[item][DESCWORDS])
    return list(set(descWords))

def getAllFirstDescWords(itemList):
    """Returns a list of the first "description word" in the list of
    description words for each item named in itemList."""
    itemList = list(set(itemList)) # make itemList unique
    descWords = []
    for item in itemList:
        descWords.append(worldItems[item][DESCWORDS][0])
    return list(set(descWords))

def getFirstItemMatchingDesc(desc, itemList):
    itemList = list(set(itemList)) # make itemList unique
    for item in itemList:
        if desc in worldItems[item][DESCWORDS]:
            return item
    return None

def getAllItemsMatchingDesc(desc, itemList):
    itemList = list(set(itemList)) # make itemList unique
    matchingItems = []
    for item in itemList:
        if desc in worldItems[item][DESCWORDS]:
            matchingItems.append(item)
    return matchingItems

The list(set(itemList)) code is a Pythonic way to get rid of duplicate values in a list by coverting the list to a set and back to a list. Note that this might change the order of the values in the list, since the set data type is unordered.

Creating a Command Line Interface with the cmd Module

The cmd module frees us from reinventing the wheel when creating the command line interface for the text adventure. First, create a class that subclasses cmd.Cmd. The cmd module will read any methods that begin with do_, complete_ and help_ for it's command, tab-completion, and help system features, respectively.

Here's a short example. Add the following code to your program:

class TextAdventureCmd(cmd.Cmd):
    prompt = '\n> '

    # The default() method is called when none of the other do_*() command methods match.
    def default(self, arg):
        print('I do not understand that command. Type "help" for a list of commands.')

    # A very simple "quit" command to terminate the program:
    def do_quit(self, arg):
        """Quit the game."""
        return True # this exits the Cmd application loop in TextAdventureCmd.cmdloop()

    def help_combat(self):
        print('Combat is not implemented in this program.')

There are several cmd-specific things about this code:

The string in the prompt member variable is printed when the player is expected to begin typing in a command. In your text adventure's case, this will be the '\n>' string: a newline followed by a > character.
The default() method will be called by the command line interface when it cannot understand the command the player typed. In this case, a "I do not understand" message is printed to the screen.
When the player types in a command, the command line interface checks if there are any methods of the same name as the command to handle it. For example, "quit" would be handled by do_quit(). If the player entered the "qwerty" command but there is no do_qwerty() method, the default() method is called instead.
When a do_<command>() returns, the command line interface will let the player type in another command. If a do_<command>() returns the value True, the command line interface will stop asking for commands.
The do_quit() method implements the "quit" command. Since it returns True, the command line interface will stop asking the player for commands.
The docstring at the top of each do_<command>() function will automatically be used for the command line interface's help system.
The help_combat() method implements the "help combat" command. You can add as many help topics as you want: typing "help" by itself lists all of them. Since there is no combat in this text adventure, this function prints a message telling the player there is no combat.
The arg parameter in default() and do_quit() will be explained later.

To kick off the command line interface code, you will need to call the cmd.Cmd object's cmdloop() method. Take out the temporary code in the while True: loop and add the following to your program:

if __name__ == '__main__':
    print('Text Adventure Demo!')
    print('====================')
    print()
    print('(Type "help" for commands.)')
    print()
    displayLocation(location)
    TextAdventureCmd().cmdloop()
    print('Thanks for playing!')

Your program should now look like this file on GitHub.

The cmd Help System

When you run this program, the movement commands won't work (they were implemented in the temporary while loop you removed) but you can run the "help", "help quit", and "help combat" commands:

> help

Documented commands (type help ):
========================================
help quit

Miscellaneous help topics:
==========================
combat

> help quit
Quit the game.

> help combat
Combat is not implemented in this program.

Notice that the "quit" command's docstring has been used for the "help quit" command. You can end this program by running "quit", which makes the command line interface call the do_quit() method. Since it is a do_<command>() method that returns True, it causes the TextAdventureCmd().cmdloop() function return and the execution reaches the end of the source code.

As a free feature provided by the command line interface, pressing the up arrow key will cycle through the command history. This provides an easy way to re-enter commands you previously typed.

The Move Commands and Tab Completion

In order to move the player around, you'll need a do_north() method for the "north" command, a do_south() method for the "south" command, and so on. All of these methods will simply call the moveDirection() function with the appropriate argument. Add the following to your program:

    # These direction commands have a long (i.e. north) and show (i.e. n) form.
    # Since the code is basically the same, I put it in the moveDirection()
    # function.
    def do_north(self, arg):
        """Go to the area to the north, if possible."""
        moveDirection('north')

    def do_south(self, arg):
        """Go to the area to the south, if possible."""
        moveDirection('south')

    def do_east(self, arg):
        """Go to the area to the east, if possible."""
        moveDirection('east')

    def do_west(self, arg):
        """Go to the area to the west, if possible."""
        moveDirection('west')

    def do_up(self, arg):
        """Go to the area upwards, if possible."""
        moveDirection('up')

    def do_down(self, arg):
        """Go to the area downwards, if possible."""
        moveDirection('down')

    # Since the code is the exact same, we can just copy the
    # methods with shortened names:
    do_n = do_north
    do_s = do_south
    do_e = do_east
    do_w = do_west
    do_u = do_up
    do_d = do_down

Because the "n" and "north" commands would do the same thing, we can create another function with the same code by assigning do_n = do_north, and so on.

To toggle the Boolean value in the global showFullExits variable, an "exits" command can be implemented in do_exits(). Add the following to your program:

    def do_exits(self, arg):
        """Toggle showing full exit descriptions or brief exit descriptions."""
        global showFullExits
        showFullExits = not showFullExits
        if showFullExits:
            print('Showing full exit descriptions.')
        else:
            print('Showing brief exit descriptions.')

With this code, your program should look like this file on GitHub. When you run this program, the north/south/east/west/up/down commands will all work.

Inventory

The "inventory" command will display the contents of the inventory global variable. Rather than just a do_inventory() method that runs print(inventory), there's additional code that checks if the player has more than one of a type of item. So an inventory value of ['Donut', 'Donut', 'Donut'] will display a single line: Donut (3).

Add the following code to your program:

    def do_inventory(self, arg):
        """Display a list of the items in your possession."""

        if len(inventory) == 0:
            print('Inventory:\n  (nothing)')
            return

        # first get a count of each distinct item in the inventory
        itemCount = {}
        for item in inventory:
            if item in itemCount.keys():
                itemCount[item] += 1
            else:
                itemCount[item] = 1

        # get a list of inventory items with duplicates removed:
        print('Inventory:')
        for item in set(inventory):
            if itemCount[item] > 1:
                print('  %s (%s)' % (item, itemCount[item]))
            else:
                print('  ' + item)

    do_inv = do_inventory

To add an identical "inv" shortcut command, the do_inv = do_inventory line is added after the do_inventory() function.

Taking and Dropping Items

Every room in the worldRooms data structure has a GROUND key whose value is a list of items on the ground of that room. By removing items from the inventory list and adding them to the GROUND list, the player can "drop" the item in a certain room. The items will continue to be on the ground even if the player leaves the room and comes back. Similarly, by removing a value from the GROUND list and adding it to the inventory list, the player can "take" the item.

The "take" and "drop" commands are a bit more complicated: There is text that follows the "take" and "drop" words such as in "take sign" or "drop sword". The additional text is passed to the do_<command>() function for its arg parameter. So if the player enters the command "drop sword", the do_drop() method is called with 'sword' passed for its arg parameter.

The drop and take methods will have to do more than modify inventory and the GROUND key's value. They must handle the player forgetting to specify what to take/drop, check that the item is actually on the ground/inventory, and if the object is "takeable" (that is, it's TAKEABLE key's value is True).

Also, items can be referred to by any of it's DESCWORDS from the worldItems data structure. For example, the sword item:

    'Sword': {
        GROUNDDESC: 'A sword lies on the ground.',
        SHORTDESC: 'a sword',
        LONGDESC: 'A longsword, engraved with the word, "Exkaleber"',
        DESCWORDS: ['sword', 'exkaleber', 'longsword']},}

...has a DESCWORDS value of ['sword', 'exkaleber', 'longsword']. So the "drop sword", "drop exkaleer", and "drop longsword" would all refer to the same sword to drop.

Add the following code to your program:

    def do_take(self, arg):
        """"take <item> - Take an item on the ground."""

        # put this value in a more suitably named variable
        itemToTake = arg.lower()

        if itemToTake == '':
            print('Take what? Type "look" the items on the ground here.')
            return

        cantTake = False

        # get the item name that the player's command describes
        for item in getAllItemsMatchingDesc(itemToTake, worldRooms[location][GROUND]):
            if worldItems[item].get(TAKEABLE, True) == False:
                cantTake = True
                continue # there may be other items named this that you can take, so we continue checking
            print('You take %s.' % (worldItems[item][SHORTDESC]))
            worldRooms[location][GROUND].remove(item) # remove from the ground
            inventory.append(item) # add to inventory
            return

        if cantTake:
            print('You cannot take "%s".' % (itemToTake))
        else:
            print('That is not on the ground.')

    def do_drop(self, arg):
        """"drop <item> - Drop an item from your inventory onto the ground."""

        # put this value in a more suitably named variable
        itemToDrop = arg.lower()

        # get a list of all "description words" for each item in the inventory
        invDescWords = getAllDescWords(inventory)

        # find out if the player doesn't have that item
        if itemToDrop not in invDescWords:
            print('You do not have "%s" in your inventory.' % (itemToDrop))
            return

        # get the item name that the player's command describes
        item = getFirstItemMatchingDesc(itemToDrop, inventory)
        if item != None:
            print('You drop %s.' % (worldItems[item][SHORTDESC]))
            inventory.remove(item) # remove from inventory
            worldRooms[location][GROUND].append(item) # add to the ground

After you are finished, your program will look like this file on GitHub. When you run the program, you will be able to drop and take items (provided they have the TAKEABLE setting).

Tab Completion

if the player types a partial command, such as "nor", they can press the Tab key and the command line interface will complete the command: "north". The command line interface knows this because "north" is the only command that begins with "nor". If there were other commands that began with "nor", pressing Tab would bring up a list of possible complete commands.

However, say that the player has an inventory value of ['sword', 'swingset', 'swampwater'] and had entered "drop sw" and pressed Tab. The command line interface knows all the commands because it can see what do_%lt;command>() functions there are. But items on the ground or in the inventory are specific to your program, so you will need a way to tell the command line interface what it should return for possible tab completions.

This is done by the complete_<command>() methods. These methods have the following parameters:

text is the part after the command. If "drop sw" were being completed, text would be set to 'sw'.
line is the entire command that was entered. If "drop sw" were being completed, line would be set to 'drop sw'.
begidx is index in line where the last word begins. If "drop sw" were being completed, begidx would be 5, which is where 'sw' begins.
endidx is index in line where the last word begins. If "drop sw" were being completed, endidx would be 7, which is where 'sw' ends.

When the Tab key is pressed, the command's complete_<command>() method is called and passed the command typed in so far. For example, typing "drop sw"-Tab will call the complete_drop() method and typing "take sw"-Tab will call the complete_take() method. If a complete_<command>() method command doesn't exist, such as not complete_qwerty() method for "qwerty sw", then the command line interface does nothing.

Using the getAllFirstDescWords() helper function, you can add complete_take() and complete_drop() methods to determine what item the player is trying to take or drop. Add the following to your program:

    def complete_take(self, text, line, begidx, endidx):
        possibleItems = []
        text = text.lower()

        # if the user has only typed "take" but no item name:
        if not text:
            return getAllFirstDescWords(worldRooms[location][GROUND])

        # otherwise, get a list of all "description words" for ground items matching the command text so far:
        for item in list(set(worldRooms[location][GROUND])):
            for descWord in worldItems[item][DESCWORDS]:
                if descWord.startswith(text) and worldItems[item].get(TAKEABLE, True):
                    possibleItems.append(descWord)

        return list(set(possibleItems)) # make list unique


    def complete_drop(self, text, line, begidx, endidx):
        possibleItems = []
        itemToDrop = text.lower()

        # get a list of all "description words" for each item in the inventory
        invDescWords = getAllDescWords(inventory)

        for descWord in invDescWords:
            if line.startswith('drop %s' % (descWord)):
                return [] # command is complete

        # if the user has only typed "drop" but no item name:
        if itemToDrop == '':
            return getAllFirstDescWords(inventory)

        # otherwise, get a list of all "description words" for inventory items matching the command text so far:
        for descWord in invDescWords:
            if descWord.startswith(text):
                possibleItems.append(descWord)

        return list(set(possibleItems)) # make list unique

Your program will look like this file on GitHub. When you run the program, you will be able to type "drop sw", then press Tab, and the command will complete to "drop sword".

Looking at Things

The "look" command will have similar do_look() and complete_look() methods. Typing "look" will print the current room's DEC key's value. Typing "look exits" will print the names of all the adjacent rooms, while "look " will print the name of the room in that direction. The player can also type "look " to look at a item that is either on the ground or in their inventory.

Enter the following code for the "look" command:

    def do_look(self, arg):
        """Look at an item, direction, or the area:
"look" - display the current area's description
"look <direction>" - display the description of the area in that direction
"look exits" - display the description of all adjacent areas
"look <item>" - display the description of an item on the ground or in your inventory"""

        lookingAt = arg.lower()
        if lookingAt == '':
            # "look" will re-print the area description
            displayLocation(location)
            return

        if lookingAt == 'exits':
            for direction in (NORTH, SOUTH, EAST, WEST, UP, DOWN):
                if direction in worldRooms[location]:
                    print('%s: %s' % (direction.title(), worldRooms[location][direction]))
            return

        if lookingAt in ('north', 'west', 'east', 'south', 'up', 'down', 'n', 'w', 'e', 's', 'u', 'd'):
            if lookingAt.startswith('n') and NORTH in worldRooms[location]:
                print(worldRooms[location][NORTH])
            elif lookingAt.startswith('w') and WEST in worldRooms[location]:
                print(worldRooms[location][WEST])
            elif lookingAt.startswith('e') and EAST in worldRooms[location]:
                print(worldRooms[location][EAST])
            elif lookingAt.startswith('s') and SOUTH in worldRooms[location]:
                print(worldRooms[location][SOUTH])
            elif lookingAt.startswith('u') and UP in worldRooms[location]:
                print(worldRooms[location][UP])
            elif lookingAt.startswith('d') and DOWN in worldRooms[location]:
                print(worldRooms[location][DOWN])
            else:
                print('There is nothing in that direction.')
            return

        # see if the item being looked at is on the ground at this location
        item = getFirstItemMatchingDesc(lookingAt, worldRooms[location][GROUND])
        if item != None:
            print('\n'.join(textwrap.wrap(worldItems[item][LONGDESC], SCREEN_WIDTH)))
            return

        # see if the item being looked at is in the inventory
        item = getFirstItemMatchingDesc(lookingAt, inventory)
        if item != None:
            print('\n'.join(textwrap.wrap(worldItems[item][LONGDESC], SCREEN_WIDTH)))
            return

        print('You do not see that nearby.')


    def complete_look(self, text, line, begidx, endidx):
        possibleItems = []
        lookingAt = text.lower()

        # get a list of all "description words" for each item in the inventory
        invDescWords = getAllDescWords(inventory)
        groundDescWords = getAllDescWords(worldRooms[location][GROUND])
        shopDescWords = getAllDescWords(worldRooms[location].get(SHOP, []))

        for descWord in invDescWords + groundDescWords + shopDescWords + [NORTH, SOUTH, EAST, WEST, UP, DOWN]:
            if line.startswith('look %s' % (descWord)):
                return [] # command is complete

        # if the user has only typed "look" but no item name, show all items on ground, shop and directions:
        if lookingAt == '':
            possibleItems.extend(getAllFirstDescWords(worldRooms[location][GROUND]))
            possibleItems.extend(getAllFirstDescWords(worldRooms[location].get(SHOP, [])))
            for direction in (NORTH, SOUTH, EAST, WEST, UP, DOWN):
                if direction in worldRooms[location]:
                    possibleItems.append(direction)
            return list(set(possibleItems)) # make list unique

        # otherwise, get a list of all "description words" for ground items matching the command text so far:
        for descWord in groundDescWords:
            if descWord.startswith(lookingAt):
                possibleItems.append(descWord)

        # otherwise, get a list of all "description words" for items for sale at the shop (if this is one):
        for descWord in shopDescWords:
            if descWord.startswith(lookingAt):
                possibleItems.append(descWord)

        # check for matching directions
        for direction in (NORTH, SOUTH, EAST, WEST, UP, DOWN):
            if direction.startswith(lookingAt):
                possibleItems.append(direction)

        # get a list of all "description words" for inventory items matching the command text so far:
        for descWord in invDescWords:
            if descWord.startswith(lookingAt):
                possibleItems.append(descWord)

        return list(set(possibleItems)) # make list unique

The program will now look like this file on GitHub.

Shops

Shops are rooms that have a SHOP key, such as the Bakery room:

    'Bakery': {
        DESC: 'The delightful smell of meat pies fills the air, making you hungry. The baker flashes a grin, as he slides a box marked "Not Human Organs" under a table with his foot.',
        WEST: 'North Y Street',
        SOUTH: 'East X Street',
        SHOP: ['Meat Pie', 'Donut', 'Bagel'],
        GROUND: ['Shop Howto']},

The value for the SHOP is a list of items that the shop sells. Inside these rooms, the player can run the "list" command (to see what is for sale), the "buy" command (to purchase an item), and the "sell" command (to pawn an item from the player's inventory). For simplicity, any item can be sold to any shop. Also, money is currently not implemented in this game, so items in the shop are free.

Several things must be checked when the player tries to run these commands: Is the player currently in a shop room? Did the player forget to specify what they want to buy or sell? Does the shop sell what the player wants to buy? Does the player have the item they want to sell to the shop? The following code implements the "list", "buy", and "sell" commands and addresses all these issues. Add the following code to your program:

    def do_list(self, arg):
        """List the items for sale at the current location's shop. "list full" will show details of the items."""
        if SHOP not in worldRooms[location]:
            print('This is not a shop.')
            return

        arg = arg.lower()

        print('For sale:')
        for item in worldRooms[location][SHOP]:
            print('  - %s' % (item))
            if arg == 'full':
                print('\n'.join(textwrap.wrap(worldItems[item][LONGDESC], SCREEN_WIDTH)))


    def do_buy(self, arg):
        """"buy <item>" - buy an item at the current location's shop."""
        if SHOP not in worldRooms[location]:
            print('This is not a shop.')
            return

        itemToBuy = arg.lower()

        if itemToBuy == '':
            print('Buy what? Type "list" or "list full" to see a list of items for sale.')
            return

        item = getFirstItemMatchingDesc(itemToBuy, worldRooms[location][SHOP])
        if item != None:
            # NOTE - If you wanted to implement money, here is where you would add
            # code that checks if the player has enough, then deducts the price
            # from their money.
            print('You have purchased %s' % (worldItems[item][SHORTDESC]))
            inventory.append(item)
            return

        print('"%s" is not sold here. Type "list" or "list full" to see a list of items for sale.' % (itemToBuy))


    def complete_buy(self, text, line, begidx, endidx):
        if SHOP not in worldRooms[location]:
            return []

        itemToBuy = text.lower()
        possibleItems = []

        # if the user has only typed "buy" but no item name:
        if not itemToBuy:
            return getAllFirstDescWords(worldRooms[location][SHOP])

        # otherwise, get a list of all "description words" for shop items matching the command text so far:
        for item in list(set(worldRooms[location][SHOP])):
            for descWord in worldItems[item][DESCWORDS]:
                if descWord.startswith(text):
                    possibleItems.append(descWord)

        return list(set(possibleItems)) # make list unique


    def do_sell(self, arg):
        """"sell <item>" - sell an item at the current location's shop."""
        if SHOP not in worldRooms[location]:
            print('This is not a shop.')
            return

        itemToSell = arg.lower()

        if itemToSell == '':
            print('Sell what? Type "inventory" or "inv" to see your inventory.')
            return

        for item in inventory:
            if itemToSell in worldItems[item][DESCWORDS]:
                # NOTE - If you wanted to implement money, here is where you would add
                # code that gives the player money for selling the item.
                print('You have sold %s' % (worldItems[item][SHORTDESC]))
                inventory.remove(item)
                return

        print('You do not have "%s". Type "inventory" or "inv" to see your inventory.' % (itemToSell))


    def complete_sell(self, text, line, begidx, endidx):
        if SHOP not in worldRooms[location]:
            return []

        itemToSell = text.lower()
        possibleItems = []

        # if the user has only typed "sell" but no item name:
        if not itemToSell:
            return getAllFirstDescWords(inventory)

        # otherwise, get a list of all "description words" for inventory items matching the command text so far:
        for item in list(set(inventory)):
            for descWord in worldItems[item][DESCWORDS]:
                if descWord.startswith(text):
                    possibleItems.append(descWord)

        return list(set(possibleItems)) # make list unique

When you are finished typing in this code, your program will look like this file on GitHub.

Eating

Some items are marked as edible by having an EDIBLE key set to True For example, Meat Pies, Bagels, and Donuts are all edible items:

    'Meat Pie': {
        GROUNDDESC: 'A suspicious meat pie rests on the ground.',
        SHORTDESC: 'a meat pie',
        LONGDESC: 'A meat pie. It tastes like chicken.',
        EDIBLE: True,
        DESCWORDS: ['pie', 'meat']},
    'Bagel': {
        GROUNDDESC: 'A bagel rests on the ground. (Gross.)',
        SHORTDESC: 'a bagel',
        LONGDESC: 'It is a donut-shaped bagel.',
        EDIBLE: True,
        DESCWORDS: ['bagel']},
    'Donut': {
        GROUNDDESC: 'A donut rests on the ground. (Gross.)',
        SHORTDESC: 'a donut',
        LONGDESC: 'It is a bagel-shaped donut.',
        EDIBLE: True,
        DESCWORDS: ['donut']},

For simplicity, eating things doesn't do anything other than remove them from your inventory. But you could implement health or hunger levels in your text adventure, and need eat (or drink) items or else have adverse effects. There's nothing new about how the do_eat() and complete_eat() functions work. Add the following code to your program:

    def do_eat(self, arg):
        """"eat <item>" - eat an item in your inventory."""
        itemToEat = arg.lower()

        if itemToEat == '':
            print('Eat what? Type "inventory" or "inv" to see your inventory.')
            return

        cantEat = False

        for item in getAllItemsMatchingDesc(itemToEat, inventory):
            if worldItems[item].get(EDIBLE, False) == False:
                cantEat = True
                continue # there may be other items named this that you can eat, so we continue checking
            # NOTE - If you wanted to implement hunger levels, here is where
            # you would add code that changes the player's hunger level.
            print('You eat %s' % (worldItems[item][SHORTDESC]))
            inventory.remove(item)
            return

        if cantEat:
            print('You cannot eat that.')
        else:
            print('You do not have "%s". Type "inventory" or "inv" to see your inventory.' % (itemToEat))


    def complete_eat(self, text, line, begidx, endidx):
        itemToEat = text.lower()
        possibleItems = []

        # if the user has only typed "eat" but no item name:
        if itemToEat == '':
            return getAllFirstDescWords(inventory)

        # otherwise, get a list of all "description words" for edible inventory items matching the command text so far:
        for item in list(set(inventory)):
            for descWord in worldItems[item][DESCWORDS]:
                if descWord.startswith(text) and worldItems[item].get(EDIBLE, False):
                    possibleItems.append(descWord)

        return list(set(possibleItems)) # make list unique

With the above code added, you will have finished the entire text adventure program. This program can be downloaded from GitHub: https://raw.githubusercontent.com/asweigart/textadventuredemo/master/textadventuredemo.py

Ideas for New Features

That's it for this text adventure tutorial. Because of the cmd module's command line interface features, it is fairly easy to add new commands to your game. From here, there are several things you could add to your game:

Add HP, hunger/thirst levels, and status effects. (These are common to RPG-like games.)
Combat with randomly wandering monsters.
Casting magic spells, or learning new spells from spellbook items.
Drinking items, including potions which can have magical effects.
Equipping items, such as wearing helmets or wielding swords.
Money, including different types of currencies that shops can accept or deny.
Several new rooms to expand the world.

If you are interested in creating a roguelike (a genre that is sort of like the Diablo games except with ASCII-art graphics), the libtcod module will be very helpful. There are tutorials here and here.

I detail the differences between these genre of text-based games in my blog post, Text Adventure vs. MUD vs. Roguelike vs. Dwarf Fortress.

You can try playing MUDs you find through The Mud Connector to get new ideas for additional features you'd like to add. Good luck, and have fun!