parser — Доступ к синтаксическим деревьям Python

Создание объектов ST

Объекты 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(). Этот входной пункт поддерживается для обратной совместимости.

Преобразование объектов ST

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

parser.st2list(st, line_info=False, col_info=False)

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

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

parser.st2tuple(st, line_info=False, col_info=False)

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

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

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

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

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

Запросы к объектам ST

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

parser.isexpr(st)

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

parser.issuite(st)

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

Исключения и обработка ошибок

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

exception parser.ParserError

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

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

Объекты ST

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

parser.STType

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

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

ST.compile(filename='<syntax-tree>')

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

ST.isexpr()

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

ST.issuite()

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

ST.tolist(line_info=False, col_info=False)

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

ST.totuple(line_info=False, col_info=False)

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

Пример: Эмуляция 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()