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()