or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ast-utilities.mdcli.mdcore-engine.mdindex.mdplugin-system.mdstring-processing.mdtoken-manipulation.md
tile.json

tessl/pypi-pyupgrade

A tool and pre-commit hook to automatically upgrade Python syntax for newer versions of the language.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pyupgrade@3.20.x

To install, run

npx @tessl/cli install tessl/pypi-pyupgrade@3.20.0

index.mddocs/

pyupgrade

A tool and pre-commit hook to automatically upgrade Python syntax for newer versions of the language. pyupgrade modernizes Python code by transforming legacy syntax patterns into their modern equivalents, supporting upgrades across Python versions from 3.6 through 3.14+.

Package Information

  • Package Name: pyupgrade
  • Language: Python
  • Installation: pip install pyupgrade
  • Minimum Python Version: 3.9+

Core Imports

For command-line usage:

pyupgrade [OPTIONS] [FILES]

For programmatic usage:

from pyupgrade._main import main
from pyupgrade._data import Settings

Basic Usage

Command Line Interface

# Upgrade a single file
pyupgrade example.py

# Upgrade multiple files
pyupgrade src/*.py

# Upgrade for specific Python version
pyupgrade --py311-plus src/*.py

# Use as pre-commit hook
pyupgrade --py310-plus --keep-percent-format src/*.py

Programmatic Interface

from pyupgrade._main import main, _fix_plugins, _fix_tokens
from pyupgrade._data import Settings

# Use main function
exit_code = main(['--py310-plus', 'example.py'])

# Transform code programmatically  
settings = Settings(min_version=(3, 10), keep_percent_format=True)
upgraded_code = _fix_plugins(source_code, settings)
upgraded_code = _fix_tokens(upgraded_code)

Architecture

pyupgrade uses a two-phase transformation approach:

  • Plugin System: AST-based transformations for complex syntax upgrades (set literals, f-strings, type annotations, etc.)
  • Token System: Token-level transformations for simpler patterns (escape sequences, parentheses, format strings)

The plugin system uses a registration mechanism where plugins register callbacks for specific AST node types. Each plugin can examine the AST and generate token-level transformations that are applied during the second phase.

Capabilities

Command Line Interface

Command-line tool for upgrading Python files with extensive configuration options for different Python versions and preservation settings.

def main(argv: Sequence[str] | None = None) -> int:
    """
    Main entry point for command-line interface.
    
    Args:
        argv: Command line arguments (None uses sys.argv)
        
    Returns:
        Exit code (0 for success, 1 for failure/changes made)
    """

Command Line Interface

Core Transformation Engine

Core functionality for applying syntax transformations through plugin and token systems.

def _fix_plugins(contents_text: str, settings: Settings) -> str:
    """Apply plugin-based AST transformations."""

def _fix_tokens(contents_text: str) -> str:
    """Apply token-level transformations."""

class Settings(NamedTuple):
    min_version: Version = (3,)
    keep_percent_format: bool = False
    keep_mock: bool = False  
    keep_runtime_typing: bool = False

Core Transformation Engine

Plugin System

Extensible plugin architecture for registering AST-based syntax transformations.

def register(tp: type[AST_T]) -> Callable[[ASTFunc[AST_T]], ASTFunc[AST_T]]:
    """Register transformation function for AST node type."""

def visit(funcs: ASTCallbackMapping, tree: ast.Module, settings: Settings) -> dict[Offset, list[TokenFunc]]:
    """Visit AST and collect transformation callbacks."""

class State(NamedTuple):
    settings: Settings
    from_imports: dict[str, set[str]]
    in_annotation: bool = False

Plugin System

AST Utilities

Helper functions for working with Python AST nodes during transformations.

def ast_parse(contents_text: str) -> ast.Module:
    """Parse Python source into AST."""

def ast_to_offset(node: ast.expr | ast.stmt) -> Offset:
    """Convert AST node position to token offset."""

def is_name_attr(node: ast.AST, imports: dict[str, set[str]], mods: tuple[str, ...], names: Container[str]) -> bool:
    """Check if node matches imported name or attribute."""

AST Utilities

Token Manipulation

Comprehensive token-level manipulation utilities for precise code transformations.

def parse_call_args(tokens: list[Token], i: int) -> tuple[list[tuple[int, int]], int]:
    """Parse function call arguments from tokens."""

def replace_call(tokens: list[Token], start: int, end: int, args: list[tuple[int, int]], tmpl: str, *, parens: Sequence[int] = ()) -> None:
    """Replace function call with template."""

class Block(NamedTuple):
    """Code block boundaries in tokens."""
    start: int
    colon: int
    block: int 
    end: int
    line: bool

Token Manipulation

String Processing

Specialized utilities for processing and transforming string literals and format strings.

def parse_format(s: str) -> list[DotFormatPart]:
    """Parse format string into component parts."""

def unparse_parsed_string(parsed: list[DotFormatPart]) -> str:
    """Convert parsed format parts back to string."""

def is_codec(encoding: str, name: str) -> bool:
    """Check if encoding matches codec name."""

String Processing

Types

# Version and callback types
Version = tuple[int, ...]
TokenFunc = Callable[[int, list[Token]], None]
ASTFunc = Callable[[State, AST_T, ast.AST], Iterable[tuple[Offset, TokenFunc]]]

# String format processing
DotFormatPart = tuple[str, Optional[str], Optional[str], Optional[str]]

# Token manipulation structures  
class Victims(NamedTuple):
    starts: list[int]
    ends: list[int] 
    first_comma_index: int | None
    arg_index: int