Type hints and code style

Make a day19 folder for today’s files, open it in your editor, and run each script from its terminal, as on earlier days. Later in the day you will install two tools into a virtual environment, so create one in day19 now if you like (Day 13: python -m venv .venv, then activate it).

A program is read far more often than it is written: by teammates, by reviewers, and by you a month from now. Yesterday’s tools were about what code can do. Today is about making code easy to read and hard to misuse. You will write down what type each value should be, so a reader knows what to pass in and a tool can catch mistakes before the program runs. You will learn the shared style rules that make every Python file look familiar, and let tools apply them for you. And you will write the docstrings and comments that answer a reader’s questions before they ask them.

Here is a function you could have written on Day 9. What should you pass to it?

def total_cost(price, quantity):
    return price * quantity


print(total_cost(2.5, 4))
print(total_cost("2.5", 4))

10.0
2.52.52.52.5

The name suggests numbers, but nothing says so. The second call passes the string "2.5", perhaps straight from input() (Day 3), and Python does not complain: * with a string and an int repeats the string (Day 3), so the “total cost” is the text 2.52.52.52.5. A docstring (Day 9) could say “price is a number”, but a sentence in English is easy to skip and impossible for a tool to check.

Day 17 showed a better way to say it. In a data class, x: int noted that the field x is meant to hold an int. That note was a type annotation. You can write the same kind of note on a function’s parameters and on its result. When an annotation states a type, it is called a type hint: a hint to the reader (and to tools) about what kind of value belongs there.

The syntax has two parts:

• A parameter hint goes after the parameter’s name: a colon, a space, then the type, as in price: float.
• A return hint goes after the closing parenthesis of the parameter list: a space, an arrow -> (a minus sign and a greater-than sign), a space, then the type of the value the function returns, and then the usual colon that ends the def line.

def line_total(price: float, quantity: int = 1) -> float:
    """Return the cost of quantity items at price each."""
    return price * quantity


def print_line(item: str, price: float, quantity: int = 1) -> None:
    """Print one receipt line, such as '4 x pens: 10.00'."""
    print(f"{quantity} x {item}: {line_total(price, quantity):.2f}")


print_line("pens", 2.5, 4)
print_line("ruler", 1.75)
help(line_total)

4 x pens: 10.00
1 x ruler: 1.75
Help on function line_total in module __main__:

line_total(price: float, quantity: int = 1) -> float
    Return the cost of quantity items at price each.

Notice the spaces in quantity: int = 1. On Day 10 you wrote defaults with no spaces, quantity=1. Once there is a hint, Python’s style guide puts a space on each side of the =, so the hint and the default are easy to tell apart. There is no space before the colon and one after it, and one space on each side of ->.

Now the most important fact about hints. Change the function to have hints, and call it with the wrong types again:

def line_total(price: float, quantity: int = 1) -> float:
    """Return the cost of quantity items at price each."""
    return price * quantity


print(line_total(2.5, 4))
print(line_total("2.5", 4))
print(line_total([0], 3))

10.0
2.52.52.52.5
[0, 0, 0]

The hints did not stop anything. Python does not check type hints when it runs your program. They are stored with the function (that is how help() found them), and otherwise ignored, exactly like the data class fields on Day 17 that accepted Point("two", "three"). Python works this way on purpose: hints were added to the language long after it was created, and checking every argument on every call would slow every program down. So who reads the hints? People, your editor, which can suggest and warn as you type, and a type checker, a separate tool that you will run in 19.4.

def line_total(price=float, quantity=int):
    """Return the cost of quantity items at price each."""
    return price * quantity


print(line_total(2.5, 4))
print(line_total(2.5))

10.0
Traceback (most recent call last):
  File ".../day19/equals_not_colon.py", line 7, in <module>
    print(line_total(2.5))
          ~~~~~~~~~~^^^^^
  File ".../day19/equals_not_colon.py", line 3, in line_total
    return price * quantity
           ~~~~~~^~~~~~~~~~
TypeError: unsupported operand type(s) for *: 'float' and 'type'

def repeat(word: str, times: int) -> str:
    return word * times


def half(number: int) -> int:
    return number / 2


print(repeat("ha", 3))
print(repeat(3, 2))
print(half(7))

hahaha
6
3.5

A hint of list tells a reader that a parameter is a list, but a list of what? Scores, names, tasks? A function that averages scores needs numbers in its list, and a dictionary could map anything to anything. Hints can say what goes inside a collection too, by putting the inner types in square brackets after the collection’s type:

A list or a set takes one inner type, because every item is meant to be the same kind of thing. A dictionary takes two: the key type, then the value type. A tuple is different: it lists a type for each position, because a tuple usually holds a fixed number of values with different meanings (Day 7), like a name and a score. Read a nested hint from the outside in: dict[str, list[int]] is “a dictionary whose keys are strings and whose values are lists of ints”.

def count_words(text: str) -> dict[str, int]:
    """Return how many times each word appears in text."""
    counts: dict[str, int] = {}
    for word in text.lower().split():
        counts[word] = counts.get(word, 0) + 1
    return counts


def most_common(counts: dict[str, int]) -> tuple[str, int]:
    """Return the most common word and its count."""
    best_word = ""
    best_count = 0
    for word, count in counts.items():
        if count > best_count:
            best_word, best_count = word, count
    return best_word, best_count


counts = count_words("The cat saw the dog and the dog saw the cat")
print(counts)
word, count = most_common(counts)
print(f"{word} appears {count} times")

{'the': 4, 'cat': 2, 'saw': 2, 'dog': 2, 'and': 1}
the appears 4 times

Hints can nest as deep as the data does. Here a gradebook maps each student to a list of scores:

def averages(grades: dict[str, list[int]]) -> dict[str, float]:
    """Return each student's average grade, rounded to 1 decimal place."""
    result: dict[str, float] = {}
    for name, scores in grades.items():
        result[name] = round(sum(scores) / len(scores), 1)
    return result


def top_students(results: dict[str, float], limit: float) -> list[str]:
    """Return the names of students whose average is at least limit."""
    return [name for name, average in results.items() if average >= limit]


grades = {"Ana": [90, 85, 88], "Ben": [72, 80], "Cy": [95, 91, 99]}
results = averages(grades)
print(results)
print(top_students(results, 85))

{'Ana': 87.7, 'Ben': 76.0, 'Cy': 95.0}
['Ana', 'Cy']

Each function’s first line now tells you the shape of the data it expects and returns: averages turns dict[str, list[int]] (names to lists of scores) into dict[str, float] (names to one average each), and top_students returns list[str], a list of names. Ana’s average is (90 + 85 + 88) / 3 = 87.67, rounded to 87.7, and Cy’s is 95.0; both reach the limit of 85, Ben’s 76.0 does not.

Any class can be a type in a hint, including your own. If Task is the data class from Day 17, then tasks: list[Task] means “a list of Task objects”, and -> Task means the function returns one. You will hint the whole to-do manager this way in today’s practice.

You may also meet older code that writes List[int] and Dict[str, int], with capital letters, imported from the standard library’s typing module (from typing import List, Dict). Python versions before 3.9 needed those. They mean the same thing; write the lowercase built-in forms in new code.

def cheapest(prices: dict[str, float]) -> str:
def split_name(full_name: str) -> tuple[str, str]:
def grid(rows: int, columns: int) -> list[list[int]]:

Many functions you have written return a value or None. Day 8’s get() returns None for a missing key, and the to-do manager’s complete_task (Day 17) returns the Task it changed, or None if the task number does not exist. What is the return hint for “a float, or None if the item is not found”? -> float would be a lie, and a caller who believed it would use the result as a number without checking.

Python writes “one type or another” with the | symbol, read as “or”. It is the same symbol that joined two sets on Day 7, here joining two types. A hint such as int | str (an int or a string) is called a union type, and the most common union by far is X | None: “a value of type X, or None”.

def find_price(prices: dict[str, float], item: str) -> float | None:
    """Return the price of item, or None if the shop does not sell it."""
    return prices.get(item)


prices = {"apple": 0.5, "bread": 2.25}
for item in ["bread", "milk"]:
    price = find_price(prices, item)
    if price is None:
        print(f"Sorry, we do not sell {item}.")
    else:
        print(f"Three {item}: {price * 3:.2f}")

Three bread: 6.75
Sorry, we do not sell milk.

The same idea works for parameters. A parameter whose default is None (Day 10 used this to avoid the shared-list trap) has the hint X | None, with the default after it. And a union does not have to include None:

def greeting(name: str | None = None) -> str:
    """Return a greeting for name, or for everyone if no name is given."""
    if name is None:
        return "Hello, everyone!"
    return f"Hello, {name}!"


def seat_label(seat: int | str) -> str:
    """Return a label for a seat given as a number (12) or a code ("12B")."""
    return f"Seat {seat}"


print(greeting())
print(greeting("Ana"))
print(seat_label(12), seat_label("12B"))

Hello, everyone!
Hello, Ana!
Seat 12 Seat 12B

name: str | None = None says that name is a string, or None, and is None when left out; line 3 handles that case first. seat: int | str accepts a seat number like 12 or a code like "12B"; the f-string works for both. Unions of unrelated types are less common than X | None, because a function that accepts many types has to handle each one, but they are sometimes exactly right.

The | form needs Python 3.10 or newer. In older code you will see the same hints written with names from the typing module: Optional[float] means float | None, and Union[int, str] means int | str.

def find_price(prices: dict[str, float], item: str) -> float | None:
    """Return the price of item, or None if the shop does not sell it."""
    return prices.get(item)


prices = {"apple": 0.5, "bread": 2.25}
for item in ["bread", "milk"]:
    price = find_price(prices, item)
    print(f"Three {item}: {price * 3:.2f}")

Three bread: 6.75
Traceback (most recent call last):
  File ".../day19/none_crash.py", line 9, in <module>
    print(f"Three {item}: {price * 3:.2f}")
                           ~~~~~~^~~
TypeError: unsupported operand type(s) for *: 'NoneType' and 'int'

def first_long_word(words: list[str], length: int) -> str | None:
    for word in words:
        if len(word) >= length:
            return word
    return None


words = ["fig", "plum", "banana"]
for length in [4, 6, 7]:
    found = first_long_word(words, length)
    if found is None:
        print(length, "none")
    else:
        print(length, found.upper())

4 PLUM
6 BANANA
7 none

Hints are only notes until something reads them. Here is a short program whose hints are right but whose code is wrong in two places. It runs without a single error:

def label(item: str, quantity: int) -> str:
    """Return a label such as '3 x pens'."""
    return f"{quantity} x {item}"


def total_items(basket: dict[str, int]) -> int:
    """Return how many items are in the basket altogether."""
    total = 0
    for quantity in basket.values():
        total += quantity
    return f"{total} items"


basket = {"pens": 3, "pads": 2}
print(label(3, "pens"))
print(total_items(basket))

pens x 3
5 items

Both lines are wrong. Line 15 passes the arguments in the wrong order, so the label is backwards. Line 11 returns a string, although the hint promises an int; the output looks fine today, but the first caller that does arithmetic with the result, such as total_items(basket) + 1, will crash. Running a program only tests the lines and values that happen to run. A bug in a rarely used branch can wait months for the day it runs.

A type checker is a program that reads your code without running it and reports every place where the values do not match the hints. Checking code by reading it, without running it, is called static analysis (“static” because the program stands still). The two most widely used type checkers for Python are mypy and pyright. Both are third-party tools: they are not part of Python, and you install them with pip (Day 13), ideally into the project’s virtual environment. You only need one; they find the same kinds of mistakes.

python -m pip install mypy
mypy checkout.py

or

python -m pip install pyright
pyright checkout.py

Type the second line of each pair in the terminal, in the folder holding the file. Use mypy . (or pyright .) to check every .py file in the current folder and the folders inside it; the dot means “this folder”. Your editor can show the same complaints as you type: VS Code’s Python extension includes Pylance, which is built on pyright, and underlines mismatches once its type checking setting is turned on.

checkout.py:11: error: Incompatible return value type (got "str", expected "int")  [return-value]
checkout.py:15: error: Argument 1 to "label" has incompatible type "int"; expected "str"  [arg-type]
checkout.py:15: error: Argument 2 to "label" has incompatible type "str"; expected "int"  [arg-type]
Found 3 errors in 1 file (checked 1 source file)

def label(item: str, quantity: int) -> str:
    """Return a label such as '3 x pens'."""
    return f"{quantity} x {item}"


def total_items(basket: dict[str, int]) -> int:
    """Return how many items are in the basket altogether."""
    total = 0
    for quantity in basket.values():
        total += quantity
    return total


basket = {"pens": 3, "pads": 2}
print(label("pens", 3))
print(f"{total_items(basket)} items")

3 x pens
5 items

Success: no issues found in 1 source file

A few things to know about how type checkers behave:

• They can only check what is hinted. mypy, by default, does not check the inside of a function that has no hints at all, so an unhinted function is invisible to it. Hint every function’s parameters and return value; that is also today’s first practice exercise.
• An int is accepted where a float is expected. A whole number is a perfectly good price, so line_total(2, 3) passes a check even though the hint says price: float. The reverse is not true: a float where an int is expected is reported.
• A complaint is a question, not a verdict. Usually it is a real bug. Sometimes the code is right and the hint is wrong, for example -> int on a function that really should return a string. Then fix the hint. Either way, the hint and the code end up agreeing.
• Checking does not replace running. A type checker proves that the types fit, not that the answers are right: return price + quantity instead of * has perfectly good types. Day 20’s tests check the answers.

from dataclasses import dataclass


@dataclass
class Task:
    title: str
    done: bool = False


def find_task(tasks: list[Task], title: str) -> Task | None:
    """Return the task with this title, or None if there is none."""
    for task in tasks:
        if task.title == title:
            return task
    return None


tasks = [Task("Practice piano"), Task("Water plants")]
task = find_task(tasks, "Water plants")
print(task.done)

False

find_task_unchecked.py:20: error: Item "None" of "Task | None" has no attribute "done"  [union-attr]

from dataclasses import dataclass


@dataclass
class Task:
    title: str
    done: bool = False


def find_task(tasks: list[Task], title: str) -> Task | None:
    """Return the task with this title, or None if there is none."""
    for task in tasks:
        if task.title == title:
            return task
    return None


tasks = [Task("Practice piano"), Task("Water plants")]
for title in ["Water plants", "Swim"]:
    task = find_task(tasks, title)
    if task is None:
        print(f"No task called {title}")
    else:
        print(task.done)

False
No task called Swim

def area(width: float, height: float) -> float:
    return width * height


def describe(name: str, size: float) -> str:
    return f"{name}: {size} square meters"


print(describe("kitchen", area(3, 4)))
print(describe(area(2.5, 4), "hall"))

Python accepts both of these programs, and both print the same line. Which would you rather read?

MaxScore=100
def Percent(Score,outOf = MaxScore):
    return round(Score/outOf*100 ,1)
class student_record:
    def __init__( self,name,score ):
        self.name=name
        self.score=score
    def summary(self):
        return f"{self.name}: {Percent(self.score)}%"
print(student_record ('Ana',87).summary())

MAX_SCORE = 100


def percent(score, out_of=MAX_SCORE):
    return round(score / out_of * 100, 1)


class StudentRecord:
    def __init__(self, name, score):
        self.name = name
        self.score = score

    def summary(self):
        return f"{self.name}: {percent(self.score)}%"


print(StudentRecord("Ana", 87).summary())

Ana: 87.0%

The first one makes you work. Is Percent a class or a function? Is student_record a variable? Where does one definition end and the next begin? None of this matters to Python, but all of it matters to the people who read the code. A program is read many more times than it is written, so the Python community agreed on one shared set of style rules. Once everyone follows them, any Python file looks familiar and the reader can concentrate on what the code does.

Changes to Python are proposed in numbered documents called PEPs (Python Enhancement Proposals). PEP 8 is the official style guide for Python code; you met a few of its rules on Days 9 and 10. Its main naming and whitespace rules are below. Each one has the same reason behind it: code is easier to read when the shape of a line tells you what it is.

Naming

Because the styles differ, a name tells you what it is at a glance: StudentRecord(...) makes an object, percent(...) calls a function, and MAX_SCORE should never be reassigned. Two more rules: never use l (lowercase L), O (capital o), or I (capital i) as a one-letter name, because in many fonts they look like the digits 1 and 0; and choose names that say what a value means (score, not s).

Whitespace

PEP 8 also warns against following it blindly. Its first section is titled “A Foolish Consistency is the Hobgoblin of Little Minds”: consistency within one project matters more than any single rule, and a rule can be broken when following it would make a particular line harder to read. When you join an existing project, follow the style it already uses.

list = ["milk", "eggs", "bread"]
print(len(list), "items")
letters = list("abc")
print(letters)

3 items
Traceback (most recent call last):
  File ".../day19/shadow_list.py", line 3, in <module>
    letters = list("abc")
TypeError: 'list' object is not callable

def AddBonus( points,bonus = 10 ):
    Total=points+bonus
    return Total

def add_bonus(points, bonus=10):
    total = points + bonus
    return total

Two more groups of rules decide how a file looks from a distance: how long its lines are, and how its imports are arranged at the top.

Line length

PEP 8 limits lines to 79 characters (and comments and docstrings to 72). Short lines let you put two files side by side, read code in a narrow window or on a phone, and compare two versions of a file without scrolling sideways. Many teams relax the limit to 88 characters, which is what the formatters in 19.7 use by default. Whichever limit your project chooses, long lines need a way to break.

A line of Python normally ends where the line ends. But inside parentheses, square brackets, or curly braces, a statement can continue onto the next line, because Python knows the statement is not finished until the bracket closes. This is called implicit line continuation. You have already seen it in Day 17’s main.py, where one from tasks import (...) statement ran over several lines.

def can_ship(weight_kg: float, length_cm: float, country: str) -> bool:
    """Return True if a parcel meets every shipping rule."""
    return (
        weight_kg <= 20
        and length_cm <= 120
        and country in ["Canada", "Mexico", "United States"]
    )


parcels = [
    ("books", 4.2, 35, "Canada"),
    ("bike", 14.0, 150, "Mexico"),
]
for name, weight_kg, length_cm, country in parcels:
    allowed = can_ship(weight_kg, length_cm, country)
    print(
        f"{name}: {weight_kg} kg, {length_cm} cm to {country}",
        "- OK" if allowed else "- too big or too heavy",
    )

books: 4.2 kg, 35 cm to Canada - OK
bike: 14.0 kg, 150 cm to Mexico - too big or too heavy

Imports

PEP 8’s rules for import statements (Day 13) are:

1. Put all imports at the top of the file, after the module’s docstring and before anything else, so a reader sees at once what the file depends on.
2. Put one module per import line: import json and import os on separate lines, not import json, os. Importing several names from one module, from tasks import add_task, list_tasks, is fine.
3. Arrange imports in three groups, with a blank line between groups: the standard library first, then third-party packages (installed with pip), then your own modules. Many teams also sort each group alphabetically.
4. Avoid from module import * (Day 13): it hides where names come from.

"""Fetch the weather and save a daily report."""

import json
from datetime import date
from pathlib import Path

import requests

from report import format_report

json, datetime, and pathlib are in the standard library; requests is the third-party package from Day 13 (it is not installed here, so this block is for reading only); report is a module of your own. Seeing the groups, a reader knows at once that this program needs requests installed.

price = 19.99
tax = 1.60
shipping = 4.50
total = price + tax +
    shipping
print(f"{total:.2f}")

  File ".../day19/broken_line.py", line 4
    total = price + tax +
                         ^
SyntaxError: invalid syntax

price = 19.99
tax = 1.60
shipping = 4.50
total = (
    price
    + tax
    + shipping
)
print(f"{total:.2f}")

26.09

def on_honor_roll(average: float, attendance: float, late_days: int) -> bool:
    """Return True if a student qualifies for the honor roll."""
    return average >= 90 and attendance >= 0.95
        and late_days <= 3


print(on_honor_roll(93.5, 0.97, 1))

IndentationError: unexpected indent

def on_honor_roll(average: float, attendance: float, late_days: int) -> bool:
    """Return True if a student qualifies for the honor roll."""
    return (
        average >= 90
        and attendance >= 0.95
        and late_days <= 3
    )


print(on_honor_roll(93.5, 0.97, 1))
print(on_honor_roll(93.5, 0.97, 5))

True
False

You could tidy every file by hand with the tables from 19.5 and 19.6, but nobody wants to count spaces, and people miss things. Programmers hand that job to tools, so the people can argue about what the code does instead of where the spaces go. There are two kinds:

• A formatter rewrites the layout of your code automatically: spaces, blank lines, quotes, and line breaks. It never changes what the code does. The best-known Python formatters are black and ruff’s formatter, which produce almost identical results.
• A linter reads your code and reports likely bugs and style problems, without changing anything unless you ask. (The name comes from an old tool called lint, which picked little bits of fluff out of programs.) ruff is a fast, popular linter; older ones include flake8 and pylint.

ruff does both jobs in one tool. Like the type checkers, these are third-party tools that you install with pip, ideally into the project’s virtual environment, and run in the terminal:

python -m pip install ruff

ruff format .
ruff format --check .
ruff check .
ruff check --fix .

If you prefer black, python -m pip install black installs it and black . reformats every file (black --check . only reports). Black is only a formatter, so pair it with a linter.

MaxScore = 100


def Percent(Score, outOf=MaxScore):
    return round(Score / outOf * 100, 1)


class student_record:
    def __init__(self, name, score):
        self.name = name
        self.score = score

    def summary(self):
        return f"{self.name}: {Percent(self.score)}%"


print(student_record("Ana", 87).summary())

Ana: 87.0%

import json


def find_task(tasks, title):
    """Return the task with this title, or None if there is none."""
    count = 0
    for task in tasks:
        if task["title"] == title:
            return task
    return None


tasks = [{"title": "Practice piano", "done": False}]
if find_task(tasks, "Swim") == None:
    print("No task called Swim")

No task called Swim

lint_me.py:1:8: F401 [*] `json` imported but unused
lint_me.py:6:5: F841 Local variable `count` is assigned to but never used
Found 2 errors.
[*] 1 fixable with `--fix` (1 unsafe fix available with `--fix --unsafe-fixes`).

lint_me.py:14:32: E711 Comparison to `None` should be `cond is None`

Type hints now say what type each value is. A reader can still have questions that no hint answers. Is the price in dollars or cents? Can people be 0? What happens if it is? Does the result include the tip? Docstrings (Day 9) and comments (Day 1) are where you answer those questions, and the best ones answer exactly what the code cannot say for itself.

Docstrings

A docstring is for someone using the function. Day 9 gave it a one-line summary; a useful docstring follows a few more conventions from PEP 257, the PEP about docstrings:

• The first line is a one-sentence summary that ends with a period and is written as a command: “Return the share…”, not “This function returns the share…”.
• For a function whose parameters need explaining, a blank line follows, then the details: what each parameter means (units, allowed values), what is returned, including any None case, and which exceptions it raises (Day 15).
• It does not repeat the hints. total: float already says it is a float; the docstring says it is the whole bill, in dollars, with the tip included.

def split_bill(total: float, people: int = 2) -> float:
    """Return each person's share of a bill, rounded to cents.

    Args:
        total: The whole bill in dollars, tip included.
        people: How many people share it. Must be at least 1.

    Returns:
        One person's share, rounded to 2 decimal places.

    Raises:
        ValueError: If people is less than 1.
    """
    if people < 1:
        raise ValueError(f"people must be at least 1, not {people}")
    return round(total / people, 2)


print(split_bill(85.0, 3))
help(split_bill)

28.33
Help on function split_bill in module __main__:

split_bill(total: float, people: int = 2) -> float
    Return each person's share of a bill, rounded to cents.

    Args:
        total: The whole bill in dollars, tip included.
        people: How many people share it. Must be at least 1.

    Returns:
        One person's share, rounded to 2 decimal places.

    Raises:
        ValueError: If people is less than 1.

A one-line docstring is enough when the name, the hints, and one sentence say it all, as in most of today’s examples. Write the longer form when a caller would otherwise have to read the body.

Comments

A comment is for someone reading the code, usually someone about to change it. The code already says what it does; a good comment says why: a reason, a rule from outside the program, or a trap the next person might fall into.

TAX_RATE = 0.0825  # 6.25% state tax plus 2% city tax.


def price_with_tax(price: float) -> float:
    """Return price with sales tax added, rounded to cents."""
    # Round once, at the end: rounding the tax and the price separately
    # can leave the total a cent out.
    return round(price * (1 + TAX_RATE), 2)


def task_title(tasks: list[str], number: int) -> str:
    """Return the title of task number, counting from 1."""
    # People number tasks from 1, but list indexes start at 0.
    return tasks[number - 1]


print(price_with_tax(19.99))
print(task_title(["Practice piano", "Water plants"], 2))

21.64
Water plants

Each comment here tells the reader something the code cannot. Line 1’s comment explains where the odd number 0.0825 comes from. PEP 8 puts an inline comment (one on the same line as code) at least two spaces after the code, with one space after the #. Lines 6 and 7 are a block comment, on their own lines above the code they explain, indented to match it; they warn the next person not to “improve” the code by rounding twice. Line 13 explains the - 1 that would otherwise look like a bug. Compare comments that only repeat the code:

count = count + 1  # add 1 to count
for task in tasks:  # loop over the tasks

These cost reading time and tell the reader nothing new. Leave them out. If a line needs a comment to say what it does, first try a clearer name: seconds_per_day = 86400 needs no comment, where n = 86400 # seconds in a day does.

TAX_RATE = 0.0825  # 6% state tax.

def pace(distance: float, minutes: float) -> float:
    """This function takes a float and a float and returns a float."""
    return minutes / distance

def pace(distance: float, minutes: float) -> float:
    """Return a running pace in minutes per kilometer.

    Args:
        distance: How far the run was, in kilometers. Must not be 0.
        minutes: How long the run took, in minutes.

    Returns:
        The minutes taken for each kilometer.
    """
    return minutes / distance

A reader keeps a log of the books they finish, with an optional rating from 1 to 5. The program below uses every idea from today: hints on every function, a field and a return value that might be None, nested collection hints, PEP 8 names and layout, and docstrings and a comment that answer the reader’s questions.

"""Keep a log of finished books and report on a reader's progress."""

from dataclasses import dataclass

PAGE_GOAL = 1000


@dataclass
class Book:
    """One finished book. rating is None until the reader rates it."""

    title: str
    pages: int
    rating: int | None = None


def total_pages(books: list[Book]) -> int:
    """Return the number of pages read across all books."""
    return sum(book.pages for book in books)


def average_rating(books: list[Book]) -> float | None:
    """Return the average rating of the rated books.

    Returns None when no book has a rating yet, because an average of
    no numbers has no sensible value (and would divide by zero).
    """
    ratings = [book.rating for book in books if book.rating is not None]
    if not ratings:
        return None
    return sum(ratings) / len(ratings)


def titles_by_rating(books: list[Book]) -> dict[int, list[str]]:
    """Group the titles of rated books by their rating."""
    groups: dict[int, list[str]] = {}
    for book in books:
        if book.rating is None:
            continue
        if book.rating not in groups:
            groups[book.rating] = []
        groups[book.rating].append(book.title)
    return groups


def report(books: list[Book]) -> None:
    """Print a short progress report for a list of finished books."""
    pages = total_pages(books)
    print(f"Pages read: {pages} of {PAGE_GOAL}")
    average = average_rating(books)
    if average is None:
        print("No ratings yet")
    else:
        print(f"Average rating: {average:.1f}")
    groups = titles_by_rating(books)
    for rating in sorted(groups, reverse=True):
        titles = groups[rating]
        print(f"{rating} stars: {', '.join(titles)}")


log = [
    Book("The Hobbit", 310, 5),
    Book("Holes", 233, 4),
    Book("Wonder", 316),
    Book("Matilda", 240, 5),
]
report(log)
print()
report([Book("Coraline", 162)])

Pages read: 1099 of 1000
Average rating: 4.7
5 stars: The Hobbit, Matilda
4 stars: Holes

Pages read: 162 of 1000
No ratings yet

Follow the first report. total_pages adds 310 + 233 + 316 + 240 = 1099. average_rating collects only the ratings that are not None: 5, 4, and 5 (Wonder has no rating), so the average is 14 / 3 = 4.67, shown as 4.7. titles_by_rating skips Wonder and builds {5: ["The Hobbit", "Matilda"], 4: ["Holes"]}, and report prints the ratings from highest to lowest. In the second report, Coraline has no rating, so ratings is empty and average_rating returns None instead of dividing by zero; report checks for it on line 51 and prints No ratings yet. A type checker run on this file finds nothing to report, and a formatter would leave it unchanged, because it already follows the style that formatters produce.

Today’s tools report problems by message and code. Use this table to go from a report to its usual cause. Messages from the tools are samples; their wording varies by version.

Older versions of Python may word the Python messages differently.

• A type hint says what type a value should have: name: type on parameters and variables, -> type for the return value, with -> None when nothing is returned. Python stores hints but never checks them when the program runs.
• Collection hints name the inner types: list[int], set[str], dict[str, int] (keys, then values), tuple[str, int] (one type per position), nested as deep as the data. X | None means “an X, or None”, and the caller should check is None before using the value.
• A type checker such as mypy or pyright reads hinted code without running it and reports mismatches, with the line, the type found, and the type expected, so it finds bugs in lines that have not run yet.
• PEP 8 is the shared style guide: snake_case for functions and variables, CapWords for classes, UPPER_CASE for constants, single spaces around operators, 79-character lines broken inside brackets, and grouped imports at the top.
• A formatter (ruff format, black) applies the layout rules for you; a linter (ruff check) reports likely bugs and style problems. A docstring tells a caller what a function does, means, returns, and raises; a comment tells a reader why.

Do these in your day19 folder. Type each program yourself, run it, and only then open the answer. Questions 18 and 19 use ruff and mypy (or pyright); install them first, as shown in 19.7 and 19.4.

"""The Task class for the to-do manager, written as a data class."""

from dataclasses import asdict, dataclass


@dataclass
class Task:
    """One thing to do: a title, and whether it is done yet."""

    title: str
    done: bool = False

    def complete(self) -> None:
        """Mark this task as done."""
        self.done = True

    def to_dict(self) -> dict[str, str | bool]:
        """Return this task as a dictionary, ready to save as JSON."""
        return asdict(self)

    def __str__(self) -> str:
        mark = "x" if self.done else " "
        return f"[{mark}] {self.title}"


if __name__ == "__main__":
    task = Task("Test the class")
    print(repr(task))
    task.complete()
    print(task)
    print(task.to_dict())
    print(task == Task("Test the class", True))

Task(title='Test the class', done=False)
[x] Test the class
{'title': 'Test the class', 'done': True}
True

"""Task functions for the to-do manager. main.py imports them."""

import json
from pathlib import Path

from task import Task


def show_menu() -> None:
    """Print the menu of choices."""
    print()
    print("1) Add  2) List  3) Complete  4) Delete  5) Quit")


def add_task(tasks: list[Task], title: str) -> None:
    """Add a new, unfinished Task to the end of tasks."""
    tasks.append(Task(title))


def list_tasks(tasks: list[Task]) -> None:
    """Print every task with its number, using Task.__str__."""
    if not tasks:
        print("No tasks yet.")
        return
    for number, task in enumerate(tasks, 1):
        print(f"{number}. {task}")


def complete_task(tasks: list[Task], number: int) -> Task | None:
    """Mark task number (counting from 1) as done.

    Return the Task, or None if no task has that number.
    """
    if not 1 <= number <= len(tasks):
        return None
    task = tasks[number - 1]
    task.complete()
    return task


def delete_task(tasks: list[Task], number: int) -> Task | None:
    """Remove task number (counting from 1) from tasks.

    Return the removed Task, or None if no task has that number.
    """
    if not 1 <= number <= len(tasks):
        return None
    return tasks.pop(number - 1)


def save_tasks(tasks: list[Task], path: Path) -> None:
    """Write tasks to the JSON file at path, replacing what was there."""
    data = [task.to_dict() for task in tasks]
    with path.open("w", encoding="utf-8") as file:
        json.dump(data, file, indent=2)


def load_tasks(path: Path) -> list[Task]:
    """Return the Tasks saved at path, or [] if there are none to load.

    A missing file means this is the first run. A file that is not valid
    JSON gets a warning, and the program starts with no tasks.
    """
    try:
        with path.open(encoding="utf-8") as file:
            data = json.load(file)
    except FileNotFoundError:
        return []
    except json.JSONDecodeError:
        print(f"Warning: {path.name} is not valid JSON, so no tasks loaded.")
        return []
    return [Task(**item) for item in data]


if __name__ == "__main__":
    test_tasks: list[Task] = []
    add_task(test_tasks, "Test the module")
    task = complete_task(test_tasks, 1)
    print(task is not None and task.done)
    print(complete_task(test_tasks, 2))
    list_tasks(test_tasks)

True
None
1. [x] Test the module

import json, os
def addTask(tasks,title):
    tasks.append({"title":title,"done":False})
def countDone(tasks):
    total=0
    done = 0
    for t in tasks:
        if t['done']==True: done+=1
    return done
tasks=[]
addTask(tasks,'Practice piano')
addTask(tasks,'Water plants')
tasks[0]['done']=True
print(countDone(tasks),'of',len(tasks),'done')

todo_messy.py:1:1: I001 [*] Import block is un-sorted or un-formatted
todo_messy.py:1:8: F401 [*] `json` imported but unused
todo_messy.py:1:14: F401 [*] `os` imported but unused
todo_messy.py:5:5: F841 Local variable `total` is assigned to but never used
Found 4 errors.
[*] 3 fixable with `--fix` (1 unsafe fix available with `--fix --unsafe-fixes`).

def add_task(tasks, title):
    """Add a new, unfinished task to the end of tasks."""
    tasks.append({"title": title, "done": False})


def count_done(tasks):
    """Return how many tasks are done."""
    done = 0
    for task in tasks:
        if task["done"]:
            done += 1
    return done


tasks = []
add_task(tasks, "Practice piano")
add_task(tasks, "Water plants")
tasks[0]["done"] = True
print(count_done(tasks), "of", len(tasks), "done")

1 of 2 done

from dataclasses import dataclass


@dataclass
class Task:
    title: str
    done: bool = False


def add_task(tasks: list[Task], title: str) -> None:
    tasks.append(Task(title))


def complete_task(tasks: list[Task], number: int) -> Task:
    if not 1 <= number <= len(tasks):
        return None
    task = tasks[number - 1]
    task.done = True
    return task


def find_task(tasks: list[Task], title: str) -> Task | None:
    for task in tasks:
        if task.title == title:
            return task
    return None


tasks: list[Task] = []
add_task(tasks, "Practice piano")
add_task(tasks, Task("Water plants"))
complete_task(tasks, 1)
print(find_task(tasks, "Practice piano").done)
print(tasks[1])

True
Task(title=Task(title='Water plants', done=False), done=False)

todo_check.py:16: error: Incompatible return value type (got "None", expected "Task")  [return-value]
todo_check.py:31: error: Argument 2 to "add_task" has incompatible type "Task"; expected "str"  [arg-type]
todo_check.py:33: error: Item "None" of "Task | None" has no attribute "done"  [union-attr]
Found 3 errors in 1 file (checked 1 source file)

from dataclasses import dataclass


@dataclass
class Task:
    title: str
    done: bool = False


def add_task(tasks: list[Task], title: str) -> None:
    tasks.append(Task(title))


def complete_task(tasks: list[Task], number: int) -> Task | None:
    if not 1 <= number <= len(tasks):
        return None
    task = tasks[number - 1]
    task.done = True
    return task


def find_task(tasks: list[Task], title: str) -> Task | None:
    for task in tasks:
        if task.title == title:
            return task
    return None


tasks: list[Task] = []
add_task(tasks, "Practice piano")
add_task(tasks, "Water plants")
complete_task(tasks, 1)
task = find_task(tasks, "Practice piano")
if task is not None:
    print(task.done)
print(tasks[1])

True
Task(title='Water plants', done=False)

def average(scores: list[int]) -> float | None:
    """Return the average of scores, or None if there are no scores."""
    if not scores:
        return None
    return sum(scores) / len(scores)


for scores in [[80, 95, 90], []]:
    print(round(average(scores), 1))

TypeError: type NoneType doesn't define __round__ method

def average(scores: list[int]) -> float | None:
    """Return the average of scores, or None if there are no scores."""
    if not scores:
        return None
    return sum(scores) / len(scores)


for scores in [[80, 95, 90], []]:
    result = average(scores)
    if result is None:
        print("no scores")
    else:
        print(round(result, 1))

88.3
no scores

from dataclasses import dataclass


@dataclass
class Player:
    name: str
    points: int = 0
    team: str | None = None

    def label(self) -> str:
        if self.team is None:
            return f"{self.name} ({self.points})"
        return f"{self.name} of {self.team} ({self.points})"


def leader(players: list[Player]) -> Player | None:
    best: Player | None = None
    for player in players:
        if best is None or player.points > best.points:
            best = player
    return best


players = [Player("Ana", 12, "Owls"), Player("Ben", 15), Player("Cy", "9")]
print(players[2].points * 2)
top = leader(players[:2])
if top is not None:
    print(top.label())
print(leader([]))

99
Ben (15)
None

PEP 8 itself is worth skimming: PEP 8: Style Guide for Python Code explains the reason behind each rule, with many short examples. The typing module documentation introduces the hint tools beyond today’s, for when you meet them in other people’s code.

Check each statement. If the answer is “not yet,” reread the linked subsection.

• I can add type hints to parameters and return values, including -> None, and explain that Python does not check them. Reread
• I can write hints such as list[int], dict[str, int], and tuple[str, int], and annotate a variable that starts empty. Reread
• I can use X | None for a value that might be None, and check it with is None before using it. Reread
• I can run mypy or pyright, read what it reports, and fix the code or the hint. Reread
• I can name variables, functions, classes, and constants the PEP 8 way, and space code the PEP 8 way. Reread
• I can break a long line inside brackets, and arrange imports in PEP 8 order. Reread
• I can run a formatter and a linter, and explain what each one does and does not change. Reread
• I can write a docstring that tells a caller what they need, and comments that explain why. Reread