OpenRewrite Python

OpenRewrite automated refactoring for Python source code. This package provides the recipe framework, the Python Lossless Semantic Tree (LST), and the testing helpers you use to author and test Python recipes.

Installation

pip install openrewrite

How it works

OpenRewrite for Python uses a split JVM/Python architecture. You author and unit-test recipes in pure Python, but running a recipe against a real codebase is orchestrated by the JVM runtime via the Moderne CLI (with Python support configured) over an RPC bridge. There is no standalone, in-process Python parser entry point.

Quick start

The fastest way to author and exercise a recipe is the test harness, which parses a before snippet, runs your recipe, and asserts the result matches after:

from rewrite.test import RecipeSpec, python

def test_renames_a_call():
    spec = RecipeSpec(recipe=RenameFunctionCall(
        old_name="assertEquals",
        new_name="assertEqual",
    ))
    spec.rewrite_run(
        python("assertEquals(a, b)", "assertEqual(a, b)"),
    )

python(before, after) asserts a change; python(before) asserts no change.

Writing a recipe

A recipe is a @dataclass subclassing Recipe that returns a visitor from editor(). Each option must have a default value, or the recipe cannot be discovered or run.

from dataclasses import dataclass, field

from rewrite import ExecutionContext, Recipe, TreeVisitor, option
from rewrite.java import J
from rewrite.java.tree import MethodInvocation
from rewrite.python.visitor import PythonVisitor


@dataclass
class RenameFunctionCall(Recipe):
    """Rename calls to a function from one name to another."""

    old_name: str = field(default="", metadata=option(
        display_name="Old function name",
        description="The name of the function whose calls should be renamed.",
        example="assertEquals",
    ))

    new_name: str = field(default="", metadata=option(
        display_name="New function name",
        description="The name to rename matching calls to.",
        example="assertEqual",
    ))

    @property
    def name(self) -> str:
        return "com.yourorg.RenameFunctionCall"

    @property
    def display_name(self) -> str:
        return "Rename a function call"

    @property
    def description(self) -> str:
        return "Rename calls to a function from one name to another."

    def editor(self) -> TreeVisitor[J, ExecutionContext]:
        old_name = self.old_name
        new_name = self.new_name

        class Visitor(PythonVisitor[ExecutionContext]):
            def visit_method_invocation(self, method: MethodInvocation, p: ExecutionContext) -> J:
                method = super().visit_method_invocation(method, p)
                if method.name.simple_name == old_name:
                    renamed = method.name.replace(_simple_name=new_name)
                    return method.replace(_name=renamed)
                return method

        return Visitor()

Returning None from a visit method removes the node entirely — which is how recipes delete code.

Running recipes with the Moderne CLI

Expose an activate() function so the CLI can discover your recipe:

from rewrite.marketplace import RecipeMarketplace, Python

def activate(marketplace: RecipeMarketplace) -> None:
    marketplace.install(RenameFunctionCall, Python)

Then install and run it against a repository whose Python LSTs you've built, passing each option as a -P parameter:

# From your recipe project directory, install it into the CLI's marketplace:
mod config recipes pip install .

# Build the LSTs for the repository you want to refactor, then run the recipe:
mod build /path/to/your/repo
mod run /path/to/your/repo --recipe=com.yourorg.RenameFunctionCall \
    -P old_name=assertEquals -P new_name=assertEqual

Learn more

Python Recipe Starter — a complete project with example recipes, tests, and CI to clone and build on
Writing a Python refactoring recipe — step-by-step authoring guide
rewrite-python module — the Python LST, parser, and built-in recipes
docs.openrewrite.org — full OpenRewrite documentation

License

Moderne Source Available License - see LICENSE.md

Metadata

Release files for openrewrite 8.86.0.dev20260625135457

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openrewrite 8.86.0.dev20260625135457
File	Size	Uploaded
openrewrite-8.86.0.dev20260625135457.tar.gz	319.8 kB	Jun 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for openrewrite 8.86.0.dev20260625135457
File	Interpreter	ABI	Platform	Reset
openrewrite-8.86.0.dev20260625135457-py3-none-any.whl 362.3 kB Jun 25, 2026	Python 3	none	any	Details

Total release size: 682.1 kB

Release files / openrewrite-8.86.0.dev20260625135457.tar.gz

Download URL	openrewrite-8.86.0.dev20260625135457.tar.gz
Size	319.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`1eb5afd905ce38ab518cf5fba7d4183a86a9d1a5966f9660cf3b81acae391a71`
BLAKE2b-256 checksum How to use checksums	`3d776b2711f6913e5b36049e82dd6fe6e82677d90eb7d85bed608a53cac6f1fd`
Upload date	Jun 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`

Release files / openrewrite-8.86.0.dev20260625135457-py3-none-any.whl

Download URL	openrewrite-8.86.0.dev20260625135457-py3-none-any.whl
Size	362.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`526f38baa1ac37011dea76b22e8cf8eba1b91e1f1742248d22f068f8cec3aaa2`
BLAKE2b-256 checksum How to use checksums	`3ce31574d598d8699f83f609884aea7f135538a448cd6acf63e39675517926e2`
Upload date	Jun 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.3`