shlex — Простой лексический анализ

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

Класс shlex упрощает создание лексических анализаторов для простых синтаксисов, напоминающих оболочку Unix. Это часто бывает полезно для создания мини-языков (например, в файлах управления выполнением для приложений Python) или для разбора строковых выражений, заключенных в кавычки.

Модуль shlex определяет следующие функции:

shlex.split(s, comments=False, posix=True): Разделить строку s с использованием синтаксиса, подобного оболочке. Если comments имеет значение False (по умолчанию), разбор комментариев в данной строке будет отключен (устанавливая атрибут commenters экземпляра shlex в пустую строку). Эта функция работает в режиме POSIX по умолчанию, но использует режим не-POSIX, если аргумент posix имеет значение false.

Примечание

Поскольку функция split() создает экземпляр shlex, передача None в качестве s будет читать строку для разделения из стандартного ввода.

shlex.quote(s)

Возвращает экранированную версию строки s для использования в оболочке. Возвращаемое значение — строка, которая безопасно может быть использована как один токен в командной строке оболочки, в случаях, когда вы не можете использовать список.

Этот фрагмент кода небезопасен:

>>> filename = 'somefile; rm -rf ~'
>>> command = 'ls -l {}'.format(filename)
>>> print(command)  # executed by a shell: boom!
ls -l somefile; rm -rf ~

quote() позволяет устранить эту уязвимость:

>>> command = 'ls -l {}'.format(quote(filename))
>>> print(command)
ls -l 'somefile; rm -rf ~'
>>> remote_command = 'ssh home {}'.format(quote(command))
>>> print(remote_command)
ssh home 'ls -l '"'"'somefile; rm -rf ~'"'"''

Экранирование совместимо с оболочками UNIX и с split():

>>> remote_command = split(remote_command)
>>> remote_command
['ssh', 'home', "ls -l 'somefile; rm -rf ~'"]
>>> command = split(remote_command[-1])
>>> command
['ls', '-l', 'somefile; rm -rf ~']

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

Модуль shlex определяет следующий класс:

class shlex.shlex(instream=None, infile=None, posix=False): Экземпляр класса shlex или его подкласса является объектом лексического анализатора. Аргумент инициализации, если он присутствует, указывает, откуда читать символы. Он должен быть объектом типа файл/поток с методами read() и readline() или строкой. Если аргумент не указан, ввод будет извлекаться из sys.stdin. Второй необязательный аргумент — строка имени файла, которая устанавливает начальное значение атрибута infile. Если аргумент instream опущен или равен sys.stdin, этот второй аргумент по умолчанию равен “stdin”. Аргумент posix определяет режим работы: когда posix не имеет значения true (по умолчанию), экземпляр shlex будет работать в режиме совместимости. При работе в режиме POSIX, shlex будет пытаться максимально соответствовать правилам разбора оболочки POSIX.

См. также

Module configparser: Парсер для файлов конфигурации, аналогичных файлам Windows .ini.

1. Объекты shlex

Экземпляр класса shlex имеет следующие методы:

shlex.get_token(): Возвращает токен. Если токены были помещены в стек с помощью push_token(), извлечь токен из стека. В противном случае прочитать один из потока ввода. Если при чтении встречается немедленный конец файла, возвращается eof (пустая строка ('') в режиме не-POSIX и None в режиме POSIX).

shlex.push_token(str): Поместить аргумент в стек токенов.

shlex.read_token(): Прочитать сырой токен. Игнорировать стек pushback и не интерпретировать запросы на источник. (Это обычно не является полезной точкой входа и документировано здесь только ради полноты.)

shlex.sourcehook(filename)

Когда shlex обнаруживает запрос на источник (см. source ниже), этому методу передается следующий токен в качестве аргумента, и ожидается, что он вернёт кортеж, состоящий из имени файла и открытого файла-подобного объекта.

Обычно этот метод сначала удаляет любые кавычки из аргумента. Если результат является абсолютным путем к файлу, или не было предыдущего запроса на источник, или предыдущий источник был потоком (таким как sys.stdin), результат оставляется без изменений. В противном случае, если результат является относительным путем к файлу, к началу пути добавляется директория файла, непосредственно предшествующего ему в стеке включения источников (это поведение аналогично тому, как C препроцессор обрабатывает #include "file.h").

Результат манипуляций обрабатывается как имя файла и возвращается как первая компонента кортежа, при этом вызывается open() для получения второй компоненты. (Примечание: это обратный порядок аргументов по сравнению с порядком аргументов при инициализации экземпляра!)

Этот обработчик предоставляется для реализации путей поиска каталогов, добавления расширений файлов и других хакерских приемов для пространств имён. Нет соответствующего обработчика «закрыть», но экземпляр shlex вызовет метод close() потока ввода, считанного из источника, когда он вернёт EOF.

Для более явного управления стеком источников используйте методы push_source() и pop_source().

shlex.push_source(newstream, newfile=None): Поместить поток ввода источника в стек ввода. Если указано имя файла, оно позже будет доступно для использования в сообщениях об ошибках. Это тот же метод, который используется внутри методом sourcehook().

shlex.pop_source(): Извлечь последний добавленный поток ввода источника из стека ввода. Это тот же метод, который используется внутри, когда лексический анализатор достигает EOF в стековом потоке ввода.

shlex.error_leader(infile=None, lineno=None)

Этот метод генерирует ведущую часть сообщения об ошибке в формате метки ошибки компилятора Unix; формат '"%s", line %d: ', где %s заменяется именем текущего файла источника, а %d — текущим номером строки ввода (необязательные аргументы можно использовать для переопределения этих значений).

Эта удобная функция способствует использованию пользователями модуля shlex для генерации сообщений об ошибках в стандартном формате, который может быть прочитан программами Emacs и другими инструментами Unix.

Экземпляры подклассов shlex имеют некоторые публичные переменные экземпляров, которые либо управляют лексическим анализом, либо могут использоваться для отладки:

shlex.commenters: Строка символов, которые распознаются как начала комментариев. Все символы от начала комментария до конца строки игнорируются. По умолчанию включает только '#'.

shlex.wordchars: Строка символов, которые будут накапливаться в многосимвольных токенах. По умолчанию включает все ASCII-буквы, цифры и символ подчёркивания.

shlex.whitespace: Символы, которые будут считаться пробелами и пропускаться. Пробелы разделяют токены. По умолчанию включает пробел, табуляцию, перенос строки и возврат каретки.

shlex.escape: Символы, которые будут считаться escape-символами. Это будет использоваться только в режиме POSIX и по умолчанию включает только '\'.

shlex.quotes: Символы, которые будут считаться кавычками. Токен накапливается до тех пор, пока не встретится та же кавычка (разные типы кавычек защищают друг друга, как в оболочке). По умолчанию включает одинарные и двойные кавычки ASCII.

shlex.escapedquotes: Символы в quotes, которые будут интерпретировать escape-символы, определённые в escape. Это используется только в режиме POSIX и по умолчанию включает только '"'.

END_OF_DOCUMENT_MARKER

shlex.whitespace_split: Если True, то токены будут разделены только пробелами. Это полезно, например, для разбора командных строк с shlex, получая токены аналогично аргументам оболочки.

shlex.infile: Имя текущего входного файла, как задано при создании класса или в последующих запросах. Это может быть полезно при построении сообщений об ошибках.

shlex.instream: Поток ввода, из которого этот экземпляр shlex считывает символы.

shlex.source: Этот атрибут None по умолчанию. Если вы присвоите ему строку, эта строка будет распознана как запрос на включение на лексическом уровне, аналогично ключевому слову source в различных оболочках. То есть, непосредственно следующий токен будет открыт как имя файла, и ввод будет осуществляться из этого потока до EOF, после чего будет вызван метод close() этого потока, а источником ввода снова станет исходный поток ввода. Запросы на источник могут быть вложены на любое количество уровней.

shlex.debug: Если этот атрибут является числовым и 1 или больше, экземпляр shlex будет выводить подробный вывод о своем поведении. Если вам нужно это использовать, вы можете прочитать исходный код модуля, чтобы узнать подробности.

shlex.lineno: Номер строки источника (количество увиденных символов новой строки плюс один).

shlex.token: Буфер токенов. Может быть полезно для проверки при перехвате исключений.

shlex.eof: Токен, используемый для определения конца файла. Он будет установлен в пустую строку ('') в режиме, несовместимом с POSIX, и в None в режиме POSIX.

2. Правила разбора

При работе в режиме, несовместимом с POSIX, shlex попытается следовать следующим правилам.

Символы кавычек не распознаются внутри слов (Do"Not"Separate разбирается как единственное слово Do"Not"Separate);
Символы экранирования не распознаются;
Символы обрамления кавычек сохраняют буквальное значение всех символов внутри кавычек;
Закрывающие кавычки разделяют слова ("Do"Separate разбирается как "Do" и Separate);
Если whitespace_split равно False, любой символ, не объявленный символом слова, пробелом или символом кавычек, будет возвращен как токен из одного символа. Если он равен True, shlex будет разделять слова только по пробелам;
EOF сигнализируется пустой строкой ('');
Невозможно разобрать пустые строки, даже если они заключены в кавычки.

При работе в режиме POSIX, shlex будет пытаться следовать следующим правилам разбора.

Кавычки удаляются и не разделяют слова ("Do"Not"Separate" разбирается как единственное слово DoNotSeparate);
Неэкранированные символы экранирования (например, '\') сохраняют буквальное значение следующего символа;
Символы обрамления кавычек, которые не являются частью escapedquotes (например, "'") сохраняют буквальное значение всех символов внутри кавычек;
Символы обрамления кавычек, которые являются частью escapedquotes (например, '"') сохраняют буквальное значение всех символов внутри кавычек, за исключением символов, упомянутых в escape. Символы экранирования сохраняют свое специальное значение только когда следуют за используемой кавычкой или самим символом экранирования. В противном случае символ экранирования будет рассматриваться как обычный символ.
EOF сигнализируется значением None;
Разрешены пустые строки в кавычках ('').