import shlex sh = shlex.shlex(instream=None, infile=None, posix=False, punctuation_chars=False)
instream=None
- откуда читать строку,infile=None
- строка c именем файла,posix=False
- режим работы,punctuation_chars=False
- порядок анализа символов (); | &
.Экземпляр класса shlex.shlex()
модуля shlex
или экземпляр подкласса является объектом лексического анализатора.
Аргумент инициализации instream
, если присутствует, указывает, откуда читать символы. Это должен быть файлоподобный объект с методами file.read()
и file.readline()
или строка. Если аргумент не указан, входные данные будут взяты из sys.stdin
.
Второй необязательный аргумент infile
- это строка c именем файла. Если аргумент instream
опущен или равен sys.stdin
, этот второй аргумент по умолчанию равен stdin
.
Аргумент posix
определяет режим работы: когда posix
не равен True
(по умолчанию), экземпляр shlex
будет работать в режиме совместимости. При работе в режиме POSIX, shlex
будет стараться максимально приблизиться к правилам разбора терминальной оболочки POSIX.
Аргумент punctuation_chars
предоставляет способ сделать поведение еще ближе к тому, как анализируются реальные оболочки. Аргумент может принимать несколько значений: значение по умолчанию False
сохраняет поведение, наблюдаемое в Python-3.5 и более ранних версиях. Если установлено значение True
, то анализ символов (); | &
меняется: любая последовательность этих символов возвращается как один токен.
Если задана непустая строка символов, эти символы будут использоваться в качестве знаков пунктуации. Любые символы в атрибуте wordchars
, которые появляются в punctuation_chars
, будут удалены из wordchars
. Подробнее смотрите раздел "Анализатор команд для терминальных оболочек bash, dash и sh.".
Параметр punctuation_chars
может быть установлен только при создании экземпляра shlex
и не может быть изменен позже.
shlex
.shlex.get_token()
,shlex.push_token()
,shlex.read_token()
,shlex.sourcehook()
,shlex.push_source()
,shlex.pop_source()
, shlex.error_leader()
,shlex.commenters()
,shlex.wordchars()
,shlex.whitespace()
,shlex.escape()
,shlex.quotes()
,shlex.escapedquotes()
,shlex.whitespace_split()
,shlex.infile()
,shlex.instream()
,shlex.source()
,shlex
shlex.debug()
,shlex.lineno()
,shlex.token()
, shlex.eof()
,shlex.punctuation_chars()
.shlex.get_token()
:Метод shlex.get_token()
возвращает токен. Если токены были добавлены с помощью shlex.push_token()
, то извлекает токен из стека. В противном случае, читает один из входного потока.
Если при чтении обнаруживается непосредственный конец файла, возвращается пустая строка ''
в режиме не POSIX и None
в режиме POSIX.
shlex.push_token(str)
:Метод shlex.push_token()
вставляет аргумент str
в стек токенов.
shlex.read_token()
:Метод shlex.read_token()
читает сырой токен. Игнорирует стек возвратов и не интерпретирует исходные запросы. Обычно это бесполезный метод и присутствует в документации только для полноты картины.
shlex.sourcehook(filename)
:Когда shlex
обнаруживает запрос shlex.source
, то методу shlex.sourcehook()
в качестве аргумента присваивается следующий токен и ожидается, что он вернет кортеж, состоящий из имени файла и открытого файлоподобного объекта.
Обычно этот метод сначала удаляет любые кавычки из аргумента. Если результатом является абсолютное имя пути, или предыдущий shlex.source
запрос не действовал, или предыдущий источник был потоком, например sys.stdin, результат остается один. В противном случае, если результатом является относительный путь, то перед каталогом будет добавлена часть имени файла непосредственно перед ним в стеке включения источника. Это похоже на то, как компилятор языка C обрабатывает #include 'file.h'
.
Результат манипуляций обрабатывается как имя файла и возвращается как первый компонент кортежа, при этом вызывается функция open()
для получения второго компонента. Примечание: это обратный порядок аргументов при инициализации экземпляра!
Если этот хук доступен то его можно использовать его для реализации путей поиска в каталогах, добавления расширений файлов и других изменений пространства имен. Хука close
не существует, но экземпляр shlex
вызовет метод file.close()
входного потока источника, когда он возвратит EOF (конец файла).
Для более явного контроля над стекированием исходного кода используйте методы shlex.push_source()
и shlex.pop_source()
.
shlex.push_source(newstream, newfile=None)
:Метод shlex.push_source()
вставляет поток входного источника newstream
в стек ввода. Если указан аргумент имени файла newfile
, то он позже будет доступен для использования в сообщениях об ошибках. Это тот же метод, который используется внутри метода shlex.sourcehook()
.
shlex.pop_source()
:Метод shlex.pop_source()
извлекает последний вставленный источник ввода из стека ввода. Это тот же метод, который используется внутри, когда лексер достигает EOF в стековом входном потоке.
shlex.error_leader(infile=None, lineno=None)
:Метод shlex.error_leader()
генерирует заголовок сообщения об ошибке в формате метки ошибки компилятора Unix C.
Формат '"%s", line %d: '
, где %s
заменяется именем текущего исходного файла, а %d
- текущим номером строки ввода, необязательные аргументы могут использоваться для их переопределения.
Это удобство позволяет пользователям shlex
генерировать сообщения об ошибках в стандартном, разбираемом формате, понятном Emacs
и другим инструментам Unix.
shlex
имеет общедоступные переменные, которые либо управляют лексическим анализом, либо могут использоваться для отладки:shlex.commenters
:Атрибут shlex.commenters()
строка символов, которые будут распознаются как начинающие комментарии. Все символы от начала комментария до конца строки игнорируются. Включает просто символ #
по умолчанию.
shlex.wordchars
:Атрибут shlex.wordchars
строка символов, которые будет накапливаться в многосимвольные токены.
По умолчанию включает все буквенно-цифровые символы ASCII и подчеркивание. В режиме POSIX, акцентированные символы в наборе Latin-1 также включены. Если аргумент punctuation_chars
не является пустым, символы ~-./*?=
, которые могут появиться в спецификациях имени файла и параметров командной строки, также будут включены в этот атрибут и любые символы, которые появляются в знаках пунктуации, будут удалены из словарных символов, если они там присутствуют. Если для атрибута shlex.whitespace_split
установлено значение True
, то это не будет иметь никакого эффекта.
shlex.whitespace
:Атрибут shlex.whitespace
символы, которые будут считаться пробелами и будут пропущены. Пробелы ограничивают токены. По умолчанию shlex.whitespace
включает пробел, табуляцию, перевод строки и возврат каретки.
shlex.escape
:Атрибут shlex.escape
символы, которые будут рассматриваться как экранирование. Это будет использоваться только в режиме POSIX и по умолчанию включает просто \
.
shlex.quotes
:Атрибут shlex.quotes()
символы, которые будут считаться строковыми кавычками. Токен накапливается до тех пор, пока одна и та же кавычка не встретится снова. Таким образом, различные типы кавычек защищают друг друга, как в оболочке. По умолчанию, включает в себя одинарные и двойные кавычки ASCII.
shlex.escapedquotes
:Атрибут shlex.escapedquotes
символы в кавычках, которые будут интерпретировать escape-символы, определенные в [shlex.escape](#shlex.escape). Это используется только в режиме POSIX и по умолчанию включает просто
'"'`.
shlex.whitespace_split
:Если атрибут shlex.whitespace_split
имеет значение True
, то токены будут разбиваться только на пробелы. Это полезно, например, для разбора командной строки с помощью shlex
, получения токенов аналогично аргументам оболочки.
При использовании в сочетании с punctuation_chars
токены будут разделены на пробелы в дополнение к этим символам.
С версии Python-3.8: Атрибут punctuation_chars
был сделан совместимым с атрибутом shlex.whitespace_split
.
shlex.infile
:Атрибут shlex.infile
возвращает имя текущего входного файла, изначально установленное во время создания класса или сложенное последующими исходными запросами.
Это может быть полезно проверить при создании сообщений об ошибках.
shlex.instream
:Атрибут shlex.instream
возвращает входной поток, из которого этот экземпляр shlex
читает символы.
shlex.source
:Атрибут shlex.source()
по умолчанию отсутствует. Если назначить ему строку, то эта строка будет распознаваться как запрос включения лексического уровня, аналогичный ключевому слову источника в различных оболочках.
Таким образом, непосредственно следующий токен будет открыт как имя файла и вход будет взят из этого потока до EOF, после чего будет вызван метод close()
этого потока, и источник ввода снова станет исходным потоком ввода. Исходные запросы могут быть сложены на любом количестве уровней.
shlex.debug
:Если атрибут shlex.debug()
является числовым и имеет значение 1 или более, то экземпляр shlex
будет печатать подробный вывод о своем поведении. Если это поведение необходимо использовать, то вы можете прочитать исходный код модуля, чтобы узнать подробности.
shlex.lineno
:Атрибут shlex.lineno
возвращает номер строки источника, количество прочитанных строк плюс один.
shlex.token
:Атрибут shlex.token
возвращает буфер токена. Может быть полезно при обнаружении исключений.
shlex.eof
:Атрибут shlex.eof
возвращает токен, который используется для определения конца файла. Для него будет задана пустая строка ''
в режиме без POSIX и None
в режиме POSIX.
shlex.punctuation_chars
:Атрибут shlex.punctuation_chars()
только для чтения. Символы, которые будут считаться знаками препинания. Строки знаков препинания будут возвращены как один токен. Тем не менее, обратите внимание, что не будет выполняться семантическая проверка достоверности: например ‘>>>’
может быть возвращено как токен, даже если он не может быть распознан как таковой оболочкой.