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