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