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