21.8. urllib.parse – Разбор URL на компоненты¶urllib.parse – Parse URLs into components

21.8.1. Разбор URL¶URL Parsing

Функции разбора URL предназначены для разделения строки URL на компоненты или для объединения компонентов URL в строку URL.

urllib.parse.urlparse(urlstring, scheme='', allow_fragments=True)¶

Разбирает URL на шесть компонентов и возвращает кортеж из шести элементов. Это соответствует общей структуре URL: scheme://netloc/path;parameters?query#fragment. Каждый элемент кортежа – строка, возможно пустая. Компоненты не разбиваются на более мелкие части (например, сетевое расположение – это одна строка), а %-последовательности не раскрываются. Разделители, показанные выше, не входят в результат, за исключением начальной косой черты в компоненте path, которая сохраняется, если присутствует. Например:

>>> from urllib.parse import urlparse
>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
>>> o   
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> o.scheme
'http'
>>> o.port
80
>>> o.geturl()
'http://www.cwi.nl:80/%7Eguido/Python.html'

Следуя синтаксическим спецификациям RFC 1808, urlparse распознаёт netloc только в том случае, если она правильно введена символами '//'. В противном случае считается, что входные данные – это относительный URL, и, следовательно, они начинаются с компонента пути.

>>> from urllib.parse import urlparse
>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
           params='', query='', fragment='')
>>> urlparse('www.cwi.nl/%7Eguido/Python.html')
ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
           params='', query='', fragment='')
>>> urlparse('help/Python.html')
ParseResult(scheme='', netloc='', path='help/Python.html', params='',
           query='', fragment='')

Если аргумент scheme указан, он задаёт схему адресации по умолчанию, которая используется только в том случае, если URL сам её не указывает. Значение по умолчанию для этого аргумента – пустая строка.

Если аргумент allow_fragments равен false, идентификаторы фрагментов не допускаются. Значение по умолчанию для этого аргумента – True.

Возвращаемое значение на самом деле является экземпляром подкласса tuple. Этот класс имеет следующие дополнительные атрибуты только для чтения, предоставляющие удобный доступ:

Атрибут	Индекс	Значение	Значение, если отсутствует
scheme	0	Спецификатор схемы URL	пустая строка
netloc	1	Сетевое расположение	пустая строка
path	2	Иерархический путь	пустая строка
params	3	Параметры последнего элемента пути	пустая строка
query	4	Компонент запроса	пустая строка
fragment	5	Идентификатор фрагмента	пустая строка
username		Имя пользователя	None
password		Пароль	None
hostname		Имя хоста (в нижнем регистре)	None
port		Номер порта как целое число, если указан	None

См. раздел Структурированные результаты разбора для получения дополнительной информации об объекте результата.

Изменено в версии 3.2: Добавлена возможность разбора URL с IPv6.

Изменено в версии 3.3: Теперь фрагмент разбирается для всех схем URL (если только allow_fragment не равно false), в соответствии с RFC 3986. Ранее существовал белый список схем, поддерживающих фрагменты.

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace')¶

Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа application/x-www-form-urlencoded). Данные возвращаются в виде словаря. Ключами словаря являются уникальные имена переменных запроса, а значениями – списки значений для каждого имени.

Необязательный аргумент keep_blank_values – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение True означает, что пустые значения должны сохраняться как пустые строки. Значение False по умолчанию означает, что пустые значения игнорируются и считаются отсутствующими.

Необязательный аргумент strict_parsing – флаг, указывающий, что делать с ошибками разбора. Если false (по умолчанию), ошибки игнорируются. Если true, ошибки вызывают исключение ValueError.

Необязательные параметры encoding и errors задают способ декодирования процентно-закодированных последовательностей в символы Unicode, как это принимается методом bytes.decode().

Используйте функцию urllib.parse.urlencode() (с параметром doseq, установленным в True) для преобразования таких словарей в строки запроса.

Изменено в версии 3.2: Добавлены параметры encoding и errors.

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace')¶

Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа application/x-www-form-urlencoded). Данные возвращаются в виде списка пар имя, значение.

Необязательный аргумент keep_blank_values – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение True означает, что пустые значения должны сохраняться как пустые строки. Значение False по умолчанию означает, что пустые значения игнорируются и считаются отсутствующими.

Необязательный аргумент strict_parsing – флаг, указывающий, что делать с ошибками разбора. Если false (по умолчанию), ошибки игнорируются. Если true, ошибки вызывают исключение ValueError.

Необязательные параметры encoding и errors задают способ декодирования процентно-закодированных последовательностей в символы Unicode, как это принимается методом bytes.decode().

Используйте функцию urllib.parse.urlencode() для преобразования таких списков пар в строки запроса.

Изменено в версии 3.2: Добавлены параметры encoding и errors.

urllib.parse.urlunparse(parts)¶

Создаёт URL из кортежа, возвращаемого функцией urlparse(). Аргумент parts может быть любым итерируемым объектом из шести элементов. Результат может немного отличаться от исходного, но быть эквивалентным URL, если исходный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны).

urllib.parse.urlsplit(urlstring, scheme='', allow_fragments=True)¶

Эта функция похожа на urlparse(), но не отделяет параметры от URL. Как правило, её следует использовать вместо urlparse(), если требуется более новый синтаксис URL, допускающий применение параметров к каждому сегменту части path (см. RFC 2396). Для разделения сегментов пути и параметров нужна отдельная функция. Эта функция возвращает 5-кортеж: (схема адресации, сетевое расположение, путь, запрос, идентификатор фрагмента).

Возвращаемое значение на самом деле является экземпляром подкласса tuple. Этот класс имеет следующие дополнительные атрибуты только для чтения, предоставляющие удобный доступ:

Атрибут	Индекс	Значение	Значение, если отсутствует
scheme	0	Спецификатор схемы URL	пустая строка
netloc	1	Сетевое расположение	пустая строка
path	2	Иерархический путь	пустая строка
query	3	Компонент запроса	пустая строка
fragment	4	Идентификатор фрагмента	пустая строка
username		Имя пользователя	None
password		Пароль	None
hostname		Имя хоста (в нижнем регистре)	None
port		Номер порта как целое число, если указан	None

См. раздел Структурированные результаты разбора для получения дополнительной информации об объекте результата.

urllib.parse.urlunsplit(parts)¶

Объединяет элементы кортежа, возвращаемого функцией urlsplit(), в полный URL в виде строки. Аргумент parts может быть любым итерируемым объектом из пяти элементов. Результат может немного отличаться, но быть эквивалентным, если исходный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны).

urllib.parse.urljoin(base, url, allow_fragments=True)¶

Строит полный («абсолютный») URL путём объединения «базового URL» (base) с другим URL (url). Неформально: используются компоненты базового URL, в частности схема адресации, сетевое расположение и (часть) пути, чтобы предоставить недостающие компоненты в относительном URL. Например:

>>> from urllib.parse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'

Аргумент allow_fragments имеет тот же смысл и значение по умолчанию, что и для urlparse().

Примечание

Если url является абсолютным URL (то есть начинается с // или scheme://), то имя хоста и/или схема url будут присутствовать в результате. Например:

>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
...         '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'

Если такое поведение нежелательно, предварительно обработайте url с помощью urlsplit() и urlunsplit(), удалив возможные части scheme и netloc.

urllib.parse.urldefrag(url)¶

Если url содержит идентификатор фрагмента, возвращает изменённую версию url без идентификатора фрагмента и сам идентификатор фрагмента в виде отдельной строки. Если в url нет идентификатора фрагмента, возвращает url без изменений и пустую строку.

Возвращаемое значение на самом деле является экземпляром подкласса tuple. Этот класс имеет следующие дополнительные атрибуты только для чтения, предоставляющие удобный доступ:

Атрибут	Индекс	Значение	Значение, если отсутствует
url	0	URL без фрагмента	пустая строка
fragment	1	Идентификатор фрагмента	пустая строка

См. раздел Структурированные результаты разбора для получения дополнительной информации об объекте результата.

Изменено в версии 3.2: Результат – структурированный объект, а не простой кортеж из двух элементов.

21.8.2. Разбор ASCII-кодированных байтов¶Parsing ASCII Encoded Bytes

Функции разбора URL изначально разрабатывались для работы только со строками символов. На практике полезно иметь возможность манипулировать правильно экранированными и закодированными URL как последовательностями байтов ASCII. Соответственно, функции разбора URL в этом модуле работают как с объектами bytes и bytearray, так и с объектами str.

Если переданы данные типа str, то результат будет содержать только данные типа str. Если переданы данные типа bytes или bytearray, то результат будет содержать только данные типа bytes.

Попытка смешивать данные типа str с данными типа bytes или bytearray в одном вызове функции приведёт к возбуждению исключения TypeError, а попытка передать не-ASCII байтовые значения вызовет UnicodeDecodeError.

Для упрощения преобразования результирующих объектов между str и bytes все возвращаемые значения функций разбора URL предоставляют либо метод encode() (если результат содержит данные str), либо метод decode() (если результат содержит данные bytes). Сигнатуры этих методов совпадают с сигнатурами соответствующих методов str и bytes (за исключением того, что кодировка по умолчанию – 'ascii', а не 'utf-8'). Каждый из них возвращает значение соответствующего типа, содержащее либо данные bytes (для методов encode()), либо данные str (для методов decode()).

Приложениям, которым необходимо работать с потенциально неправильно экранированными URL, которые могут содержать не-ASCII данные, потребуется выполнить собственное декодирование из байтов в символы перед вызовом методов разбора URL.

Поведение, описанное в этом разделе, применяется только к функциям разбора URL. Функции экранирования URL используют свои собственные правила при создании или потреблении последовательностей байтов, как подробно описано в документации отдельных функций экранирования URL.

21.8.3. Структурированные результаты разбора¶Structured Parse Results

Результирующие объекты функций urlparse(), urlsplit() и urldefrag() являются подклассами типа tuple. Эти подклассы добавляют атрибуты, перечисленные в документации этих функций, поддержку кодирования и декодирования, описанную в предыдущем разделе, а также дополнительный метод:

urllib.parse.SplitResult.geturl()¶

Возвращает перекомбинированную версию исходного URL в виде строки. Она может отличаться от исходного URL тем, что схема может быть нормализована к нижнему регистру, а пустые компоненты могут быть отброшены. В частности, пустые параметры, запросы и идентификаторы фрагментов будут удалены.

Для результатов urldefrag() будут удалены только пустые идентификаторы фрагментов. Для результатов urlsplit() и urlparse() все указанные изменения будут внесены в URL, возвращаемый этим методом.

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

>>> from urllib.parse import urlsplit
>>> url = 'HTTP://www.Python.org/doc/#'
>>> r1 = urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'
>>> r2 = urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'

Следующие классы предоставляют реализацию структурированных результатов разбора при работе с объектами str:

class urllib.parse.DefragResult(url, fragment)¶

Конкретный класс для результатов urldefrag(), содержащих данные типа str. Метод encode() возвращает экземпляр DefragResultBytes.

Новое в версии 3.2.

class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)¶

Конкретный класс для результатов urlparse(), содержащих данные типа str. Метод encode() возвращает экземпляр ParseResultBytes.

class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)¶

Конкретный класс для результатов urlsplit(), содержащих данные типа str. Метод encode() возвращает экземпляр SplitResultBytes.

Следующие классы предоставляют реализацию результатов разбора при работе с объектами bytes или bytearray:

class urllib.parse.DefragResultBytes(url, fragment)¶

Конкретный класс для результатов urldefrag(), содержащих данные типа bytes. Метод decode() возвращает экземпляр DefragResult.

Новое в версии 3.2.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)¶

Конкретный класс для результатов urlparse(), содержащих данные типа bytes. Метод decode() возвращает экземпляр ParseResult.

Новое в версии 3.2.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)¶

Конкретный класс для результатов urlsplit(), содержащих данные типа bytes. Метод decode() возвращает экземпляр SplitResult.

Новое в версии 3.2.

21.8.4. Квотирование URL¶URL Quoting

Функции экранирования URL предназначены для преобразования программных данных в безопасный формат для использования в компонентах URL: они экранируют специальные символы и кодируют не-ASCII текст. Они также поддерживают обратные операции для восстановления исходных данных из содержимого компонента URL, если эта задача ещё не решается описанными выше функциями разбора URL.

urllib.parse.quote(string, safe='/', encoding=None, errors=None)¶

Заменяет специальные символы в string с помощью экранирования %xx. Буквы, цифры и символы '_.-' никогда не экранируются. По умолчанию эта функция предназначена для экранирования компонента пути URL. Необязательный параметр safe задаёт дополнительные символы ASCII, которые не должны экранироваться – его значение по умолчанию равно '/'.

string может быть как строкой str, так и объектом bytes.

Необязательные параметры encoding и errors определяют, как обрабатывать не-ASCII символы; они принимаются методом str.encode(). encoding по умолчанию равен 'utf-8'. errors по умолчанию равен 'strict', то есть неподдерживаемые символы вызывают UnicodeEncodeError. encoding и errors не должны указываться, если string является bytes, иначе будет возбуждено TypeError.

Обратите внимание, что quote(string, safe, encoding, errors) эквивалентно quote_from_bytes(string.encode(encoding, errors), safe).

Пример: quote('/El Niño/') возвращает '/El%20Ni%C3%B1o/'.

urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)¶

Аналогична quote(), но также заменяет пробелы знаками плюс, как требуется для экранирования значений HTML-форм при составлении строки запроса для URL. Знаки плюс в исходной строке экранируются, если они не включены в safe. Кроме того, значение по умолчанию safe не равно '/'.

Пример: quote_plus('/El Niño/') возвращает '%2FEl+Ni%C3%B1o%2F'.

urllib.parse.quote_from_bytes(bytes, safe='/')¶

Аналогична quote(), но принимает объект bytes вместо str и не выполняет преобразование строки в байты.

Пример: quote_from_bytes(b'a&\xef') возвращает 'a%26%EF'.

urllib.parse.unquote(string, encoding='utf-8', errors='replace')¶

Заменяет последовательности %xx на соответствующий им одиночный символ. Необязательные параметры encoding и errors задают, как декодировать процентно-кодированные последовательности в символы Юникода, как это делается в методе bytes.decode().

string должен иметь тип str.

По умолчанию encoding равен 'utf-8'. errors по умолчанию равен 'replace', то есть недопустимые последовательности заменяются на символ-заменитель.

Пример: unquote('/El%20Ni%C3%B1o/') возвращает '/El Niño/'.

urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')¶

Аналогично unquote(), но дополнительно заменяет знаки плюс пробелами, что требуется для декодирования значений HTML-форм.

string должен иметь тип str.

Пример: unquote_plus('/El+Ni%C3%B1o/') возвращает '/El Niño/'.

urllib.parse.unquote_to_bytes(string)¶

Заменяет последовательности %xx на эквивалентный одиночный октет и возвращает объект байтов.

string может быть как строкой str, так и объектом bytes.

Если это строка str, то неэкранированные не-ASCII символы в string кодируются в байты UTF-8.

Пример: unquote_to_bytes('a%26%EF') возвращает b'a&\xef'.

urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None)¶

Преобразует объект отображения или последовательность кортежей из двух элементов (каждый может быть либо str, либо bytes) в строку в «процентной кодировке». Если результирующую строку планируется использовать в качестве data для операции POST с функцией urlopen(), её необходимо правильно преобразовать в байты, иначе это приведёт к TypeError.

Результирующая строка представляет собой последовательность пар ключ=значение, разделённых символами '&', где и key, и value кодируются с помощью quote_plus() (см. выше). Если в качестве аргумента query используется последовательность двухэлементных кортежей, то первый элемент каждого кортежа является ключом, а второй – значением. Сам элемент значения может быть последовательностью, и в этом случае, если необязательный параметр doseq принимает значение True, для каждого элемента последовательности значений ключа генерируются отдельные пары ключ=значение, разделённые '&'. Порядок параметров в закодированной строке будет соответствовать порядку кортежей параметров в последовательности.

Когда параметр query является str, параметры safe, encoding и error передаются в quote_plus() для кодирования.

Для обратного преобразования этой кодировки в этом модуле предоставляются функции parse_qs() и parse_qsl(), которые разбирают строки запроса в структуры данных Python.

Обратитесь к примерам urllib, чтобы узнать, как метод urlencode можно использовать для создания строки запроса для URL или данных для POST.

Изменено в версии 3.2: Параметр Query поддерживает объекты bytes и string.