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(), that take progam text, a filename and a 'mode'
   5 and:
   6
   7 - Return a 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 def _maybe_compile(compiler, source, filename, symbol):
  67     # Check for source consisting of only blank lines and comments
  68     for line in source.split("\n"):
  69         line = line.strip()
  70         if line and line[0] != '#':
  71             break               # Leave it alone
  72     else:
  73         source = "pass"         # Replace it with a 'pass' statement
  74
  75     err = err1 = err2 = None
  76     code = code1 = code2 = None
  77
  78     try:
  79         code = compiler(source, filename, symbol)
  80     except SyntaxError, err:
  81         pass
  82
  83     try:
  84         code1 = compiler(source + "\n", filename, symbol)
  85     except SyntaxError, err1:
  86         pass
  87
  88     try:
  89         code2 = compiler(source + "\n\n", filename, symbol)
  90     except SyntaxError, err2:
  91         pass
  92
  93     if code:
  94         return code
  95     try:
  96         e1 = err1.__dict__
  97     except AttributeError:
  98         e1 = err1
  99     try:
 100         e2 = err2.__dict__
 101     except AttributeError:
 102         e2 = err2
 103     if not code1 and e1 == e2:
 104         raise SyntaxError, err1
 105
 106 def compile_command(source, filename="<input>", symbol="single"):
 107     r"""Compile a command and determine whether it is incomplete.
 108
 109     Arguments:
 110
 111     source -- the source string; may contain \n characters
 112     filename -- optional filename from which source was read; default
 113                 "<input>"
 114     symbol -- optional grammar start symbol; "single" (default) or "eval"
 115
 116     Return value / exceptions raised:
 117
 118     - Return a code object if the command is complete and valid
 119     - Return None if the command is incomplete
 120     - Raise SyntaxError, ValueError or OverflowError if the command is a
 121       syntax error (OverflowError and ValueError can be produced by
 122       malformed literals).
 123     """
 124     return _maybe_compile(compile, source, filename, symbol)
 125
 126 class Compile:
 127     """Instances of this class behave much like the built-in compile
 128     function, but if one is used to compile text containing a future
 129     statement, it "remembers" and compiles all subsequent program texts
 130     with the statement in force."""
 131     def __init__(self):
 132         self.flags = 0
 133
 134     def __call__(self, source, filename, symbol):
 135         codeob = compile(source, filename, symbol, self.flags, 1)
 136         for feature in _features:
 137             if codeob.co_flags & feature.compiler_flag:
 138                 self.flags |= feature.compiler_flag
 139         return codeob
 140
 141 class CommandCompiler:
 142     """Instances of this class have __call__ methods identical in
 143     signature to compile_command; the difference is that if the
 144     instance compiles program text containing a __future__ statement,
 145     the instance 'remembers' and compiles all subsequent program texts
 146     with the statement in force."""
 147
 148     def __init__(self,):
 149         self.compiler = Compile()
 150
 151     def __call__(self, source, filename="<input>", symbol="single"):
 152         r"""Compile a command and determine whether it is incomplete.
 153
 154         Arguments:
 155
 156         source -- the source string; may contain \n characters
 157         filename -- optional filename from which source was read;
 158                     default "<input>"
 159         symbol -- optional grammar start symbol; "single" (default) or
 160                   "eval"
 161
 162         Return value / exceptions raised:
 163
 164         - Return a code object if the command is complete and valid
 165         - Return None if the command is incomplete
 166         - Raise SyntaxError, ValueError or OverflowError if the command is a
 167           syntax error (OverflowError and ValueError can be produced by
 168           malformed literals).
 169         """
 170         return _maybe_compile(self.compiler, source, filename, symbol)