Bowler should include docs on how to test/debug/understand lib2to3 patterns

[msci-jordancrawford]

Not at all sure where something like this belongs, so I'm creating an issue in the hope that the team can give some guidance. When first starting with bowler, I struggled to wrap my head around how the lib2to3 patterns worked. The problem was compounded by the general lack of easily googleable information. To help myself understand (and after some reading though the source code), I came up with a basic way to play around:

from pprint import pprint

from fissix import pytree, pygram
from fissix.patcomp import PatternCompiler
from fissix.pgen2 import driver

d = driver.Driver(pygram.python_grammar.copy(), pytree.convert)
pc = PatternCompiler()

def test(pattern, code):
    pat = pc.compile_pattern(pattern)
    for node in d.parse_string(code).pre_order():
        for match in pat.generate_matches([node]):
            pprint(match)

# Anything calling .foo() with any args:
pattern="""
call=power<
  any*
  trailer<"." "foo">
  trailer<"(" args=any* ")">
>
"""
# Prints out details about both the f.foo and bar.foo calls
test(pattern,'a = f.foo(123) + bar.foo("adf")\n')

This test function made it much easier for me to start writing + understanding patterns because I could quickly iterate tests inside of a REPL.

Should something like this function be added to the website/documentation/somewhere else? Even without extensive documentation for the lib2to3 patterns (which would be a lot of work), it would be nice for new users to have a good starting point like this. (It also might be that this function already exists somewhere, and I just reinvented the wheel - whoops!).