Lib/lib2to3/fixer_base.py

   1 # Copyright 2006 Google, Inc. All Rights Reserved.
   2 # Licensed to PSF under a Contributor Agreement.
   3
   4 """Base class for fixers (optional, but recommended)."""
   5
   6 # Python imports
   7 import logging
   8 import itertools
   9
  10 # Local imports
  11 from .patcomp import PatternCompiler
  12 from . import pygram
  13 from .fixer_util import does_tree_import
  14
  15 class BaseFix(object):
  16
  17     """Optional base class for fixers.
  18
  19     The subclass name must be FixFooBar where FooBar is the result of
  20     removing underscores and capitalizing the words of the fix name.
  21     For example, the class name for a fixer named 'has_key' should be
  22     FixHasKey.
  23     """
  24
  25     PATTERN = None  # Most subclasses should override with a string literal
  26     pattern = None  # Compiled pattern, set by compile_pattern()
  27     options = None  # Options object passed to initializer
  28     filename = None # The filename (set by set_filename)
  29     logger = None   # A logger (set by set_filename)
  30     numbers = itertools.count(1) # For new_name()
  31     used_names = set() # A set of all used NAMEs
  32     order = "post" # Does the fixer prefer pre- or post-order traversal
  33     explicit = False # Is this ignored by refactor.py -f all?
  34     run_order = 5   # Fixers will be sorted by run order before execution
  35                     # Lower numbers will be run first.
  36     _accept_type = None # [Advanced and not public] This tells RefactoringTool
  37                         # which node type to accept when there's not a pattern.
  38
  39     # Shortcut for access to Python grammar symbols
  40     syms = pygram.python_symbols
  41
  42     def __init__(self, options, log):
  43         """Initializer.  Subclass may override.
  44
  45         Args:
  46             options: an dict containing the options passed to RefactoringTool
  47             that could be used to customize the fixer through the command line.
  48             log: a list to append warnings and other messages to.
  49         """
  50         self.options = options
  51         self.log = log
  52         self.compile_pattern()
  53
  54     def compile_pattern(self):
  55         """Compiles self.PATTERN into self.pattern.
  56
  57         Subclass may override if it doesn't want to use
  58         self.{pattern,PATTERN} in .match().
  59         """
  60         if self.PATTERN is not None:
  61             self.pattern = PatternCompiler().compile_pattern(self.PATTERN)
  62
  63     def set_filename(self, filename):
  64         """Set the filename, and a logger derived from it.
  65
  66         The main refactoring tool should call this.
  67         """
  68         self.filename = filename
  69         self.logger = logging.getLogger(filename)
  70
  71     def match(self, node):
  72         """Returns match for a given parse tree node.
  73
  74         Should return a true or false object (not necessarily a bool).
  75         It may return a non-empty dict of matching sub-nodes as
  76         returned by a matching pattern.
  77
  78         Subclass may override.
  79         """
  80         results = {"node": node}
  81         return self.pattern.match(node, results) and results
  82
  83     def transform(self, node, results):
  84         """Returns the transformation for a given parse tree node.
  85
  86         Args:
  87           node: the root of the parse tree that matched the fixer.
  88           results: a dict mapping symbolic names to part of the match.
  89
  90         Returns:
  91           None, or a node that is a modified copy of the
  92           argument node.  The node argument may also be modified in-place to
  93           effect the same change.
  94
  95         Subclass *must* override.
  96         """
  97         raise NotImplementedError()
  98
  99     def new_name(self, template=u"xxx_todo_changeme"):
 100         """Return a string suitable for use as an identifier
 101
 102         The new name is guaranteed not to conflict with other identifiers.
 103         """
 104         name = template
 105         while name in self.used_names:
 106             name = template + unicode(self.numbers.next())
 107         self.used_names.add(name)
 108         return name
 109
 110     def log_message(self, message):
 111         if self.first_log:
 112             self.first_log = False
 113             self.log.append("### In file %s ###" % self.filename)
 114         self.log.append(message)
 115
 116     def cannot_convert(self, node, reason=None):
 117         """Warn the user that a given chunk of code is not valid Python 3,
 118         but that it cannot be converted automatically.
 119
 120         First argument is the top-level node for the code in question.
 121         Optional second argument is why it can't be converted.
 122         """
 123         lineno = node.get_lineno()
 124         for_output = node.clone()
 125         for_output.prefix = u""
 126         msg = "Line %d: could not convert: %s"
 127         self.log_message(msg % (lineno, for_output))
 128         if reason:
 129             self.log_message(reason)
 130
 131     def warning(self, node, reason):
 132         """Used for warning the user about possible uncertainty in the
 133         translation.
 134
 135         First argument is the top-level node for the code in question.
 136         Optional second argument is why it can't be converted.
 137         """
 138         lineno = node.get_lineno()
 139         self.log_message("Line %d: %s" % (lineno, reason))
 140
 141     def start_tree(self, tree, filename):
 142         """Some fixers need to maintain tree-wide state.
 143         This method is called once, at the start of tree fix-up.
 144
 145         tree - the root node of the tree to be processed.
 146         filename - the name of the file the tree came from.
 147         """
 148         self.used_names = tree.used_names
 149         self.set_filename(filename)
 150         self.numbers = itertools.count(1)
 151         self.first_log = True
 152
 153     def finish_tree(self, tree, filename):
 154         """Some fixers need to maintain tree-wide state.
 155         This method is called once, at the conclusion of tree fix-up.
 156
 157         tree - the root node of the tree to be processed.
 158         filename - the name of the file the tree came from.
 159         """
 160         pass
 161
 162
 163 class ConditionalFix(BaseFix):
 164     """ Base class for fixers which not execute if an import is found. """
 165
 166     # This is the name of the import which, if found, will cause the test to be skipped
 167     skip_on = None
 168
 169     def start_tree(self, *args):
 170         super(ConditionalFix, self).start_tree(*args)
 171         self._should_skip = None
 172
 173     def should_skip(self, node):
 174         if self._should_skip is not None:
 175             return self._should_skip
 176         pkg = self.skip_on.split(".")
 177         name = pkg[-1]
 178         pkg = ".".join(pkg[:-1])
 179         self._should_skip = does_tree_import(pkg, name, node)
 180         return self._should_skip