shlex.md

1> **Источник:** https://python-all.ru/2.7/library/shlex.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 23.2. [`shlex`](https://python-all.ru/2.7/library/shlex.html#module-shlex) – Простой лексический анализ89Новое в версии 1.5.2.1011**Исходный код:** [Lib/shlex.py](https://python-all.ru/src/2.7/Lib/shlex.py)1213---1415Класс [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) упрощает написание лексических анализаторов для синтаксиса, напоминающего синтаксис оболочки Unix. Это часто бывает полезно для создания мини-языков (например, в конфигурационных файлах приложений Python) или для разбора строк в кавычках.1617До Python 2.7.3 этот модуль не поддерживал ввод Unicode.1819Модуль [`shlex`](https://python-all.ru/2.7/library/shlex.html#module-shlex) определяет следующие функции:2021#### `shlex.split(s[, comments[, posix]])`2223Разделяет строку *s*, используя синтаксис, подобный оболочке. Если *comments* равно [`False`](https://python-all.ru/2.7/library/constants.html#False) (по умолчанию), разбор комментариев в заданной строке будет отключён (устанавливает атрибут [`commenters`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.commenters) экземпляра [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) в пустую строку). Эта функция работает в режиме POSIX по умолчанию, но использует не-POSIX режим, если аргумент *posix* равен False.2425Новое в версии 2.3.2627Изменено в версии 2.6: Добавлен параметр *posix*.2829> **Примечание**30>31> Поскольку функция [`split()`](https://python-all.ru/2.7/library/shlex.html#shlex.split) создаёт экземпляр [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) , передача `None` в качестве *s* будет читать строку для разбиения из стандартного ввода.3233Модуль [`shlex`](https://python-all.ru/2.7/library/shlex.html#module-shlex) определяет следующий класс:3435#### `class shlex.shlex([instream[, infile[, posix]]])`3637Экземпляр [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) или его подкласса является объектом лексического анализатора. Аргумент инициализации, если он указан, определяет источник символов. Это должен быть объект, подобный файлу или потоку, с методами [`read()`](https://python-all.ru/2.7/library/io.html#io.TextIOBase.read) и [`readline()`](https://python-all.ru/2.7/library/io.html#io.TextIOBase.readline), или строка (строки поддерживаются начиная с Python 2.3). Если аргумент не указан, ввод будет производиться из `sys.stdin`. Второй необязательный аргумент – строка имени файла, которая задаёт начальное значение атрибута [`infile`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.infile). Если аргумент *instream* опущен или равен `sys.stdin`, этот второй аргумент по умолчанию равен «stdin». Аргумент *posix* был введён в Python 2.3 и определяет режим работы. Если *posix* не истинно (по умолчанию), экземпляр [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) будет работать в режиме совместимости. При работе в режиме POSIX [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) будет стараться максимально точно следовать правилам разбора командной оболочки POSIX.3839> **См. также**40>41> **Модуль [`ConfigParser`](https://python-all.ru/2.7/library/configparser.html#module-ConfigParser)**42>43> Синтаксический анализатор конфигурационных файлов, аналогичных файлам `.ini` в Windows.4445## 23.2.1. Объекты shlex4647Экземпляр [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) имеет следующие методы:4849#### `shlex.get_token()`5051Возвращает токен. Если токены были помещены в стек с помощью [`push_token()`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.push_token), извлекает токен из стека. В противном случае читает один токен из входного потока. Если при чтении сразу встречается конец файла, возвращается [`eof`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.eof) (пустая строка (`''`) в не-POSIX режиме и `None` в режиме POSIX).5253#### `shlex.push_token(str)`5455Помещает аргумент в стек токенов.5657#### `shlex.read_token()`5859Читает сырой токен. Игнорирует стек возврата и не интерпретирует запросы источника. (Обычно это не является полезной точкой входа и документируется здесь только для полноты.)6061#### `shlex.sourcehook(filename)`6263Когда [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) обнаруживает запрос источника (см. [`source`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.source) ниже), этому методу передаётся следующий токен в качестве аргумента, и ожидается, что он вернёт кортеж, состоящий из имени файла и открытого файлоподобного объекта.6465Обычно этот метод сначала удаляет кавычки из аргумента. Если результат – абсолютный путь, или нет активного предыдущего запроса источника, или предыдущий источник был потоком данных (например, `sys.stdin`), результат остаётся без изменений. В противном случае, если результат – относительный путь, к нему добавляется часть пути каталога файла, находящегося непосредственно перед ним в стеке включения источников (такое поведение аналогично тому, как препроцессор C обрабатывает `#include "file.h"`).6667Результат этих действий трактуется как имя файла и возвращается в качестве первого компонента кортежа, а к нему применяется [`open()`](https://python-all.ru/2.7/library/functions.html#open) для получения второго компонента. (Примечание: это обратный порядок аргументов при инициализации экземпляра!)6869Этот хук предоставляется, чтобы вы могли использовать его для реализации путей поиска по каталогам, добавления расширений файлов и других трюков с пространствами имён. Соответствующего хука «закрытия» нет, но экземпляр shlex вызовет метод [`close()`](https://python-all.ru/2.7/library/io.html#io.IOBase.close) входного потока источника, когда тот вернёт EOF.7071Для более явного управления стеком источников используйте методы [`push_source()`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.push_source) и [`pop_source()`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.pop_source).7273#### `shlex.push_source(stream[, filename])`7475Помещает поток входного источника в стек ввода. Если указан аргумент filename, он будет доступен позже для использования в сообщениях об ошибках. Это тот же метод, который внутренне используется методом [`sourcehook()`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.sourcehook).7677Новое в версии 2.1.7879#### `shlex.pop_source()`8081Извлекает последний помещённый входной источник из стека ввода. Это тот же метод, который используется внутри, когда лексер достигает EOF для помещённого в стек входного потока.8283Новое в версии 2.1.8485#### `shlex.error_leader([file[, line]])`8687Этот метод формирует префикс сообщения об ошибке в формате метки ошибок компилятора C в Unix; формат – `'"%s", line %d: '`, где `%s` заменяется на имя текущего исходного файла, а `%d` – на номер текущей строки ввода (необязательные аргументы позволяют переопределить эти значения).8889Это удобство предоставляется для того, чтобы побудить пользователей [`shlex`](https://python-all.ru/2.7/library/shlex.html#module-shlex) генерировать сообщения об ошибках в стандартном, анализируемом формате, который понимают Emacs и другие инструменты Unix.9091Экземпляры подклассов [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) имеют несколько открытых переменных экземпляра, которые либо управляют лексическим анализом, либо могут использоваться для отладки:9293#### `shlex.commenters`9495Строка символов, которые распознаются как начало комментария. Все символы от начала комментария до конца строки игнорируются. По умолчанию включает только `'#'`.9697#### `shlex.wordchars`9899Строка символов, которые будут накапливаться в составные токены. По умолчанию включает все буквы и цифры ASCII и символ подчёркивания.100101#### `shlex.whitespace`102103Символы, которые считаются пробельными и пропускаются. Пробельные символы разделяют токены. По умолчанию включает пробел, табуляцию, перевод строки и возврат каретки.104105#### `shlex.escape`106107Символы, которые будут считаться экранирующими. Это используется только в режиме POSIX и по умолчанию включает только `'\'`.108109Новое в версии 2.3.110111#### `shlex.quotes`112113Символы, которые будут считаться строковыми кавычками. Токен накапливается до тех пор, пока не встретится та же самая кавычка (то есть разные типы кавычек защищают друг друга, как в оболочке). По умолчанию включает ASCII одинарные и двойные кавычки.114115#### `shlex.escapedquotes`116117Символы в [`quotes`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.quotes), которые будут интерпретировать экранирующие символы, определённые в [`escape`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.escape). Это используется только в режиме POSIX и по умолчанию включает только `'"'`.118119Новое в версии 2.3.120121#### `shlex.whitespace_split`122123Если `True`, токены будут разделяться только по пробельным символам. Это полезно, например, для разбора командных строк с помощью [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex), получая токены аналогично аргументам оболочки.124125Новое в версии 2.3.126127#### `shlex.infile`128129Имя текущего входного файла, установленное при создании экземпляра класса или помещённое в стек последующими запросами источников. Может быть полезно просмотреть его при формировании сообщений об ошибках.130131#### `shlex.instream`132133Входной поток, из которого данный экземпляр [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) читает символы.134135#### `shlex.source`136137По умолчанию этот атрибут равен `None`. Если присвоить ему строку, эта строка будет распознаваться как запрос включения на лексическом уровне, аналогично ключевому слову `source` в различных оболочках. То есть следующий непосредственно токен будет открыт как имя файла, и ввод будет поступать из этого потока до достижения конца файла; после этого будет вызван метод [`close()`](https://python-all.ru/2.7/library/io.html#io.IOBase.close) этого потока, и источником ввода снова станет исходный входной поток. Запросы источника могут быть вложенными на любое количество уровней.138139#### `shlex.debug`140141Если этот атрибут является числовым и равен `1` или больше, экземпляр [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) будет выводить подробную информацию о своих действиях. Если потребуется этим воспользоваться, можно изучить исходный код модуля, чтобы узнать подробности.142143#### `shlex.lineno`144145Номер строки в исходном файле (количество встреченных символов новой строки плюс один).146147#### `shlex.token`148149Буфер токенов. Его может быть полезно проверить при перехвате исключений.150151#### `shlex.eof`152153Токен, используемый для определения конца файла. В не-POSIX-режиме он устанавливается в пустую строку (`''`), а в POSIX-режиме – в `None`.154155Новое в версии 2.3.156157## 23.2.2. Правила разбора158159При работе в не-POSIX режиме [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) будет следовать следующим правилам.160161- Символы кавычек не распознаются внутри слов (`Do"Not"Separate` разбирается как одно слово `Do"Not"Separate`);162- Символы экранирования не распознаются;163- Заключение символов в кавычки сохраняет буквальное значение всех символов внутри кавычек;164- Закрывающие кавычки разделяют слова (`"Do"Separate` разбирается как `"Do"` и `Separate`);165- Если значение [`whitespace_split`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.whitespace_split) равно `False`, любой символ, не объявленный как символ слова, пробел или кавычка, будет возвращён как односимвольный токен. Если оно равно `True`, [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) будет разделять слова только по пробельным символам;166- EOF обозначается пустой строкой (`''`);167- Невозможно разобрать пустые строки, даже если они в кавычках.168169При работе в POSIX режиме [`shlex`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex) будет следовать следующим правилам разбора.170171- Кавычки удаляются и не разделяют слова (`"Do"Not"Separate"` разбирается как одно слово `DoNotSeparate`);172- Неэкранированные (не в кавычках) escape-символы (например, `'\'`) сохраняют буквальное значение следующего за ними символа;173- Заключение символов в кавычки, не входящие в [`escapedquotes`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.escapedquotes) (например, `"'"`), сохраняет буквальное значение всех символов внутри кавычек;174- Заключение символов в кавычки, которые являются частью [`escapedquotes`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.escapedquotes) (например, `'"'`), сохраняет буквальное значение всех символов внутри кавычек, за исключением символов, упомянутых в [`escape`](https://python-all.ru/2.7/library/shlex.html#shlex.shlex.escape). Escape-символы сохраняют своё особое значение только в том случае, если за ними следует используемая кавычка или сам escape-символ. В противном случае escape-символ считается обычным символом.175- EOF обозначается значением [`None`](https://python-all.ru/2.7/library/constants.html#None);176- Пустые строки в кавычках (`''`) разрешены;177