Upgrading
Software evolves, and Flama is no exception. As the framework grows, a new major release occasionally relocates a module, renames a symbol, or tightens a signature. To spare you from chasing every one of these changes by hand, Flama ships an upgrade command that rewrites your codebase to match a newer version automatically. This page walks through the upgrade process end to end, so that moving a project from one major version to the next is a routine, low-risk task rather than a tedious migration.
How upgrades work
In Flama, an upgrade brings two things into line with a newer release: the library installed in your
environment, and the source code of your project that depends on it. Minor and patch releases are backwards compatible,
so updating the library is enough. Major releases are where public interfaces may shift, and that is precisely what the
flama upgrade command is built for.
Under the hood, the command applies codemods ā automated source-to-source transformations ā across the Python
files you point it at. It rewrites import statements, renamed symbols, and a handful of call patterns so they match the
target version. Anything that has no automatic replacement is never silently dropped: it is flagged in place with a
# flama-upgrade marker and reported as a manual follow-up.
Why lean on the command instead of migrating by hand?
- Completeness: every affected import and reference under the given paths is rewritten, so nothing is missed.
- Safety: by default the command only previews a diff, leaving your files untouched until you choose to apply it.
- Transparency: changes that require human judgement are surfaced explicitly, rather than guessed at.
- Repeatability: the same command can run locally and in continuous integration, so upgrades stay verifiable.
The workflow that follows is deliberately version agnostic: the same steps apply whichever version you are moving from and to.
Upgrading your codebase
With the concepts in place, let's walk through a typical upgrade, from previewing the changes to confirming that your project still behaves as expected.
Previewing the changes
The first step is always to see what would change, without altering a single file. The recommended way to run the command is with pipx, which fetches and runs it in a throwaway environment, leaving your project's dependencies untouched:
pipx run flama upgrade src/ tests/Point the command at the files and directories you want to process; directories are scanned recursively. Alternatively, install Flama into your active environment and call the command directly:
pip install flamaflama upgrade src/ tests/By default, upgrade previews the changes as a unified diff and modifies nothing, which makes this the safe first step. When it finds pending changes in this mode, it exits with a non-zero status ā a detail we will put to use shortly.
Read through the diff carefully. Automatic rewrites generally fall into a few categories: modules that moved to a new
location, symbols that were renamed or relocated, and call patterns that changed shape. Anything the command cannot
rewrite on its own is left untouched and tagged with a # flama-upgrade marker for you to address by hand.
Applying the changes
Once you are happy with the proposed diff, apply it in place with the --write flag.
WARNING
The upgrade command rewrites files in place when applied. Commit or stash your work first, so that you always have a clean diff to review and can revert if needed.
flama upgrade --write src/ tests/The command now edits your files directly. Because you reviewed the diff in the previous step and your working tree was clean, you can inspect the result with your version control tooling and revert selectively if anything looks off.
Resolving manual follow-ups
Not every change can be made mechanically. When a symbol has been removed without a drop-in replacement, or a pattern
needs a decision only you can make, the command leaves a # flama-upgrade marker at the relevant line and lists it as a
follow-up. Search your codebase for the markers and resolve each one:
grep -rn "# flama-upgrade" src/ tests/Each marker is accompanied by a short note explaining what changed and what to do instead. Work through them, removing the markers as you go. Once none remain, pin your project's Flama dependency to the new version, reinstall it, and run your test suite to confirm the migration is complete.
Targeting a specific version
By default, the command detects the version installed in the environment as the source, and uses the latest known migration as the target. When you run it from an isolated pipx environment, where the detected version may differ from your project's, it is worth being explicit about both ends:
flama upgrade --from 1.0 --to 2.0 src/You can also restrict which transformations run with --select and --skip. For the full list of options, run
flama upgrade --help or see the Upgrade command reference.
Upgrading in continuous integration
Because preview mode exits with a non-zero status whenever it finds pending changes, the command doubles as a guard in a continuous integration and continuous deployment (CI/CD) pipeline. Adding the following step fails the build whenever a codebase has drifted behind the targeted version, reminding you to run the upgrade before merging:
flama upgrade src/ tests/With that, your project stays aligned with the latest version of Flama. To explore the command's options in more detail, head to the Upgrade reference in the Flama CLI section.