Lib/codeop.py

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