codeop

Utilities to compile possibly incomplete Python source code.

This module provides two interfaces, broadly similar to the builtin function compile(), which take program text, a filename and a ‘mode’ and:

• Return code object if the command is complete and valid
• Return None if the command is incomplete
• Raise SyntaxError, ValueError or OverflowError if the command is a syntax error (OverflowError and ValueError can be produced by malformed literals).

Approach:

First, check if the source consists entirely of blank lines and comments; if so, replace it with ‘pass’, because the built-in parser doesn’t always do the right thing for these.

Compile three times: as is, with n, and with nn appended. If it compiles as is, it’s complete. If it compiles with one n appended, we expect more. If it doesn’t compile either way, we compare the error we get when compiling with n or nn appended. If the errors are the same, the code is broken. But if the errors are different, we expect more. Not intuitive; not even guaranteed to hold in future releases; but this matches the compiler’s behavior from Python 1.4 through 2.2, at least.

Caveat:

It is possible (but not likely) that the parser stops parsing with a successful outcome before reaching the end of the source; in this case, trailing symbols may be ignored instead of causing an error. For example, a backslash followed by two newlines may be followed by arbitrary garbage. This will be fixed once the API for the parser is better.

The two interfaces are:

compile_command(source, filename, symbol):

Compiles a single command in the manner described above.

CommandCompiler():

Instances of this class have __call__ methods identical in signature to compile_command; the difference is that if the instance compiles program text containing a __future__ statement, the instance ‘remembers’ and compiles all subsequent program texts with the statement in force.

The module also provides another class:

Compile():

Instances of this class act like the built-in function compile, but with ‘memory’ in the sense described above.

Functions

compile_command(source[, filename, symbol])

Compile a command and determine whether it is incomplete.

Classes

CommandCompiler()	Instances of this class have __call__ methods identical in signature to compile_command; the difference is that if the instance compiles program text containing a __future__ statement, the instance ‘remembers’ and compiles all subsequent program texts with the statement in force.
Compile()	Instances of this class behave much like the built-in compile function, but if one is used to compile text containing a future statement, it “remembers” and compiles all subsequent program texts with the statement in force.