Bowler

Safe code refactoring for modern Python projects.

Current Development Status

Bowler 0.x is based on fissix (a fork of lib2to3) which was never intended to be a
stable api. We’ve pretty much reached the limit of being able to add new language
features, so while we can support 3.8’s walrus, that’s basically the last it’s going to
get.

See discussion for f(**not x) for one example –
a proper fix for things like this would mean invalidating all current patterns since
there’s no way to match against a specific revision of the grammar.

If you need to do codemods today, we recommend looking at
LibCST codemods which
are a bit more verbose, but work well on modern python grammars. We have contributed
support for Python 3.0-3.3 grammars
and have a draft PR going even further back to 2.3.

The longer term plan for Bowler is to build Bowler 2.x on top of libcst’s parser, while
still supporting a very simple fluent api. That’s unlikely to materialize in a final
release during 2021.

Overview

Bowler is a refactoring tool for manipulating Python at the syntax tree level. It enables
safe, large scale code modifications while guaranteeing that the resulting code compiles
and runs. It provides both a simple command line interface and a fluent API in Python for
generating complex code modifications in code.

Bowler uses a “fluent” Query API to build refactoring scripts through a series
of selectors, filters, and modifiers. Many simple modifications are already possible
using the existing API, but you can also provide custom selectors, filters, and
modifiers as needed to build more complex or custom refactorings. See the
Query Reference for more details.

Using the query API to rename a single function, and generate an interactive diff from
the results, would look something like this:

query = (
    Query(<paths to modify>)
    .select_function("old_name")
    .rename("new_name")
    .diff(interactive=True)
)

For more details or documentation, check out https://pybowler.io

Installing Bowler

Bowler supports modifications to code from any version of Python 2 or 3, but it
requires Python 3.6 or higher to run. Bowler can be easily installed using most common
Python packaging tools. We recommend installing the latest stable release from
PyPI with pip:

pip install bowler

You can also install a development version from source by checking out the Git repo:

git clone https://github.com/facebookincubator/bowler
cd bowler
python setup.py install

License

Bowler is MIT licensed, as found in the LICENSE file.