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=''): Выводит приглашение и считывает строку. Возвращаемая строка не включает завершающий символ новой строки. Когда пользователь вводит последовательность клавиш конца файла, вызывается исключение EOFError. Базовая реализация считывает данные из sys.stdin; подкласс может заменить её другой реализацией.