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    err = err1 = err2 = None
80    code = code1 = code2 = None
81
82    try:
83        code = compiler(source, filename, symbol)
84    except SyntaxError as err:
85        pass
86
87    # Catch syntax warnings after the first compile
88    # to emit warnings (SyntaxWarning, DeprecationWarning) at most once.
89    with warnings.catch_warnings():
90        warnings.simplefilter("error")
91
92        try:
93            code1 = compiler(source + "\n", filename, symbol)
94        except SyntaxError as e:
95            err1 = e
96
97        try:
98            code2 = compiler(source + "\n\n", filename, symbol)
99        except SyntaxError as e:
100            err2 = e
101
102    try:
103        if code:
104            return code
105        if not code1 and repr(err1) == repr(err2):
106            raise err1
107    finally:
108        err1 = err2 = None
109
110def _compile(source, filename, symbol):
111    return compile(source, filename, symbol, PyCF_DONT_IMPLY_DEDENT)
112
113def compile_command(source, filename="<input>", symbol="single"):
114    r"""Compile a command and determine whether it is incomplete.
115
116    Arguments:
117
118    source -- the source string; may contain \n characters
119    filename -- optional filename from which source was read; default
120                "<input>"
121    symbol -- optional grammar start symbol; "single" (default), "exec"
122              or "eval"
123
124    Return value / exceptions raised:
125
126    - Return a code object if the command is complete and valid
127    - Return None if the command is incomplete
128    - Raise SyntaxError, ValueError or OverflowError if the command is a
129      syntax error (OverflowError and ValueError can be produced by
130      malformed literals).
131    """
132    return _maybe_compile(_compile, source, filename, symbol)
133
134class Compile:
135    """Instances of this class behave much like the built-in compile
136    function, but if one is used to compile text containing a future
137    statement, it "remembers" and compiles all subsequent program texts
138    with the statement in force."""
139    def __init__(self):
140        self.flags = PyCF_DONT_IMPLY_DEDENT
141
142    def __call__(self, source, filename, symbol):
143        codeob = compile(source, filename, symbol, self.flags, 1)
144        for feature in _features:
145            if codeob.co_flags & feature.compiler_flag:
146                self.flags |= feature.compiler_flag
147        return codeob
148
149class CommandCompiler:
150    """Instances of this class have __call__ methods identical in
151    signature to compile_command; the difference is that if the
152    instance compiles program text containing a __future__ statement,
153    the instance 'remembers' and compiles all subsequent program texts
154    with the statement in force."""
155
156    def __init__(self,):
157        self.compiler = Compile()
158
159    def __call__(self, source, filename="<input>", symbol="single"):
160        r"""Compile a command and determine whether it is incomplete.
161
162        Arguments:
163
164        source -- the source string; may contain \n characters
165        filename -- optional filename from which source was read;
166                    default "<input>"
167        symbol -- optional grammar start symbol; "single" (default) or
168                  "eval"
169
170        Return value / exceptions raised:
171
172        - Return a code object if the command is complete and valid
173        - Return None if the command is incomplete
174        - Raise SyntaxError, ValueError or OverflowError if the command is a
175          syntax error (OverflowError and ValueError can be produced by
176          malformed literals).
177        """
178        return _maybe_compile(self.compiler, source, filename, symbol)
179