Upgrade syntax. Applies safe pyupgrade fixes and removes imports the rewrite left unused.
Upgrade Django code. Rewrites deprecated Django APIs up to the target release.
Run a custom codemod. Loads a team codemod module with -x and applies it across the tree.
Verify. Writes nothing and exits 0 only when no fixable changes remain.
## Where Droids take over in Python modernization
The deterministic pass ends with a residue that no rule covers. In a typical Python upgrade, that residue falls into a few recognizable groups.
Removed modules are the clearest case. Python 3.13 removed the "dead batteries" listed in PEP 594, including `cgi`, `telnetlib`, `crypt`, and `imghdr`. No rewrite rule can choose a replacement, because the right one depends on how the module was used. A Droid reads the call sites, picks a maintained alternative or a small local implementation, and adds tests for the behavior the old module provided.
Semantic choices are the second group. `datetime.utcnow()` has been deprecated since Python 3.12 and returns a naive datetime, while `datetime.now(UTC)` returns an aware one. Comparing the two raises `TypeError`, so a correct migration has to follow each value through serializers, database columns, and comparisons.
The third group is repair work. Changed annotations surface new mypy or pyright errors, Django upgrades break tests that relied on old defaults, and unsafe Ruff fixes need someone to confirm behavior is unchanged. A Droid can take each failure from the gate, fix it, and rerun the narrow command that failed.
The fourth is the most valuable. When the same change repeats across hundreds of files, the Droid should stop editing by hand and write a codemod. The codemod turns the pattern into something deterministic and reviewable, and it can be rerun after every rebase.
## Writing a LibCST codemod with tests
The [LibCST codemod tutorial](https://libcst.readthedocs.io/en/latest/codemods_tutorial.html) builds commands on `VisitorBasedCodemodCommand` and tests them with `CodemodTest`. The codemod below rewrites `datetime.utcnow()` calls and adds the `UTC` import. It runs under LibCST's matcher decorators, so it touches only exact matches.
```python title="codemods/replace_utcnow.py"
import libcst as cst
import libcst.matchers as m
from libcst.codemod import VisitorBasedCodemodCommand
from libcst.codemod.visitors import AddImportsVisitor
class ReplaceUtcnow(VisitorBasedCodemodCommand):
DESCRIPTION = "Replace datetime.utcnow() with datetime.now(UTC)."
@m.leave(m.Call(func=m.Attribute(value=m.Name("datetime"), attr=m.Name("utcnow")), args=[]))
def replace(self, original: cst.Call, updated: cst.Call) -> cst.Call:
AddImportsVisitor.add_needed_import(self.context, "datetime", "UTC")
return updated.with_changes(
func=updated.func.with_changes(attr=cst.Name("now")),
args=[cst.Arg(cst.Name("UTC"))],
)
```
The tests pin the exact output, including the merged import line, and confirm that unrelated calls stay untouched.
```python title="codemods/test_replace_utcnow.py"
from libcst.codemod import CodemodTest
from codemods.replace_utcnow import ReplaceUtcnow
class TestReplaceUtcnow(CodemodTest):
TRANSFORM = ReplaceUtcnow
def test_rewrites_call(self) -> None:
before = "from datetime import datetime\nstamp = datetime.utcnow()\n"
after = "from datetime import UTC, datetime\nstamp = datetime.now(UTC)\n"
self.assertCodemod(before, after)
def test_leaves_other_calls(self) -> None:
code = "from datetime import datetime\nstamp = datetime.now()\n"
self.assertCodemod(code, code)
```
Two details matter when running it. `python -m libcst.tool initialize .` writes a `.libcst.codemod.yaml` whose default formatter is Black, and a run fails per file if that formatter is missing, so set `formatter: ['ruff', 'format', '-']` or pass `--no-format`. The codemod also changes semantics on purpose. Its output is correct syntax, and the aware-versus-naive decision still needs the Droid and the tests to check every caller.
## How Factory keeps the tools in the loop
Factory does not ship a Python migration mode or a transpiler. Its Python support comes from running the ecosystem's own tools at the right moments, with Droids working between them.
[Hooks](https://docs.factory.com/harness/hooks) run deterministic shell commands at lifecycle events. A `PostToolUse` hook runs after every edit, and when it exits with code `2` its stderr goes back to the Droid as corrective feedback. This hook rechecks each edited Python file with Ruff, so the Droid cannot reintroduce old syntax while fixing something else.
```json title=".factory/hooks.json"
{
"PostToolUse": [
{
"matcher": "Edit|Create",
"hooks": [
{
"type": "command",
"command": "\"$FACTORY_PROJECT_DIR\"/.factory/hooks/ruff-upgrade-check.sh",
"timeout": 60
}
]
}
]
}
```
```bash title=".factory/hooks/ruff-upgrade-check.sh"
#!/usr/bin/env bash
file=$(jq -r '.tool_input.file_path // empty')
[[ "$file" == *.py ]] || exit 0
if ! ruff check --select UP,F401 --target-version py312 --diff "$file" >&2
then
echo "Ruff reports pending upgrade fixes in $file. Apply them before continuing." >&2
exit 2
fi
```
A [skill](https://docs.factory.com/harness/skills) in `.factory/skills/python-upgrade/SKILL.md` packages the playbook, including target versions, the order of tools, the codemod modules to run, and the verification commands. The repository's [AGENTS.md](https://docs.factory.com/harness/agents-md) holds the exact `pytest`, `mypy`, and `ruff` invocations, so every session and every headless run uses the same gate.
For fan-out, the [lint autofix recipe](https://docs.factory.com/droid-exec/recipes/lint-autofix) shows the pattern for Droid Exec. A deterministic tool lists the files that fail, one `droid exec --auto low` run fixes each file, and the tool checks each file again. The same script works with `mypy` output or a list of files that import a removed module. Upgrades that span many services fit [Missions](https://docs.factory.com/missions/overview), which list brownfield migrations as a use case and validate progress milestone by milestone.
The loop for one repository looks like this.
Deterministic pass