Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 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 | |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 13 | The two interfaces are: |
| 14 | |
| 15 | compile_command(source, filename, symbol): |
| 16 | |
| 17 | Compiles a single command in the manner described above. |
| 18 | |
| 19 | CommandCompiler(): |
| 20 | |
| 21 | Instances of this class have __call__ methods identical in |
| 22 | signature to compile_command; the difference is that if the |
| 23 | instance compiles program text containing a __future__ statement, |
| 24 | the instance 'remembers' and compiles all subsequent program texts |
| 25 | with the statement in force. |
| 26 | |
| 27 | The module also provides another class: |
| 28 | |
| 29 | Compile(): |
| 30 | |
| 31 | Instances of this class act like the built-in function compile, |
| 32 | but with 'memory' in the sense described above. |
| 33 | """ |
| 34 | |
| 35 | import __future__ |
| 36 | import warnings |
| 37 | |
| 38 | _features = [getattr(__future__, fname) |
| 39 | for fname in __future__.all_feature_names] |
| 40 | |
| 41 | __all__ = ["compile_command", "Compile", "CommandCompiler"] |
| 42 | |
Dan Willemsen | c9fa001 | 2022-03-25 22:58:53 +0000 | [diff] [blame] | 43 | # The following flags match the values from Include/cpython/compile.h |
| 44 | # Caveat emptor: These flags are undocumented on purpose and depending |
| 45 | # on their effect outside the standard library is **unsupported**. |
| 46 | PyCF_DONT_IMPLY_DEDENT = 0x200 |
| 47 | PyCF_ALLOW_INCOMPLETE_INPUT = 0x4000 |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 48 | |
| 49 | def _maybe_compile(compiler, source, filename, symbol): |
Dan Willemsen | c9fa001 | 2022-03-25 22:58:53 +0000 | [diff] [blame] | 50 | # Check for source consisting of only blank lines and comments. |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 51 | for line in source.split("\n"): |
| 52 | line = line.strip() |
| 53 | if line and line[0] != '#': |
Dan Willemsen | c9fa001 | 2022-03-25 22:58:53 +0000 | [diff] [blame] | 54 | break # Leave it alone. |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 55 | else: |
| 56 | if symbol != "eval": |
| 57 | source = "pass" # Replace it with a 'pass' statement |
| 58 | |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 59 | try: |
Dan Willemsen | c9fa001 | 2022-03-25 22:58:53 +0000 | [diff] [blame] | 60 | return compiler(source, filename, symbol) |
| 61 | except SyntaxError: # Let other compile() errors propagate. |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 62 | pass |
| 63 | |
Elliott Hughes | 96c2b6b | 2021-01-26 11:15:15 -0800 | [diff] [blame] | 64 | # Catch syntax warnings after the first compile |
| 65 | # to emit warnings (SyntaxWarning, DeprecationWarning) at most once. |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 66 | with warnings.catch_warnings(): |
Elliott Hughes | 96c2b6b | 2021-01-26 11:15:15 -0800 | [diff] [blame] | 67 | warnings.simplefilter("error") |
| 68 | |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 69 | try: |
Dan Willemsen | c9fa001 | 2022-03-25 22:58:53 +0000 | [diff] [blame] | 70 | compiler(source + "\n", filename, symbol) |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 71 | except SyntaxError as e: |
Dan Willemsen | c9fa001 | 2022-03-25 22:58:53 +0000 | [diff] [blame] | 72 | if "incomplete input" in str(e): |
| 73 | return None |
| 74 | raise |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 75 | |
Dan Willemsen | c9fa001 | 2022-03-25 22:58:53 +0000 | [diff] [blame] | 76 | def _is_syntax_error(err1, err2): |
| 77 | rep1 = repr(err1) |
| 78 | rep2 = repr(err2) |
| 79 | if "was never closed" in rep1 and "was never closed" in rep2: |
| 80 | return False |
| 81 | if rep1 == rep2: |
| 82 | return True |
| 83 | return False |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 84 | |
| 85 | def _compile(source, filename, symbol): |
Dan Willemsen | c9fa001 | 2022-03-25 22:58:53 +0000 | [diff] [blame] | 86 | return compile(source, filename, symbol, PyCF_DONT_IMPLY_DEDENT | PyCF_ALLOW_INCOMPLETE_INPUT) |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 87 | |
| 88 | def compile_command(source, filename="<input>", symbol="single"): |
| 89 | r"""Compile a command and determine whether it is incomplete. |
| 90 | |
| 91 | Arguments: |
| 92 | |
| 93 | source -- the source string; may contain \n characters |
| 94 | filename -- optional filename from which source was read; default |
| 95 | "<input>" |
| 96 | symbol -- optional grammar start symbol; "single" (default), "exec" |
| 97 | or "eval" |
| 98 | |
| 99 | Return value / exceptions raised: |
| 100 | |
| 101 | - Return a code object if the command is complete and valid |
| 102 | - Return None if the command is incomplete |
| 103 | - Raise SyntaxError, ValueError or OverflowError if the command is a |
| 104 | syntax error (OverflowError and ValueError can be produced by |
| 105 | malformed literals). |
| 106 | """ |
| 107 | return _maybe_compile(_compile, source, filename, symbol) |
| 108 | |
| 109 | class Compile: |
| 110 | """Instances of this class behave much like the built-in compile |
| 111 | function, but if one is used to compile text containing a future |
| 112 | statement, it "remembers" and compiles all subsequent program texts |
| 113 | with the statement in force.""" |
| 114 | def __init__(self): |
Dan Willemsen | c9fa001 | 2022-03-25 22:58:53 +0000 | [diff] [blame] | 115 | self.flags = PyCF_DONT_IMPLY_DEDENT | PyCF_ALLOW_INCOMPLETE_INPUT |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 116 | |
| 117 | def __call__(self, source, filename, symbol): |
Elliott Hughes | 96c2b6b | 2021-01-26 11:15:15 -0800 | [diff] [blame] | 118 | codeob = compile(source, filename, symbol, self.flags, True) |
Jingwen Chen | 475b3cc | 2021-01-05 21:45:16 -0500 | [diff] [blame] | 119 | for feature in _features: |
| 120 | if codeob.co_flags & feature.compiler_flag: |
| 121 | self.flags |= feature.compiler_flag |
| 122 | return codeob |
| 123 | |
| 124 | class CommandCompiler: |
| 125 | """Instances of this class have __call__ methods identical in |
| 126 | signature to compile_command; the difference is that if the |
| 127 | instance compiles program text containing a __future__ statement, |
| 128 | the instance 'remembers' and compiles all subsequent program texts |
| 129 | with the statement in force.""" |
| 130 | |
| 131 | def __init__(self,): |
| 132 | self.compiler = Compile() |
| 133 | |
| 134 | def __call__(self, source, filename="<input>", symbol="single"): |
| 135 | r"""Compile a command and determine whether it is incomplete. |
| 136 | |
| 137 | Arguments: |
| 138 | |
| 139 | source -- the source string; may contain \n characters |
| 140 | filename -- optional filename from which source was read; |
| 141 | default "<input>" |
| 142 | symbol -- optional grammar start symbol; "single" (default) or |
| 143 | "eval" |
| 144 | |
| 145 | Return value / exceptions raised: |
| 146 | |
| 147 | - Return a code object if the command is complete and valid |
| 148 | - Return None if the command is incomplete |
| 149 | - Raise SyntaxError, ValueError or OverflowError if the command is a |
| 150 | syntax error (OverflowError and ValueError can be produced by |
| 151 | malformed literals). |
| 152 | """ |
| 153 | return _maybe_compile(self.compiler, source, filename, symbol) |