tokenize.md
1> **Источник:** https://python-all.ru/3.3/library/tokenize.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 31.7. [`tokenize`](https://python-all.ru/3.3/library/tokenize.html#module-tokenize) – Токенизатор исходного кода Python89**Исходный код:** [Lib/tokenize.py](https://python-all.ru/src/3.3/Lib/tokenize.py)1011---1213Модуль [`tokenize`](https://python-all.ru/3.3/library/tokenize.html#module-tokenize) предоставляет лексический анализатор для исходного кода Python, реализованный на Python. Этот анализатор также возвращает комментарии как токены, что делает его полезным для реализации «pretty-printers», включая раскраску для отображения на экране.1415Для упрощения обработки потока токенов все токены [*Операторов*](https://python-all.ru/3.3/reference/lexical_analysis.html#operators) и [*Разделителей*](https://python-all.ru/3.3/reference/lexical_analysis.html#delimiters) возвращаются с использованием общего типа токена [`token.OP`](https://python-all.ru/3.3/library/token.html#token.OP). Точный тип можно определить, проверив свойство `exact_type` в [*именованном кортеже*](https://python-all.ru/3.3/glossary.html#term-named-tuple), возвращаемом из [`tokenize.tokenize()`](https://python-all.ru/3.3/library/tokenize.html#tokenize.tokenize).1617## 31.7.1. Токенизация входных данных1819Основной точкой входа является [*генератор*](https://python-all.ru/3.3/glossary.html#term-generator):2021#### `tokenize.tokenize(readline)`2223Генератор [`tokenize()`](https://python-all.ru/3.3/library/tokenize.html#module-tokenize) требует один аргумент, *readline*, который должен быть вызываемым объектом, предоставляющим тот же интерфейс, что и метод [`io.IOBase.readline()`](https://python-all.ru/3.3/library/io.html#io.IOBase.readline) файловых объектов. Каждый вызов функции должен возвращать одну строку ввода в виде байтов.2425Генератор выдает 5-кортежи со следующими элементами: тип токена; строка токена; 2-кортеж `(srow, scol)` из целых чисел, указывающих строку и столбец начала токена в исходном коде; 2-кортеж `(erow, ecol)` из целых чисел, указывающих строку и столбец конца токена в исходном коде; и строку, в которой был найден токен. Передаваемая строка (последний элемент кортежа) является *логической* строкой; строки продолжения включены. 5-кортеж возвращается как [*именованный кортеж*](https://python-all.ru/3.3/glossary.html#term-named-tuple) с именами полей: `type string start end line`.2627Возвращаемый [*именованный кортеж*](https://python-all.ru/3.3/glossary.html#term-named-tuple) имеет дополнительное свойство с именем `exact_type`, которое содержит точный тип оператора для [`token.OP`](https://python-all.ru/3.3/library/token.html#token.OP) токенов. Для всех остальных типов токенов `exact_type` равна полю `type` именованного кортежа.2829Изменено в версии 3.1: Добавлена поддержка именованных кортежей.3031Изменено в версии 3.3: Добавлена поддержка `exact_type`.3233[`tokenize()`](https://python-all.ru/3.3/library/tokenize.html#module-tokenize) определяет кодировку исходного файла, ища BOM UTF-8 или cookie кодировки, в соответствии с [**PEP 263**](https://python-all.ru/3.3/library/tokenize.html).3435Все константы из модуля [`token`](https://python-all.ru/3.3/library/token.html#module-token) также экспортируются из [`tokenize`](https://python-all.ru/3.3/library/tokenize.html#module-tokenize), как и три дополнительных значения типа токена:3637#### `tokenize.COMMENT`3839Значение токена, используемое для обозначения комментария.4041#### `tokenize.NL`4243Значение токена, используемое для обозначения незавершающего перевода строки. Токен NEWLINE обозначает конец логической строки кода Python; токены NL создаются, когда логическая строка кода продолжается на нескольких физических строках.4445#### `tokenize.ENCODING`4647Значение токена, указывающее кодировку, используемую для декодирования исходных байтов в текст. Первый токен, возвращаемый [`tokenize()`](https://python-all.ru/3.3/library/tokenize.html#module-tokenize), всегда будет токеном ENCODING.4849Предоставляется ещё одна функция для обращения процесса токенизации. Это полезно для создания инструментов, которые токенизируют скрипт, изменяют поток токенов и записывают изменённый скрипт обратно.5051#### `tokenize.untokenize(iterable)`5253Преобразует токены обратно в исходный код Python. *Итерируемый объект* должен возвращать последовательности как минимум из двух элементов: типа токена и строки токена. Все дополнительные элементы последовательности игнорируются.5455Восстановленный скрипт возвращается в виде одной строки. Результат гарантированно токенизируется обратно в соответствии с входными данными, что обеспечивает преобразование без потерь и полную обратимость. Гарантия распространяется только на тип токена и строку токена, поскольку расстояния между токенами (позиции столбцов) могут измениться.5657Он возвращает байты, закодированные с использованием токена ENCODING, который является первой последовательностью токенов, выводимой [`tokenize()`](https://python-all.ru/3.3/library/tokenize.html#module-tokenize).5859[`tokenize()`](https://python-all.ru/3.3/library/tokenize.html#module-tokenize) необходимо определять кодировку исходных файлов, которые он токенизирует. Функция, которую он для этого использует, доступна:6061#### `tokenize.detect_encoding(readline)`6263Функция [`detect_encoding()`](https://python-all.ru/3.3/library/tokenize.html#tokenize.detect_encoding) используется для определения кодировки, которая должна использоваться для декодирования исходного файла Python. Она требует один аргумент, readline, так же, как и генератор [`tokenize()`](https://python-all.ru/3.3/library/tokenize.html#module-tokenize).6465Она вызовет readline максимум дважды и вернёт используемую кодировку (в виде строки) и список любых строк (не декодированных из байтов), которые она прочитала .6667Она определяет кодировку по наличию BOM UTF-8 или cookie кодировки, как указано в [**PEP 263**](https://python-all.ru/3.3/library/tokenize.html). Если присутствуют и BOM, и cookie, но они не согласуются, будет возбуждено SyntaxError. Обратите внимание, что если BOM найден, `'utf-8-sig'` будет возвращена как кодировка.6869Если кодировка не указана, то будет возвращена кодировка по умолчанию `'utf-8'`.7071Используйте [`open()`](https://python-all.ru/3.3/library/functions.html#open) для открытия исходных файлов Python: он использует [`detect_encoding()`](https://python-all.ru/3.3/library/tokenize.html#tokenize.detect_encoding) для определения кодировки файла.7273#### `tokenize.open(filename)`7475Открывает файл в режиме только для чтения, используя кодировку, определенную [`detect_encoding()`](https://python-all.ru/3.3/library/tokenize.html#tokenize.detect_encoding).7677Новое в версии 3.2.7879## 31.7.2. Использование из командной строки8081Новое в версии 3.3.8283Модуль [`tokenize`](https://python-all.ru/3.3/library/tokenize.html#module-tokenize) может быть выполнен как скрипт из командной строки. Это так же просто, как:8485```sh86python -m tokenize [-e] [filename.py]87```8889Принимаются следующие опции:9091#### `-h, --help`9293показывает это справочное сообщение и завершает работу9495#### `-e, --exact`9697отображает имена токенов с использованием точного типа9899Если указан `filename.py`, его содержимое токенизируется в stdout. В противном случае токенизация выполняется из stdin.100101## 31.7.3. Примеры102103Пример переписчика скриптов, преобразующего литералы чисел с плавающей запятой в объекты Decimal :104105```python106from tokenize import tokenize, untokenize, NUMBER, STRING, NAME, OP107from io import BytesIO108109def decistmt(s):110 """Заменяет значения float на Decimal.111112 >>> from decimal import Decimal113 >>> s = 'print(+21.3e-5*-.1234/81.7)'114 >>> decistmt(s)115 "print (+Decimal ('21.3e-5')*-Decimal ('.1234')/Decimal ('81.7'))"116117 Формат показателя степени наследуется от библиотеки C платформы.118 Известные случаи: "e-007" (Windows) и "e-07" (не Windows). Поскольку119 мы показываем только 12 цифр, а 13-я не близка к 5, остальная120 часть вывода должна быть независимой от платформы.121122 >>> exec(s) #doctest: +ELLIPSIS123 -3.21716034272e-0...7124125 Результаты вычислений с Decimal должны быть одинаковыми на всех126 платформах.127128 >>> exec(decistmt(s))129 -3.217160342717258261933904529E-7130 """131 result = []132 g = tokenize(BytesIO(s.encode('utf-8')).readline) # токенизировать строку133 for toknum, tokval, _, _, _ in g:134 if toknum == NUMBER and '.' in tokval: # заменить токены NUMBER135 result.extend([136 (NAME, 'Decimal'),137 (OP, '('),138 (STRING, repr(tokval)),139 (OP, ')')140 ])141 else:142 result.append((toknum, tokval))143 return untokenize(result).decode('utf-8')144```145146Пример токенизации из командной строки. Скрипт:147148```python149def say_hello():150 print("Hello, World!")151152say_hello()153```154155будет токенизирован в следующий вывод, где первый столбец – это диапазон координат строки/столбца, где найден токен, второй столбец – имя токена, а последний столбец – значение токена (если есть)156157```sh158$ python -m tokenize hello.py1590,0-0,0: ENCODING 'utf-8'1601,0-1,3: NAME 'def'1611,4-1,13: NAME 'say_hello'1621,13-1,14: OP '('1631,14-1,15: OP ')'1641,15-1,16: OP ':'1651,16-1,17: NEWLINE '\n'1662,0-2,4: INDENT ' '1672,4-2,9: NAME 'print'1682,9-2,10: OP '('1692,10-2,25: STRING '"Hello, World!"'1702,25-2,26: OP ')'1712,26-2,27: NEWLINE '\n'1723,0-3,1: NL '\n'1734,0-4,0: DEDENT ''1744,0-4,9: NAME 'say_hello'1754,9-4,10: OP '('1764,10-4,11: OP ')'1774,11-4,12: NEWLINE '\n'1785,0-5,0: ENDMARKER ''179```180181Точные имена типов токенов можно отобразить с помощью опции `-e`:182183```sh184$ python -m tokenize -e hello.py1850,0-0,0: ENCODING 'utf-8'1861,0-1,3: NAME 'def'1871,4-1,13: NAME 'say_hello'1881,13-1,14: LPAR '('1891,14-1,15: RPAR ')'1901,15-1,16: COLON ':'1911,16-1,17: NEWLINE '\n'1922,0-2,4: INDENT ' '1932,4-2,9: NAME 'print'1942,9-2,10: LPAR '('1952,10-2,25: STRING '"Hello, World!"'1962,25-2,26: RPAR ')'1972,26-2,27: NEWLINE '\n'1983,0-3,1: NL '\n'1994,0-4,0: DEDENT ''2004,0-4,9: NAME 'say_hello'2014,9-4,10: LPAR '('2024,10-4,11: RPAR ')'2034,11-4,12: NEWLINE '\n'2045,0-5,0: ENDMARKER ''205```206