32.1. parser – Доступ к деревьям разбора Python¶parser – Access Python parse trees

32.1.1. Создание объектов ST¶Creating ST Objects

ST-объекты могут быть созданы из исходного кода или из дерева разбора. При создании ST-объекта из исходного кода используются разные функции для создания форм 'eval' и 'exec'.

parser.expr(source)¶

Функция expr() анализирует параметр source так, как если бы он был входными данными для compile(source, 'file.py', 'eval'). В случае успешного разбора создаётся ST-объект для хранения внутреннего представления дерева разбора, в противном случае возбуждается соответствующее исключение.

parser.suite(source)¶

Функция suite() анализирует параметр source так, как если бы он был входными данными для compile(source, 'file.py', 'exec'). В случае успешного разбора создаётся ST-объект для хранения внутреннего представления дерева разбора, в противном случае возбуждается соответствующее исключение.

parser.sequence2st(sequence)¶

Эта функция принимает дерево разбора, представленное в виде последовательности, и, если возможно, строит внутреннее представление. Если удаётся проверить, что дерево соответствует грамматике Python и все узлы являются допустимыми типами узлов в текущей версии Python, из внутреннего представления создаётся ST-объект и возвращается вызывающему. Если при создании внутреннего представления возникла проблема или дерево не прошло проверку, возбуждается исключение ParserError. Не следует предполагать, что ST-объект, созданный таким образом, скомпилируется корректно; обычные исключения, возбуждаемые при компиляции, могут возникнуть при передаче ST-объекта функции compilest(). Это может указывать на проблемы, не связанные с синтаксисом (например, исключение MemoryError), но также может быть связано с конструкциями вроде результата разбора del f(0), который ускользает от парсера Python, но проверяется компилятором байт-кода.

Последовательности, представляющие терминальные токены, могут быть представлены либо двухэлементными списками вида (1, 'name'), либо трёхэлементными списками вида (1, 'name', 56). Если присутствует третий элемент, он считается допустимым номером строки. Номер строки может быть указан для любого подмножества терминальных символов во входном дереве.

parser.tuple2st(sequence)¶

Это та же функция, что и sequence2st(). Данная точка входа сохраняется для обратной совместимости.

32.1.2. Преобразование объектов ST¶Converting ST Objects

ST-объекты, независимо от входных данных, использованных для их создания, могут быть преобразованы в деревья разбора, представленные в виде списков или кортежей, или скомпилированы в исполняемые объекты кода. Деревья разбора могут быть извлечены с информацией о номерах строк или без неё.

parser.st2list(ast[, line_info])¶

Эта функция принимает объект ST от вызывающей стороны в ast и возвращает список Python, представляющий эквивалентное дерево разбора. Полученное представление в виде списка можно использовать для просмотра или создания нового дерева разбора в виде списка. Эта функция не завершается ошибкой, пока достаточно памяти для построения спискового представления. Если дерево разбора будет использоваться только для просмотра, вместо этого следует использовать st2tuple() для уменьшения расхода памяти и фрагментации. Когда требуется представление в виде списка, эта функция значительно быстрее, чем получение кортежного представления и преобразование его во вложенные списки.

Если line_info равен true, для всех терминальных токенов будет включена информация о номере строки в качестве третьего элемента списка, представляющего токен. Обратите внимание, что указанный номер строки определяет строку, в которой токен заканчивается. Эта информация опускается, если флаг равен false или опущен.

parser.st2tuple(ast[, line_info])¶

Эта функция принимает объект ST от вызывающей стороны в ast и возвращает кортеж Python, представляющий эквивалентное дерево разбора. За исключением того, что возвращает кортеж вместо списка, эта функция идентична st2list().

Если line_info равен true, для всех терминальных токенов будет включена информация о номере строки в качестве третьего элемента списка, представляющего токен. Эта информация опускается, если флаг равен false или опущен.

parser.compilest(ast, filename='<syntax-tree>')¶

Байт-компилятор Python можно вызвать для объекта ST, чтобы получить объекты кода, которые можно использовать в операторе exec или вызове встроенной функции eval(). Эта функция предоставляет интерфейс к компилятору, передавая внутреннее дерево разбора из ast анализатору, используя имя исходного файла, заданное параметром filename. Значение по умолчанию, указанное для filename, указывает, что исходный код был объектом ST.

Компиляция объекта ST может привести к исключениям, связанным с компиляцией; примером может служить SyntaxError, вызванное синтаксическим деревом для del f(0): этот оператор считается допустимым в формальной грамматике Python, но не является допустимой языковой конструкцией. SyntaxError, возбуждаемое для такой ситуации, на самом деле обычно генерируется байт-компилятором Python, поэтому оно может быть возбуждено на этом этапе модулем parser. Большинство причин сбоя компиляции можно диагностировать программно, проверив синтаксическое дерево.

32.1.3. Запросы к объектам ST¶Queries on ST Objects

Предоставляются две функции, которые позволяют приложению определить, был ли ST создан как выражение или как блок. Ни одна из этих функций не может быть использована для определения того, был ли ST создан из исходного кода через expr() или suite(), или из синтаксического дерева через sequence2st().

parser.isexpr(ast)¶

Когда ast представляет форму 'eval', эта функция возвращает true, иначе false. Это полезно, поскольку объекты кода обычно нельзя запросить об этой информации с помощью существующих встроенных функций. Обратите внимание, что объекты кода, созданные compilest(), также нельзя так запросить, и они идентичны тем, что создаются встроенной функцией compile().

parser.issuite(ast)¶

Эта функция аналогична isexpr() в том, что она сообщает, представляет ли объект ST форму 'exec', обычно называемую "блоком". Небезопасно предполагать, что эта функция эквивалентна not isexpr(ast), так как в будущем могут поддерживаться дополнительные синтаксические фрагменты.

32.1.4. Исключения и обработка ошибок¶Exceptions and Error Handling

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

exception parser.ParserError¶

Исключение, возбуждаемое при сбое в модуле parser. Обычно оно возникает из-за ошибок валидации, а не из-за встроенного исключения SyntaxError, возбуждаемого при обычном разборе. Аргумент исключения – либо строка, описывающая причину сбоя, либо кортеж, содержащий последовательность, вызвавшую сбой (из синтаксического дерева, переданного в sequence2st()), и пояснительную строку. Вызовы sequence2st() должны уметь обрабатывать оба типа исключений, в то время как вызовы других функций модуля должны быть готовы только к простым строковым значениям.

Обратите внимание, что функции compilest(), expr() и suite() могут возбуждать исключения, которые обычно возбуждаются в процессе разбора и компиляции. К ним относятся встроенные исключения MemoryError, OverflowError, SyntaxError и SystemError. В этих случаях такие исключения несут всю обычную смысловую нагрузку. За подробной информацией обращайтесь к описанию каждой функции.

32.1.5. Объекты ST¶ST Objects

Поддерживаются упорядоченные сравнения и сравнения на равенство между объектами ST. Также поддерживается сериализация объектов ST (с помощью модуля pickle).

parser.STType¶

Тип объектов, возвращаемых функциями expr(), suite() и sequence2st().

Объекты ST имеют следующие методы:

ST.compile([filename])¶

То же, что и compilest(st, filename).

ST.isexpr()¶

То же, что и isexpr(st).

ST.issuite()¶

То же, что и issuite(st).

ST.tolist([line_info])¶

То же, что и st2list(st, line_info).

ST.totuple([line_info])¶

То же, что и st2tuple(st, line_info).

32.1.6. Пример: эмуляция compile()¶Example: Emulation of compile()

Хотя между разбором и генерацией байт-кода может выполняться множество полезных операций, самая простая операция – ничего не делать. Для этой цели использование модуля parser для создания промежуточной структуры данных эквивалентно коду

>>> code = compile('a + 5', 'file.py', 'eval')
>>> a = 5
>>> eval(code)
10

Эквивалентная операция с использованием модуля parser несколько длиннее и позволяет сохранить промежуточное внутреннее синтаксическое дерево в виде объекта ST:

>>> import parser
>>> st = parser.expr('a + 5')
>>> code = st.compile('file.py')
>>> a = 5
>>> eval(code)
10

Приложение, которому нужны как объекты ST, так и объекты кода, может упаковать этот код в готовые функции:

import parser

def load_suite(source_string):
    st = parser.suite(source_string)
    return st, st.compile()

def load_expression(source_string):
    st = parser.expr(source_string)
    return st, st.compile()