Overview — Python 2 to 3 Migration Kit

A pragmatic kit for the migration nobody wants but many still face: moving a Python

2 codebase (or a legacy Python 3.4/3.6 one) to modern Python 3.11+. It's the map an

agent or engineer needs to do it incrementally and safely, not with a big-bang

rewrite that breaks everything at once.

The strategy: run on both, then drop 2

Big-bang migrations fail. This kit uses the proven incremental path:

1. Get to a 2and3 state — code that runs under both Python 2.7 and 3 using

__future__, six, and modernized idioms. Ship this; nothing breaks.

2. Add CI on Python 3 alongside Python 2 — catch regressions per commit.

3. Flip the default runtime to 3; keep 2 in CI briefly as a safety net.

4. Drop Python 2 — remove six, __future__, and 2-only shims.

What's inside

• MIGRATION-GUIDE.md — the full incremental playbook with the order to do things.
• GOTCHAS.md — the bugs that bite: str/bytes, integer division, dict views,

print, iterators, relative imports, unicode, exception syntax, sorting.

• examples/before_after.py — 12 real before/after snippets of the common breakages.
• examples/strbytes_examples.py — the str/bytes boundary done right (the #1 source

of production bugs), runnable under Python 3.

• tools/checklist.md — per-module migration checklist + tooling (2to3, pyupgrade,

python-modernize, caniusepython3).

The single biggest trap: str vs bytes

In Python 2, str was bytes and "just worked" with text most of the time. In

Python 3 they're strictly separate. 80% of migration bugs are a str where bytes

are needed (or vice versa) — file I/O, sockets, hashing, subprocess, base64.

examples/strbytes_examples.py shows the correct patterns.

Requirements

Python 3.8+ to run the examples. The kit's advice applies to any 2→3 or legacy-3

modernization.