mafw.devtools.toolchain.tools.pyupgrade

PyUpgradeTool — concrete ProjectTool for pyupgrade.

This module implements the PyUpgradeTool class that manages the pyupgrade syntax modernizer across two configuration files:

• pyproject.toml — lower-bound >= specifier in project.optional-dependencies.dev

• .pre-commit-config.yaml — the rev field of the https://github.com/asottile/pyupgrade repository entry

Because pyupgrade is referenced in two places, the verify() method checks that the two declared versions are consistent. The post_update() hook recreates the dev hatch environment, then runs pyupgrade via pre-commit run pyupgrade --all-files at the highest supported Python version, and reverts both files if the command fails.

The tool follows the same cross-file synchronization pattern as RuffTool: the base class’s _saved_content and _revert() handle pyproject.toml, while a separate _saved_precommit attribute tracks the pre-commit config file state.

Classes

PyUpgradeTool([project_root])

Manage pyupgrade across pyproject.toml and pre-commit.

class mafw.devtools.toolchain.tools.pyupgrade.PyUpgradeTool(project_root: Path | None = None)

Bases: ProjectTool

Manage pyupgrade across pyproject.toml and pre-commit.

pyupgrade is categorized as a project tool. Its version lower bound lives in project.optional-dependencies.dev and the pre-commit hook revision is declared in .pre-commit-config.yaml under the asottile/pyupgrade repository. Both must stay in sync.

The update() method writes both files (pyproject first, then pre-commit). On post_update() failure, both files are reverted to their pre-update contents: pyproject.toml via the inherited _revert() helper, and .pre-commit-config.yaml via the local _saved_precommit attribute.

Parameters:

project_root (Path | None) – Path to the project root directory containing both pyproject.toml and .pre-commit-config.yaml. Defaults to the current working directory.

_get_precommit_version() → Version | None

Read the pyupgrade version from the pre-commit config rev field.

Parses .pre-commit-config.yaml, locates the asottile/pyupgrade repo entry, reads its rev field, strips the v prefix, and returns it as a Version.

Returns:

The version from the pre-commit rev field, or None if the repo or rev cannot be found.

Return type:

Version | None

_revert_all() → None

Restore both config files to their saved pre-update state.

Uses the parent class _revert() for pyproject.toml and manually restores .pre-commit-config.yaml from the saved content. Silently handles the case where saved content is not available.

_revert_precommit() → None

Restore .pre-commit-config.yaml to its saved pre-update state.

Silently handles the case where saved content is not available.

post_update() → None

Recreate the dev environment and run pyupgrade via pre-commit.

Performs the following steps after a successful version update:

1. Forces recreation of the dev hatch environment so that the newly specified dependency versions are resolved and installed.

2. Determines the highest supported Python version dynamically from tool.mafw.supported-python in pyproject.toml.

3. Runs pre-commit run pyupgrade --all-files via the dev environment to execute pyupgrade on all source files.

If environment recreation fails due to a dependency conflict, both pyproject.toml and .pre-commit-config.yaml are reverted. If pyupgrade fails, both files are also reverted.

Raises:

DevtoolsError – If environment recreation fails or pyupgrade exits with a non-zero exit code.

update() → bool

Update the pyupgrade version in pyproject.toml and .pre-commit-config.yaml.

Performs both updates:

1. Sets the >= lower bound for pyupgrade in project.optional-dependencies.dev to the latest PyPI version (delegated to the parent class).

2. Updates the rev field of the asottile/pyupgrade repo entry in .pre-commit-config.yaml to v{latest_version}.

Before modifying, saves both file contents so they can be reverted by post_update() on failure. The parent class handles saving pyproject.toml via _saved_content; this method additionally saves the pre-commit config.

Returns:

True if either file was changed, False if both are already up to date.

Return type:

bool

Raises:

DevtoolsError – If either file cannot be read or written.

verify() → list[Issue]

Compare pyupgrade version in pyproject.toml with the pre-commit rev.

Reads the >= lower bound from project.optional-dependencies.dev and the rev field (stripped of v prefix) from the asottile/pyupgrade repo entry. Returns an Issue if they do not match.

Returns:

A list containing at most one toolchain.Issue if the two versions differ, or an empty list if they are consistent.

Return type:

list[toolchain.Issue]

property env_name: str

Hatch environment where pyupgrade is validated.

Returns:

"dev"

Return type:

str

property package_name: str

PyPI package name.

Returns:

"pyupgrade"

Return type:

str

property section_path: str

TOML section path where pyupgrade is declared.

Returns:

"project.optional-dependencies.dev"

Return type:

str

mafw.devtools.toolchain.tools.pyupgrade._PRECOMMIT_REPO_URL: Final[str] = 'https://github.com/asottile/pyupgrade'

Repository URL for the pyupgrade pre-commit hook entry.