Skip to main content

a fork of facebook/codemod using pcre compatible regular expressions

Project description

codemod2

PyPI downloads

Overview

codemod2 is a tool/library to assist you with large-scale codebase refactors that can be partially automated but still require human oversight and occasional intervention. This is a FORK of the retired codemod cli tools developed by Justin Rosenstein at Facebook.

Example: Let's say you're deprecating your use of the <font> tag. From the command line, you might make progress by running:

codemod2 -m -d /home/mdrohmann/www --extensions py,html \
    '<font *color="?(.*?)"?>(.*?)</font>' \
    '<span style="color: {1};">\2</span>'

For each match of the regex, you'll be shown a colored diff, and asked if you want to accept the change (the replacement of the <font> tag with a <span> tag), reject it, or edit the line in question in your $EDITOR of choice.

Motivation for the fork

Most programming languages have some kind of balanced parantheses or brackets. PCRE2 regular expressions can help for such a use case. In my specific case, I wanted to wrap Python dictionaries in a specific type constructor in some contexts.

The following codemod2 regular expression accomplishes this:

codemod2 -m 'context=(?<expr>\{(?:[^}{]+|(?P>expr))*+\})' 'context=DictConstructor({1})'

Note, that the substitution string is a Python format string now, because codemod uses the regex package instead of the standard lib re package.

The diff output is also improved and now uses the routines from the difflib library to display changes.

Alternatives

There are more sophisticated solutions to modifying your code base that are based on parsing an abstract or concrete syntax tree representation of your code. Examples in the Python space are rope and libCST. In Golang, there are tools like [eg] (https://github.com/golang/tools/blob/master/refactor/eg/eg.go) and rf.

All of the above may work more reliably for the use-cases they provide solutions for. But in my own experience, I often got disappointed after going through the process of

  • finding the tool that works for the use-case
  • understanding its usage, and
  • applying it to my use-case.

Consider that refactors usually are simple tasks, and when assessing the efficacy of a tool and you are working on a small to medium sized code-base, you have to weigh the above investment against the option to just slog through it for half an hour with a cup of coffee, applying all the changes with your favorite editor manually until the linter and test checks are happy again. This tool is simple, but generic and regular expressions are widely known, such that many members of your team can use and understand them.

So, compared to most alternatives, this is where codemod2 shines:

  • Easy on-boarding if you knw regular expressions: no need to learn new syntax
  • Capabilities and limitations of codemod2 are easy to understand

Install

In a virtual environment or as admin user

pip install codemod2

or with pipx

pipx install codemod2

Usage

The last two arguments are a regular expression to match and a substitution string, respectively. Or you can omit the substitution string, and just be prompted on each match for whether you want to edit in your editor.

Options (all optional) include:

-m
  Have regex work over multiple lines (e.g. have dot match newlines).  By
  default, codemod2 applies the regex one line at a time.
-d
  The path whose ancestor files are to be explored.  Defaults to current dir.
-i
  Make your search case-insensitive
--start
  A path:line_number-formatted position somewhere in the hierarchy from which
  to being exploring, or a percentage (e.g. "--start 25%") of the way through
  to start.  Useful if you're divvying up the substitution task across
  multiple people.
--end
  A path:line_number-formatted position somewhere in the hierarchy just
  *before* which we should stop exploring, or a percentage of the way
  through, just before which to end.
--extensions
  A comma-delimited list of file extensions to process. Also supports Unix
  pattern matching.
--include-extensionless
  If set, this will check files without an extension, along with any
  matching file extensions passed in --extensions
--accept-all
  Automatically accept all changes (use with caution)
--default-no
  Set default behavior to reject the change.
--editor
  Specify an editor, e.g. "vim" or "emacs".  If omitted, defaults to $EDITOR
  environment variable.
--count
  Don't run normally.  Instead, just print out number of times places in the
  codebase where the 'query' matches.
--test
  Don't run normally.  Instead, just run the unit tests embedded in the
  codemod2 library.

You can also use codemod for transformations that are much more sophisticated than regular expression substitution. Rather than using the command line, you write Python code that looks like:

from codemod2 import run_interactive, Query
run_interactive(Query(...))

See the documentation for the Query class for details if you want to try it.

Dependencies

  • python2
  • regex

Credits

Copyright (c) 2024 Martin Drohmann.

Copyright (c) 2007-2008 Facebook.

Created by Justin Rosenstein.

Licensed under the Apache License, Version 2.0.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

codemod2-0.2.4.tar.gz (20.7 kB view details)

Uploaded Source

Built Distribution

codemod2-0.2.4-py3-none-any.whl (21.8 kB view details)

Uploaded Python 3

File details

Details for the file codemod2-0.2.4.tar.gz.

File metadata

  • Download URL: codemod2-0.2.4.tar.gz
  • Upload date:
  • Size: 20.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.11.6 Linux/6.5.0-14-generic

File hashes

Hashes for codemod2-0.2.4.tar.gz
Algorithm Hash digest
SHA256 b7f7139f52de722533fbfe0792ad398c6aa85f00786304b6dca3d6af753655fa
MD5 6703caa2e4b4ac178d99245d4deb7a6d
BLAKE2b-256 aca2d448188445dd5bf4ee637213415ae31198969bcb6120d9a7d76fd72abe04

See more details on using hashes here.

Provenance

File details

Details for the file codemod2-0.2.4-py3-none-any.whl.

File metadata

  • Download URL: codemod2-0.2.4-py3-none-any.whl
  • Upload date:
  • Size: 21.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.11.6 Linux/6.5.0-14-generic

File hashes

Hashes for codemod2-0.2.4-py3-none-any.whl
Algorithm Hash digest
SHA256 9ba92bd68cc17006ecd8a7da2a2f09e9cd42038cc45c505bc325dbdba28729ca
MD5 dcb80b4e549f867c32f8ec3205aee1fa
BLAKE2b-256 6ad4d25928af829145ab6509ff3e198c2c8a5c159b84746fb2798ad59ad44de5

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page