code — базовые классы интерпретатора

Исходный код: Lib/code.py

Модуль code предоставляет средства для реализации циклов чтения-вычисления-вывода в Python. В него входят два класса и вспомогательные функции, с помощью которых можно создавать приложения с интерактивным приглашением интерпретатора.

class code.InteractiveInterpreter(locals=None): Этот класс отвечает за разбор кода и состояние интерпретатора (пространство имён пользователя); он не отвечает за буферизацию ввода, вывод приглашения или задание имени входного файла (имя файла всегда передаётся явно). Необязательный аргумент locals задаёт словарь, в котором будет выполняться код; по умолчанию создаётся новый словарь с ключом '__name__', которому присвоено значение '__console__', и ключом '__doc__', которому присвоено значение None.

class code.InteractiveConsole(locals=None, filename='<console>'): Точно имитирует поведение интерактивного интерпретатора Python. Этот класс расширяет InteractiveInterpreter, добавляя вывод знакомых приглашений sys.ps1 и sys.ps2, а также буферизацию ввода.

code.interact(banner=None, readfunc=None, local=None, exitmsg=None): Вспомогательная функция для запуска цикла чтения-вычисления-вывода. Она создаёт новый экземпляр InteractiveConsole и, если задан аргумент readfunc, использует его в качестве метода InteractiveConsole.raw_input(). Если задан аргумент local, он передаётся конструктору InteractiveConsole и используется как пространство имён по умолчанию для цикла интерпретатора. Затем вызывается метод экземпляра interact(), которому передаются аргументы banner и exitmsg для задания приветственного сообщения и сообщения при выходе, если они указаны. После использования объект консоли удаляется.

Изменено в версии 3.6: Добавлен параметр exitmsg.

code.compile_command(source, filename='<input>', symbol='single')

Эта функция полезна программам, которые хотят имитировать главный цикл интерпретатора Python (также называемый циклом чтения-вычисления-вывода). Сложность состоит в том, чтобы определить, ввёл ли пользователь неполную команду, которую можно завершить дополнительным текстом (в отличие от завершённой команды или синтаксической ошибки). Эта функция почти всегда принимает такое же решение, как и главный цикл настоящего интерпретатора.

source — исходная строка; filename — необязательное имя файла, из которого был прочитан исходный код; по умолчанию используется '<input>'; symbol — необязательный начальный символ грамматики, которым должен быть 'single' (по умолчанию), 'eval' или 'exec'.

Возвращает объект кода (такой же, как compile(source, filename, symbol)), если команда завершена и корректна; None, если команда не завершена; вызывает исключение SyntaxError, если команда завершена, но содержит синтаксическую ошибку, или исключение OverflowError либо ValueError, если команда содержит недопустимый литерал.

Объекты интерактивного интерпретатора

InteractiveInterpreter.runsource(source, filename='<input>', symbol='single')

Компилирует и выполняет исходный код в интерпретаторе. Аргументы такие же, как у compile_command(); значение filename по умолчанию — '<input>', а значение symbol — 'single'. Возможны следующие варианты:

Ввод некорректен; compile_command() вызвала исключение (SyntaxError или OverflowError). Трассировка синтаксической ошибки будет выведена вызовом метода showsyntaxerror(). Метод runsource() возвращает False.
Ввод не завершён и требуется дополнительный ввод; compile_command() вернула None. Метод runsource() возвращает True.
Ввод завершён; compile_command() вернула объект кода. Код выполняется вызовом метода runcode() (который также обрабатывает исключения времени выполнения, за исключением SystemExit). Метод runsource() возвращает False.

Возвращаемое значение можно использовать, чтобы решить, выводить ли sys.ps1 или sys.ps2 в качестве приглашения для следующей строки.

InteractiveInterpreter.runcode(code)

Выполняет объект кода. При возникновении исключения для вывода трассировки вызывается showtraceback(). Перехватываются все исключения, кроме SystemExit, которому разрешено распространяться дальше.

Примечание об KeyboardInterrupt: это исключение может возникнуть в другом месте кода, и его перехват не всегда гарантирован. Вызывающая сторона должна быть готова обработать его.

InteractiveInterpreter.showsyntaxerror(filename=None): Выводит только что возникшую синтаксическую ошибку. Трассировка стека не выводится, поскольку для синтаксических ошибок её нет. Если задан аргумент filename, он подставляется в исключение вместо имени файла по умолчанию, предоставляемого парсером Python, поскольку при чтении из строки парсер всегда использует '<string>'. Вывод выполняется методом write().

InteractiveInterpreter.showtraceback(): Выводит только что возникшее исключение. Первый элемент трассировки стека удаляется, поскольку он относится к реализации объекта интерпретатора. Вывод выполняется методом write().

Изменено в версии 3.5: Теперь отображается полная цепочка трассировок, а не только основная трассировка.

InteractiveInterpreter.write(data): Записывает строку в стандартный поток ошибок (sys.stderr). При необходимости производные классы должны переопределить этот метод, чтобы обеспечить соответствующую обработку вывода.

Объекты интерактивной консоли

Класс InteractiveConsole является подклассом InteractiveInterpreter, поэтому он предоставляет все методы объектов интерпретатора, а также следующие дополнительные методы.

InteractiveConsole.interact(banner=None, exitmsg=None)

Точно имитирует интерактивную консоль Python. Необязательный аргумент banner задаёт приветственное сообщение, выводимое перед первым взаимодействием; по умолчанию выводится сообщение, похожее на сообщение стандартного интерпретатора Python, за которым в скобках следует имя класса объекта консоли (чтобы его не путали с настоящим интерпретатором — ведь сходство очень велико!).

Необязательный аргумент exitmsg задаёт сообщение, выводимое при выходе. Передайте пустую строку, чтобы не выводить сообщение при выходе. Если аргумент exitmsg не задан или равен None, выводится сообщение по умолчанию.

Изменено в версии 3.4: Чтобы не выводить приветственное сообщение, передайте пустую строку.

Изменено в версии 3.6: При выходе выводится сообщение.

InteractiveConsole.push(line): Передаёт интерпретатору строку исходного текста. В конце строки не должно быть символа новой строки; внутри строки символы новой строки допускаются. Строка добавляется в буфер, после чего вызывается метод runsource() интерпретатора, которому в качестве исходного кода передаётся объединённое содержимое буфера. Если это указывает на то, что команда выполнена или некорректна, буфер очищается; в противном случае команда считается незавершённой, и буфер сохраняется в состоянии после добавления строки. Возвращаемое значение равно True, если требуется дополнительный ввод, и False, если строка была обработана каким-либо образом (это то же значение, что и runsource()).

InteractiveConsole.resetbuffer(): Удаляет из буфера ввода весь необработанный исходный текст.

InteractiveConsole.raw_input(prompt=''): Выводит приглашение и считывает строку. Возвращаемая строка не содержит завершающего символа новой строки. Когда пользователь вводит комбинацию клавиш EOF, возникает исключение EOFError. Базовая реализация считывает данные из sys.stdin; подкласс может заменить её другой реализацией.