1r"""Utilities to compile possibly incomplete Python source code. 2 3This module provides two interfaces, broadly similar to the builtin 4function compile(), which take program text, a filename and a 'mode' 5and: 6 7- Return code object if the command is complete and valid 8- Return None if the command is incomplete 9- Raise SyntaxError, ValueError or OverflowError if the command is a 10 syntax error (OverflowError and ValueError can be produced by 11 malformed literals). 12 13Approach: 14 15First, check if the source consists entirely of blank lines and 16comments; if so, replace it with 'pass', because the built-in 17parser doesn't always do the right thing for these. 18 19Compile three times: as is, with \n, and with \n\n appended. If it 20compiles as is, it's complete. If it compiles with one \n appended, 21we expect more. If it doesn't compile either way, we compare the 22error we get when compiling with \n or \n\n appended. If the errors 23are the same, the code is broken. But if the errors are different, we 24expect more. Not intuitive; not even guaranteed to hold in future 25releases; but this matches the compiler's behavior from Python 1.4 26through 2.2, at least. 27 28Caveat: 29 30It is possible (but not likely) that the parser stops parsing with a 31successful outcome before reaching the end of the source; in this 32case, trailing symbols may be ignored instead of causing an error. 33For example, a backslash followed by two newlines may be followed by 34arbitrary garbage. This will be fixed once the API for the parser is 35better. 36 37The two interfaces are: 38 39compile_command(source, filename, symbol): 40 41 Compiles a single command in the manner described above. 42 43CommandCompiler(): 44 45 Instances of this class have __call__ methods identical in 46 signature to compile_command; the difference is that if the 47 instance compiles program text containing a __future__ statement, 48 the instance 'remembers' and compiles all subsequent program texts 49 with the statement in force. 50 51The module also provides another class: 52 53Compile(): 54 55 Instances of this class act like the built-in function compile, 56 but with 'memory' in the sense described above. 57""" 58 59import __future__ 60import warnings 61 62_features = [getattr(__future__, fname) 63 for fname in __future__.all_feature_names] 64 65__all__ = ["compile_command", "Compile", "CommandCompiler"] 66 67PyCF_DONT_IMPLY_DEDENT = 0x200 # Matches pythonrun.h. 68 69def _maybe_compile(compiler, source, filename, symbol): 70 # Check for source consisting of only blank lines and comments. 71 for line in source.split("\n"): 72 line = line.strip() 73 if line and line[0] != '#': 74 break # Leave it alone. 75 else: 76 if symbol != "eval": 77 source = "pass" # Replace it with a 'pass' statement 78 79 try: 80 return compiler(source, filename, symbol) 81 except SyntaxError: # Let other compile() errors propagate. 82 pass 83 84 # Catch syntax warnings after the first compile 85 # to emit warnings (SyntaxWarning, DeprecationWarning) at most once. 86 with warnings.catch_warnings(): 87 warnings.simplefilter("error") 88 89 code1 = err1 = err2 = None 90 try: 91 code1 = compiler(source + "\n", filename, symbol) 92 except SyntaxError as e: 93 err1 = e 94 95 try: 96 code2 = compiler(source + "\n\n", filename, symbol) 97 except SyntaxError as e: 98 err2 = e 99 100 try: 101 if not code1 and _is_syntax_error(err1, err2): 102 raise err1 103 else: 104 return None 105 finally: 106 err1 = err2 = None 107 108def _is_syntax_error(err1, err2): 109 rep1 = repr(err1) 110 rep2 = repr(err2) 111 if "was never closed" in rep1 and "was never closed" in rep2: 112 return False 113 if rep1 == rep2: 114 return True 115 return False 116 117def _compile(source, filename, symbol): 118 return compile(source, filename, symbol, PyCF_DONT_IMPLY_DEDENT) 119 120def compile_command(source, filename="<input>", symbol="single"): 121 r"""Compile a command and determine whether it is incomplete. 122 123 Arguments: 124 125 source -- the source string; may contain \n characters 126 filename -- optional filename from which source was read; default 127 "<input>" 128 symbol -- optional grammar start symbol; "single" (default), "exec" 129 or "eval" 130 131 Return value / exceptions raised: 132 133 - Return a code object if the command is complete and valid 134 - Return None if the command is incomplete 135 - Raise SyntaxError, ValueError or OverflowError if the command is a 136 syntax error (OverflowError and ValueError can be produced by 137 malformed literals). 138 """ 139 return _maybe_compile(_compile, source, filename, symbol) 140 141class Compile: 142 """Instances of this class behave much like the built-in compile 143 function, but if one is used to compile text containing a future 144 statement, it "remembers" and compiles all subsequent program texts 145 with the statement in force.""" 146 def __init__(self): 147 self.flags = PyCF_DONT_IMPLY_DEDENT 148 149 def __call__(self, source, filename, symbol): 150 codeob = compile(source, filename, symbol, self.flags, True) 151 for feature in _features: 152 if codeob.co_flags & feature.compiler_flag: 153 self.flags |= feature.compiler_flag 154 return codeob 155 156class CommandCompiler: 157 """Instances of this class have __call__ methods identical in 158 signature to compile_command; the difference is that if the 159 instance compiles program text containing a __future__ statement, 160 the instance 'remembers' and compiles all subsequent program texts 161 with the statement in force.""" 162 163 def __init__(self,): 164 self.compiler = Compile() 165 166 def __call__(self, source, filename="<input>", symbol="single"): 167 r"""Compile a command and determine whether it is incomplete. 168 169 Arguments: 170 171 source -- the source string; may contain \n characters 172 filename -- optional filename from which source was read; 173 default "<input>" 174 symbol -- optional grammar start symbol; "single" (default) or 175 "eval" 176 177 Return value / exceptions raised: 178 179 - Return a code object if the command is complete and valid 180 - Return None if the command is incomplete 181 - Raise SyntaxError, ValueError or OverflowError if the command is a 182 syntax error (OverflowError and ValueError can be produced by 183 malformed literals). 184 """ 185 return _maybe_compile(self.compiler, source, filename, symbol) 186