Upgrade
Upgrading a codebase
Major releases of Flama occasionally relocate modules, rename symbols, or change a few call patterns. Rather than asking you to track down every affected import by hand, the command upgrade rewrites your codebase to match a target version, applying a set of codemods (automated source-to-source transformations) across your Python files.
Symbols that have no automatic replacement are never silently dropped: they are flagged in place with a # flama-upgrade
marker and reported as manual follow-ups. This page documents the command itself; for the end-to-end migration workflow,
see the Upgrading guide. To inspect the command options, run:
flama upgrade --help
Usage: flama upgrade [OPTIONS] PATHS... Upgrade a Flama codebase to a newer major version.
Rewrite import statements and renamed symbols across the Python files under <PATHS> so they match the target Flama version. By default the command previews a unified diff and leaves files untouched; pass --write to apply the changes in place. Symbols that have no automatic replacement are flagged with a '# flama-upgrade' marker and listed as manual follow-ups.
<PATHS> are the files and/or directories to process; directories are scanned recursively.
Example: flama upgrade src/ flama upgrade --write src/ tests/ flama upgrade --to 2.0 --skip move-module:flama.asgi src/āā Options āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā®ā --to TEXT Target Flama version (default: latest known āā migration). āā --from TEXT Source Flama version; only migrations newer than it āā are applied (default: all of them). āā --diff / --write Preview a diff (default) or rewrite files in place. āā --select TEXT Comma-separated operation ids to run exclusively. āā --skip TEXT Comma-separated operation ids to skip. āā --help Show this message and exit. āā°āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāÆParameters
Paths
- PATHS (required): the files and directories to process. Directories are scanned recursively.
Source and target versions
Every migration between the two ends applies, in order, so a codebase several releases behind is brought forward in a single run. By default the target is the latest known migration and no source is assumed, which applies every migration up to it. You can pin either end explicitly:
- from: the version your code already matches. Only migrations newer than it apply, which is how you narrow the chain when you know your codebase is already partway. Omitted, nothing is assumed and the whole chain runs. The installed Flama version is deliberately not consulted: you normally upgrade the package before running the command, which makes it the target rather than the source.
- to: the target version to migrate to. Defaults to the latest known migration.
Preview and apply
- diff / write: by default the command previews a unified diff and leaves your files untouched; pass
--writeto apply the changes in place.
Selecting operations
Every transformation has a stable operation id, so individual codemods can be run or excluded:
- select: a comma-separated list of operation ids to run exclusively.
- skip: a comma-separated list of operation ids to skip.
Examples
Previewing changes
By default, upgrade previews the changes as a unified diff without modifying anything, which makes it the safe first step:
flama upgrade src/When run in preview mode and changes are found, the command exits with a non-zero status, which makes it convenient to use as a check in a continuous integration and continuous deployment (CI/CD) pipeline.
Applying changes
Once you have reviewed the diff, apply it in place with --write:
flama upgrade --write src/ tests/Targeting a version and selecting operations
You can pin the source and target versions, and restrict which codemods run:
flama upgrade --from 1.0 --to 2.0 --skip move-module:flama.asgi src/After running the codemods, address any # flama-upgrade markers left in your code, then run your test suite to confirm
the migration is complete. For a step-by-step walkthrough, see the Upgrading guide.