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

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

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

class code.InteractiveInterpreter(locals=None)

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

Обратите внимание, что функции и объекты классов, созданные в экземпляре InteractiveInterpreter, будут принадлежать пространству имён, заданному аргументом locals. Их можно сериализовать с помощью pickle, только если locals — пространство имён существующего модуля.

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

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

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

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

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

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; подкласс может заменить её другой реализацией.