Writing Modern Python: An Idiom Upgrade

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Idiom

The usual, preferred way to write a common thing in a language.

Deprecated

Still works, but scheduled for removal; new code should not use it.

Backport

A package that brings a newer language feature to older Python versions.

`requires-python`

The setting in pyproject.toml saying which Python versions your project supports.

Free-threaded build

A Python build without the global interpreter lock, so threads can run Python code in parallel.

t-string

A template string (3.14) written t"..." that produces an object holding the pieces instead of finished text.

JIT

Just-in-time compiler: a part that turns frequently used code into machine code while the program runs.

Linter

A tool that reads code and flags or fixes style and likely mistakes.

1. 1

   Modernise an old function

   Take this old code and rewrite it with modern idioms: from typing import List, Optional, def total(items: List[int], default: Optional[int] = None) -> int: that returns default for an empty list. Use list[int], int | None and a conditional expression.

2. 2

   Catch a silent bug

   In the first example, change zip(..., strict=True) to plain zip and note that the error vanishes: the extra item is silently dropped. That is the bug strict=True exists to expose.

3. 3

   Check your project's age

   Look at a project you have, find the lowest Python version it supports (requires-python), and list three idioms from this topic that it could already use.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

import copy
from dataclasses import dataclass

@dataclass(frozen=True)
class Config:
    model: str

print(copy.replace(Config("small"), model="large"))

1. 1

   Text and paths. Use f-strings (f"Hi {name}", Topic 3.3) instead of % and .format(). Write f"{x=}" (3.8) to print the name and the value together. Use pathlib.Path and the / operator (Topic 7.6) instead of gluing strings together with os.path.join. Use removeprefix and removesuffix (3.9) instead of slicing by hand.

2. 2

   Data. Use a dataclass (Topic 8.8) with slots=True, kw_only=True (3.10) instead of a hand-written __init__ full of repeated lines. slots=True saves memory (Topic 8.12). kw_only=True means every argument must be given by name. Use StrEnum (3.11, Topic 8.9) when the members are strings.

3. 3

   Merge dictionaries with a | b (3.9) instead of {**a, **b}. Use list[int] and X | None (3.9, 3.10) instead of List[int] and Optional[X] (Topic 10.2).

4. 4

   Control flow. Use match (3.10, Topics 2.8 and 10.8) for shape-based branching. Use the walrus := (3.8, Topic 2.9) to compute a value once and use it. Use zip(..., strict=True) (3.10) so unequal lengths raise an error rather than silently dropping items. Use enumerate(items, start=1) (Topic 2.6) instead of adding 1 yourself.

5. 5

   Two helpers from itertools (Topic 9.4) arrived too: pairwise (3.10) gives neighbouring pairs and batched (3.12) gives chunks.

6. 6

   Errors and files. Several failures at once are carried by ExceptionGroup and handled with except* (3.11, Topic 7.3). It was born from asyncio.TaskGroup (Topic 12.7). Notes can be added to an exception with add_note (3.11). Read configuration files with tomllib (3.11, Topic 7.8).

7. 7

   Always pass encoding="utf-8" when opening text files (Topic 3.4 explains encodings). UTF-8 will become the default in Python 3.15.

8. 8

   Recent versions. 3.12 added the type statement, def f[T], @override, and nicer f-strings (you can reuse the same quote marks inside). 3.13 added a new coloured interactive shell, copy.replace and warnings.deprecated. It also added *experimental* free-threaded builds (Python without the global lock, Topic 12.2) and an experimental JIT (a part that turns hot code into machine code while the program runs).

9. 9

   3.14 added template strings (t-strings), lazily evaluated annotations, an officially supported free-threaded build, and except A, B: without brackets. Python 3.15 (released on 9 October 2026) makes UTF-8 the default text encoding and adds explicit lazy imports; check the release notes for the current state.

10. 10

    How to upgrade a codebase without breaking it. Know your minimum supported Python: the requires-python setting in pyproject.toml (Topic 6.7). Only use features from that version or older.

11. 11

    Let Ruff (a tool that finds and fixes style problems, Topic 11.6) modernise the code automatically. Its UP rules rewrite Optional[int] to int | None, List to list, .format to f-strings and more. Then run your tests (Topic 11.1) and type checker (Topic 10.3). That is what makes a mechanical upgrade safe.

• ↔

  Newest syntax versus reach. The newer the feature, the fewer environments run it. Your requires-python is the cap.

• ↔

  Rewriting versus leaving alone. Mechanical upgrades are cheap with a tool and tests; hand rewrites of working code carry risk for small gain.

• ↔

  Experimental builds. Free-threading and the JIT can bring speed, but are younger; adopt them deliberately, with measurements.

• Done when you can rewrite old string formatting, dict merging and type hints in modern style.

• Done when you can name what 3.9, 3.10, 3.11, 3.12 and 3.13 each added.

• Done when you can explain zip(strict=True) and the walrus operator.

• Done when you can set requires-python and a Ruff target and explain why.

• Done when you can explain what a t-string is and why it is safer than an f-string for SQL.