l4/pkg/python/contrib/Lib/lib2to3/refactor.py

   1 #!/usr/bin/env python2.5
   2 # Copyright 2006 Google, Inc. All Rights Reserved.
   3 # Licensed to PSF under a Contributor Agreement.
   4
   5 """Refactoring framework.
   6
   7 Used as a main program, this can refactor any number of files and/or
   8 recursively descend down directories.  Imported as a module, this
   9 provides infrastructure to write your own refactoring tool.
  10 """
  11
  12 __author__ = "Guido van Rossum <guido@python.org>"
  13
  14
  15 # Python imports
  16 import os
  17 import sys
  18 import difflib
  19 import logging
  20 import operator
  21 from collections import defaultdict
  22 from itertools import chain
  23
  24 # Local imports
  25 from .pgen2 import driver
  26 from .pgen2 import tokenize
  27
  28 from . import pytree
  29 from . import patcomp
  30 from . import fixes
  31 from . import pygram
  32
  33
  34 def get_all_fix_names(fixer_pkg, remove_prefix=True):
  35     """Return a sorted list of all available fix names in the given package."""
  36     pkg = __import__(fixer_pkg, [], [], ["*"])
  37     fixer_dir = os.path.dirname(pkg.__file__)
  38     fix_names = []
  39     for name in sorted(os.listdir(fixer_dir)):
  40         if name.startswith("fix_") and name.endswith(".py"):
  41             if remove_prefix:
  42                 name = name[4:]
  43             fix_names.append(name[:-3])
  44     return fix_names
  45
  46 def get_head_types(pat):
  47     """ Accepts a pytree Pattern Node and returns a set
  48         of the pattern types which will match first. """
  49
  50     if isinstance(pat, (pytree.NodePattern, pytree.LeafPattern)):
  51         # NodePatters must either have no type and no content
  52         #   or a type and content -- so they don't get any farther
  53         # Always return leafs
  54         return set([pat.type])
  55
  56     if isinstance(pat, pytree.NegatedPattern):
  57         if pat.content:
  58             return get_head_types(pat.content)
  59         return set([None]) # Negated Patterns don't have a type
  60
  61     if isinstance(pat, pytree.WildcardPattern):
  62         # Recurse on each node in content
  63         r = set()
  64         for p in pat.content:
  65             for x in p:
  66                 r.update(get_head_types(x))
  67         return r
  68
  69     raise Exception("Oh no! I don't understand pattern %s" %(pat))
  70
  71 def get_headnode_dict(fixer_list):
  72     """ Accepts a list of fixers and returns a dictionary
  73         of head node type --> fixer list.  """
  74     head_nodes = defaultdict(list)
  75     for fixer in fixer_list:
  76         if not fixer.pattern:
  77             head_nodes[None].append(fixer)
  78             continue
  79         for t in get_head_types(fixer.pattern):
  80             head_nodes[t].append(fixer)
  81     return head_nodes
  82
  83 def get_fixers_from_package(pkg_name):
  84     """
  85     Return the fully qualified names for fixers in the package pkg_name.
  86     """
  87     return [pkg_name + "." + fix_name
  88             for fix_name in get_all_fix_names(pkg_name, False)]
  89
  90
  91 class FixerError(Exception):
  92     """A fixer could not be loaded."""
  93
  94
  95 class RefactoringTool(object):
  96
  97     _default_options = {"print_function": False}
  98
  99     CLASS_PREFIX = "Fix" # The prefix for fixer classes
 100     FILE_PREFIX = "fix_" # The prefix for modules with a fixer within
 101
 102     def __init__(self, fixer_names, options=None, explicit=None):
 103         """Initializer.
 104
 105         Args:
 106             fixer_names: a list of fixers to import
 107             options: an dict with configuration.
 108             explicit: a list of fixers to run even if they are explicit.
 109         """
 110         self.fixers = fixer_names
 111         self.explicit = explicit or []
 112         self.options = self._default_options.copy()
 113         if options is not None:
 114             self.options.update(options)
 115         self.errors = []
 116         self.logger = logging.getLogger("RefactoringTool")
 117         self.fixer_log = []
 118         self.wrote = False
 119         if self.options["print_function"]:
 120             del pygram.python_grammar.keywords["print"]
 121         self.driver = driver.Driver(pygram.python_grammar,
 122                                     convert=pytree.convert,
 123                                     logger=self.logger)
 124         self.pre_order, self.post_order = self.get_fixers()
 125
 126         self.pre_order_heads = get_headnode_dict(self.pre_order)
 127         self.post_order_heads = get_headnode_dict(self.post_order)
 128
 129         self.files = []  # List of files that were or should be modified
 130
 131     def get_fixers(self):
 132         """Inspects the options to load the requested patterns and handlers.
 133
 134         Returns:
 135           (pre_order, post_order), where pre_order is the list of fixers that
 136           want a pre-order AST traversal, and post_order is the list that want
 137           post-order traversal.
 138         """
 139         pre_order_fixers = []
 140         post_order_fixers = []
 141         for fix_mod_path in self.fixers:
 142             mod = __import__(fix_mod_path, {}, {}, ["*"])
 143             fix_name = fix_mod_path.rsplit(".", 1)[-1]
 144             if fix_name.startswith(self.FILE_PREFIX):
 145                 fix_name = fix_name[len(self.FILE_PREFIX):]
 146             parts = fix_name.split("_")
 147             class_name = self.CLASS_PREFIX + "".join([p.title() for p in parts])
 148             try:
 149                 fix_class = getattr(mod, class_name)
 150             except AttributeError:
 151                 raise FixerError("Can't find %s.%s" % (fix_name, class_name))
 152             fixer = fix_class(self.options, self.fixer_log)
 153             if fixer.explicit and self.explicit is not True and \
 154                     fix_mod_path not in self.explicit:
 155                 self.log_message("Skipping implicit fixer: %s", fix_name)
 156                 continue
 157
 158             self.log_debug("Adding transformation: %s", fix_name)
 159             if fixer.order == "pre":
 160                 pre_order_fixers.append(fixer)
 161             elif fixer.order == "post":
 162                 post_order_fixers.append(fixer)
 163             else:
 164                 raise FixerError("Illegal fixer order: %r" % fixer.order)
 165
 166         key_func = operator.attrgetter("run_order")
 167         pre_order_fixers.sort(key=key_func)
 168         post_order_fixers.sort(key=key_func)
 169         return (pre_order_fixers, post_order_fixers)
 170
 171     def log_error(self, msg, *args, **kwds):
 172         """Called when an error occurs."""
 173         raise
 174
 175     def log_message(self, msg, *args):
 176         """Hook to log a message."""
 177         if args:
 178             msg = msg % args
 179         self.logger.info(msg)
 180
 181     def log_debug(self, msg, *args):
 182         if args:
 183             msg = msg % args
 184         self.logger.debug(msg)
 185
 186     def print_output(self, lines):
 187         """Called with lines of output to give to the user."""
 188         pass
 189
 190     def refactor(self, items, write=False, doctests_only=False):
 191         """Refactor a list of files and directories."""
 192         for dir_or_file in items:
 193             if os.path.isdir(dir_or_file):
 194                 self.refactor_dir(dir_or_file, write, doctests_only)
 195             else:
 196                 self.refactor_file(dir_or_file, write, doctests_only)
 197
 198     def refactor_dir(self, dir_name, write=False, doctests_only=False):
 199         """Descends down a directory and refactor every Python file found.
 200
 201         Python files are assumed to have a .py extension.
 202
 203         Files and subdirectories starting with '.' are skipped.
 204         """
 205         for dirpath, dirnames, filenames in os.walk(dir_name):
 206             self.log_debug("Descending into %s", dirpath)
 207             dirnames.sort()
 208             filenames.sort()
 209             for name in filenames:
 210                 if not name.startswith(".") and name.endswith("py"):
 211                     fullname = os.path.join(dirpath, name)
 212                     self.refactor_file(fullname, write, doctests_only)
 213             # Modify dirnames in-place to remove subdirs with leading dots
 214             dirnames[:] = [dn for dn in dirnames if not dn.startswith(".")]
 215
 216     def refactor_file(self, filename, write=False, doctests_only=False):
 217         """Refactors a file."""
 218         try:
 219             f = open(filename)
 220         except IOError, err:
 221             self.log_error("Can't open %s: %s", filename, err)
 222             return
 223         try:
 224             input = f.read() + "\n" # Silence certain parse errors
 225         finally:
 226             f.close()
 227         if doctests_only:
 228             self.log_debug("Refactoring doctests in %s", filename)
 229             output = self.refactor_docstring(input, filename)
 230             if output != input:
 231                 self.processed_file(output, filename, input, write=write)
 232             else:
 233                 self.log_debug("No doctest changes in %s", filename)
 234         else:
 235             tree = self.refactor_string(input, filename)
 236             if tree and tree.was_changed:
 237                 # The [:-1] is to take off the \n we added earlier
 238                 self.processed_file(str(tree)[:-1], filename, write=write)
 239             else:
 240                 self.log_debug("No changes in %s", filename)
 241
 242     def refactor_string(self, data, name):
 243         """Refactor a given input string.
 244
 245         Args:
 246             data: a string holding the code to be refactored.
 247             name: a human-readable name for use in error/log messages.
 248
 249         Returns:
 250             An AST corresponding to the refactored input stream; None if
 251             there were errors during the parse.
 252         """
 253         try:
 254             tree = self.driver.parse_string(data)
 255         except Exception, err:
 256             self.log_error("Can't parse %s: %s: %s",
 257                            name, err.__class__.__name__, err)
 258             return
 259         self.log_debug("Refactoring %s", name)
 260         self.refactor_tree(tree, name)
 261         return tree
 262
 263     def refactor_stdin(self, doctests_only=False):
 264         input = sys.stdin.read()
 265         if doctests_only:
 266             self.log_debug("Refactoring doctests in stdin")
 267             output = self.refactor_docstring(input, "<stdin>")
 268             if output != input:
 269                 self.processed_file(output, "<stdin>", input)
 270             else:
 271                 self.log_debug("No doctest changes in stdin")
 272         else:
 273             tree = self.refactor_string(input, "<stdin>")
 274             if tree and tree.was_changed:
 275                 self.processed_file(str(tree), "<stdin>", input)
 276             else:
 277                 self.log_debug("No changes in stdin")
 278
 279     def refactor_tree(self, tree, name):
 280         """Refactors a parse tree (modifying the tree in place).
 281
 282         Args:
 283             tree: a pytree.Node instance representing the root of the tree
 284                   to be refactored.
 285             name: a human-readable name for this tree.
 286
 287         Returns:
 288             True if the tree was modified, False otherwise.
 289         """
 290         for fixer in chain(self.pre_order, self.post_order):
 291             fixer.start_tree(tree, name)
 292
 293         self.traverse_by(self.pre_order_heads, tree.pre_order())
 294         self.traverse_by(self.post_order_heads, tree.post_order())
 295
 296         for fixer in chain(self.pre_order, self.post_order):
 297             fixer.finish_tree(tree, name)
 298         return tree.was_changed
 299
 300     def traverse_by(self, fixers, traversal):
 301         """Traverse an AST, applying a set of fixers to each node.
 302
 303         This is a helper method for refactor_tree().
 304
 305         Args:
 306             fixers: a list of fixer instances.
 307             traversal: a generator that yields AST nodes.
 308
 309         Returns:
 310             None
 311         """
 312         if not fixers:
 313             return
 314         for node in traversal:
 315             for fixer in fixers[node.type] + fixers[None]:
 316                 results = fixer.match(node)
 317                 if results:
 318                     new = fixer.transform(node, results)
 319                     if new is not None and (new != node or
 320                                             str(new) != str(node)):
 321                         node.replace(new)
 322                         node = new
 323
 324     def processed_file(self, new_text, filename, old_text=None, write=False):
 325         """
 326         Called when a file has been refactored, and there are changes.
 327         """
 328         self.files.append(filename)
 329         if old_text is None:
 330             try:
 331                 f = open(filename, "r")
 332             except IOError, err:
 333                 self.log_error("Can't read %s: %s", filename, err)
 334                 return
 335             try:
 336                 old_text = f.read()
 337             finally:
 338                 f.close()
 339         if old_text == new_text:
 340             self.log_debug("No changes to %s", filename)
 341             return
 342         self.print_output(diff_texts(old_text, new_text, filename))
 343         if write:
 344             self.write_file(new_text, filename, old_text)
 345         else:
 346             self.log_debug("Not writing changes to %s", filename)
 347
 348     def write_file(self, new_text, filename, old_text):
 349         """Writes a string to a file.
 350
 351         It first shows a unified diff between the old text and the new text, and
 352         then rewrites the file; the latter is only done if the write option is
 353         set.
 354         """
 355         try:
 356             f = open(filename, "w")
 357         except os.error, err:
 358             self.log_error("Can't create %s: %s", filename, err)
 359             return
 360         try:
 361             f.write(new_text)
 362         except os.error, err:
 363             self.log_error("Can't write %s: %s", filename, err)
 364         finally:
 365             f.close()
 366         self.log_debug("Wrote changes to %s", filename)
 367         self.wrote = True
 368
 369     PS1 = ">>> "
 370     PS2 = "... "
 371
 372     def refactor_docstring(self, input, filename):
 373         """Refactors a docstring, looking for doctests.
 374
 375         This returns a modified version of the input string.  It looks
 376         for doctests, which start with a ">>>" prompt, and may be
 377         continued with "..." prompts, as long as the "..." is indented
 378         the same as the ">>>".
 379
 380         (Unfortunately we can't use the doctest module's parser,
 381         since, like most parsers, it is not geared towards preserving
 382         the original source.)
 383         """
 384         result = []
 385         block = None
 386         block_lineno = None
 387         indent = None
 388         lineno = 0
 389         for line in input.splitlines(True):
 390             lineno += 1
 391             if line.lstrip().startswith(self.PS1):
 392                 if block is not None:
 393                     result.extend(self.refactor_doctest(block, block_lineno,
 394                                                         indent, filename))
 395                 block_lineno = lineno
 396                 block = [line]
 397                 i = line.find(self.PS1)
 398                 indent = line[:i]
 399             elif (indent is not None and
 400                   (line.startswith(indent + self.PS2) or
 401                    line == indent + self.PS2.rstrip() + "\n")):
 402                 block.append(line)
 403             else:
 404                 if block is not None:
 405                     result.extend(self.refactor_doctest(block, block_lineno,
 406                                                         indent, filename))
 407                 block = None
 408                 indent = None
 409                 result.append(line)
 410         if block is not None:
 411             result.extend(self.refactor_doctest(block, block_lineno,
 412                                                 indent, filename))
 413         return "".join(result)
 414
 415     def refactor_doctest(self, block, lineno, indent, filename):
 416         """Refactors one doctest.
 417
 418         A doctest is given as a block of lines, the first of which starts
 419         with ">>>" (possibly indented), while the remaining lines start
 420         with "..." (identically indented).
 421
 422         """
 423         try:
 424             tree = self.parse_block(block, lineno, indent)
 425         except Exception, err:
 426             if self.log.isEnabledFor(logging.DEBUG):
 427                 for line in block:
 428                     self.log_debug("Source: %s", line.rstrip("\n"))
 429             self.log_error("Can't parse docstring in %s line %s: %s: %s",
 430                            filename, lineno, err.__class__.__name__, err)
 431             return block
 432         if self.refactor_tree(tree, filename):
 433             new = str(tree).splitlines(True)
 434             # Undo the adjustment of the line numbers in wrap_toks() below.
 435             clipped, new = new[:lineno-1], new[lineno-1:]
 436             assert clipped == ["\n"] * (lineno-1), clipped
 437             if not new[-1].endswith("\n"):
 438                 new[-1] += "\n"
 439             block = [indent + self.PS1 + new.pop(0)]
 440             if new:
 441                 block += [indent + self.PS2 + line for line in new]
 442         return block
 443
 444     def summarize(self):
 445         if self.wrote:
 446             were = "were"
 447         else:
 448             were = "need to be"
 449         if not self.files:
 450             self.log_message("No files %s modified.", were)
 451         else:
 452             self.log_message("Files that %s modified:", were)
 453             for file in self.files:
 454                 self.log_message(file)
 455         if self.fixer_log:
 456             self.log_message("Warnings/messages while refactoring:")
 457             for message in self.fixer_log:
 458                 self.log_message(message)
 459         if self.errors:
 460             if len(self.errors) == 1:
 461                 self.log_message("There was 1 error:")
 462             else:
 463                 self.log_message("There were %d errors:", len(self.errors))
 464             for msg, args, kwds in self.errors:
 465                 self.log_message(msg, *args, **kwds)
 466
 467     def parse_block(self, block, lineno, indent):
 468         """Parses a block into a tree.
 469
 470         This is necessary to get correct line number / offset information
 471         in the parser diagnostics and embedded into the parse tree.
 472         """
 473         return self.driver.parse_tokens(self.wrap_toks(block, lineno, indent))
 474
 475     def wrap_toks(self, block, lineno, indent):
 476         """Wraps a tokenize stream to systematically modify start/end."""
 477         tokens = tokenize.generate_tokens(self.gen_lines(block, indent).next)
 478         for type, value, (line0, col0), (line1, col1), line_text in tokens:
 479             line0 += lineno - 1
 480             line1 += lineno - 1
 481             # Don't bother updating the columns; this is too complicated
 482             # since line_text would also have to be updated and it would
 483             # still break for tokens spanning lines.  Let the user guess
 484             # that the column numbers for doctests are relative to the
 485             # end of the prompt string (PS1 or PS2).
 486             yield type, value, (line0, col0), (line1, col1), line_text
 487
 488
 489     def gen_lines(self, block, indent):
 490         """Generates lines as expected by tokenize from a list of lines.
 491
 492         This strips the first len(indent + self.PS1) characters off each line.
 493         """
 494         prefix1 = indent + self.PS1
 495         prefix2 = indent + self.PS2
 496         prefix = prefix1
 497         for line in block:
 498             if line.startswith(prefix):
 499                 yield line[len(prefix):]
 500             elif line == prefix.rstrip() + "\n":
 501                 yield "\n"
 502             else:
 503                 raise AssertionError("line=%r, prefix=%r" % (line, prefix))
 504             prefix = prefix2
 505         while True:
 506             yield ""
 507
 508
 509 def diff_texts(a, b, filename):
 510     """Return a unified diff of two strings."""
 511     a = a.splitlines()
 512     b = b.splitlines()
 513     return difflib.unified_diff(a, b, filename, filename,
 514                                 "(original)", "(refactored)",
 515                                 lineterm="")