tokenize — Токенизатор для исходного кода Python

Исходный код: Lib/tokenize.py

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

Для упрощения обработки потока токенов все операторы и разделители токены возвращаются с помощью универсального типа токена token.OP. Точный тип можно определить, проверив второе поле (содержащее фактическую строку совпавшего токена) кортежа, возвращаемого из tokenize.generate_tokens() для последовательности символов, которая идентифицирует конкретный токен оператора.

Основной точкой входа является генератор:

tokenize.generate_tokens(readline)

Генератор generate_tokens() принимает один аргумент, readline, который должен быть вызываемым объектом, предоставляющим тот же интерфейс, что и метод readline() встроенных объектов файлов (см. раздел Объекты файлов). Каждый вызов функции должен возвращать одну строку ввода в качестве строки. В качестве альтернативы, readline может быть вызываемым объектом, который сигнализирует об окончании, выбросив StopIteration.

Генератор производит 5-кортежи с этими членами: тип токена; строка токена; 2-кортеж (srow, scol) целых чисел, указывающих строку и столбец, где начинается токен в исходном коде; 2-кортеж (erow, ecol) целых чисел, указывающих строку и столбец, где заканчивается токен в исходном коде; и строка, в которой найден токен. Переданная строка (последний элемент кортежа) — это логическая строка; строки продолжения включаются.

Введено в версии 2.2.

Для обеспечения обратной совместимости сохраняется более старая точка входа:

tokenize.tokenize(readline[, tokeneater])

Функция tokenize() принимает два параметра: один, представляющий поток ввода, и один, предоставляющий механизм вывода для tokenize().

Первый параметр, readline, должен быть вызываемым объектом, предоставляющим тот же интерфейс, что и метод readline() встроенных объектов файлов (см. раздел Объекты файлов). Каждый вызов функции должен возвращать одну строку ввода в качестве строки. В качестве альтернативы, readline может быть вызываемым объектом, который сигнализирует об окончании, выбросив StopIteration.

Изменено в версии 2.5: Добавлена поддержка StopIteration.

Второй параметр, tokeneater, также должен быть вызываемым объектом. Он вызывается один раз для каждого токена с пятью аргументами, соответствующими кортежам, сгенерированным generate_tokens().

Все константы из модуля token также экспортируются из tokenize, как и два дополнительных значения типа токена, которые могут быть переданы функции tokeneater функцией tokenize():

tokenize.COMMENT

Значение токена, используемое для обозначения комментария.

tokenize.NL

Значение токена, используемое для обозначения нетерминирующей новой строки. Токен NEWLINE указывает конец логической строки кода Python; токены NL генерируются, когда логическая строка кода продолжается на нескольких физических строках.

Для обратной операции токенизации предоставляется еще одна функция. Это полезно для создания инструментов, которые токенизируют скрипт, изменяют поток токенов и записывают обратно измененный скрипт.

tokenize.untokenize(iterable)

Преобразует токены обратно в исходный код Python. Итерируемый объект должен возвращать последовательности, содержащие как минимум два элемента: тип токена и строку токена. Любые дополнительные элементы последовательности игнорируются.

Восстановленный скрипт возвращается в виде одной строки. Результат гарантированно возвращает токенизацию, соответствующую входным данным, так что преобразование является без потерь и гарантирует обратные преобразования. Гарантия распространяется только на тип токена и строку токена, так как пробелы между токенами (позиции столбцов) могут изменяться.

Введено в версии 2.5.

exception tokenize.TokenError

Вызывается, когда либо строка документации, либо выражение, которое может быть разделено на несколько строк, не завершено нигде в файле, например:

"""Beginning of
docstring

или:

[1,
 2,
 3

Обратите внимание, что незакрытые строки в одинарных кавычках не вызывают ошибку. Они токенизируются как ERRORTOKEN, за которым следует токенизация их содержимого.

Пример скрипта-переработчика, который преобразует числовые литералы с плавающей точкой в объекты Decimal:

def decistmt(s):
    """Substitute Decimals for floats in a string of statements.

    >>> from decimal import Decimal
    >>> s = 'print +21.3e-5*-.1234/81.7'
    >>> decistmt(s)
    "print +Decimal ('21.3e-5')*-Decimal ('.1234')/Decimal ('81.7')"

    >>> exec(s)
    -3.21716034272e-007
    >>> exec(decistmt(s))
    -3.217160342717258261933904529E-7

    """
    result = []
    g = generate_tokens(StringIO(s).readline)   # tokenize the string
    for toknum, tokval, _, _, _  in g:
        if toknum == NUMBER and '.' in tokval:  # replace NUMBER tokens
            result.extend([
                (NAME, 'Decimal'),
                (OP, '('),
                (STRING, repr(tokval)),
                (OP, ')')
            ])
        else:
            result.append((toknum, tokval))
    return untokenize(result)