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

Этот модуль предоставляет стандартный интерфейс для разбора строки URL на компоненты (схема адресации, сетевое расположение, путь и т.д.), обратной сборки компонентов в строку URL, а также для преобразования «относительного URL» в абсолютный по заданному «базовому URL».

Модуль разработан в соответствии с RFC на относительные унифицированные указатели ресурсов (и обнаружил ошибку в одном из ранних черновиков!). Он поддерживает следующие схемы URL: file, ftp, gopher, hdl, http, https, imap, mailto, mms, news, nntp, prospero, rsync, rtsp, rtspu, sftp, shttp, sip, sips, snews, svn, svn+ssh, telnet, wais.

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

urllib.parse.urlparse(, urlstring[, default_scheme[, allow_fragments]])¶

Разбирает 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   # doctest: +NORMALIZE_WHITESPACE
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'

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

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

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

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

См. раздел Результаты urlparse() и urlsplit() для получения дополнительной информации о результирующем объекте.

urllib.parse.parse_qs(qs[, keep_blank_values[, strict_parsing]])¶

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

Необязательный аргумент keep_blank_values – флаг, указывающий, следует ли рассматривать пустые значения в URL-кодированных запросах как пустые строки. Значение true означает, что пустые значения сохраняются как пустые строки. Значение по умолчанию false означает, что пустые значения игнорируются и считаются не включёнными.

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

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

urllib.parse.parse_qsl(qs[, keep_blank_values[, strict_parsing]])¶

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

Необязательный аргумент keep_blank_values – флаг, указывающий, следует ли рассматривать пустые значения в URL-кодированных запросах как пустые строки. Значение true означает, что пустые значения сохраняются как пустые строки. Значение по умолчанию false означает, что пустые значения игнорируются и считаются не включёнными.

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

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

urllib.parse.urlunparse(parts)¶

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

urllib.parse.urlsplit(urlstring[, default_scheme[, allow_fragments]])¶

Эта функция похожа на 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

См. раздел Результаты urlparse() и urlsplit() для получения дополнительной информации о результирующем объекте.

urllib.parse.urlunsplit(parts)¶

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

urllib.parse.urljoin(base, url[, allow_fragments])¶

Строит полный («абсолютный») 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 без изменений и пустую строку.

urllib.parse.quote(string[, safe[, encoding[, errors]]])¶

Заменяет специальные символы в строке string с помощью экранирования %xx. Буквы, цифры и символ '_.-' не квотируются. Необязательный параметр 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[, errors]]])¶

Действует как quote(), но также заменяет пробелы на знаки плюс, как требуется для квотирования значений HTML-форм. Знаки плюс в исходной строке экранируются, если они не включены в 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[, errors]])¶

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

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

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

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

urllib.parse.unquote_plus(string[, encoding[, errors]])¶

Аналогично 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])¶

Преобразует объект отображения (mapping) или последовательность кортежей из двух элементов в строку, закодированную в формате URL, подходящую для передачи в качестве необязательного аргумента data функции urlopen() выше. Это полезно для передачи словаря полей формы в запросе POST. Результирующая строка представляет собой серию пар key=value, разделённых символами '&', причём как key, так и value квотируются с помощью quote_plus() выше. Если необязательный параметр doseq присутствует и принимает значение true, для каждого элемента последовательности генерируются отдельные пары key=value. Когда в качестве аргумента query используется последовательность кортежей из двух элементов, первый элемент каждого кортежа – это ключ, а второй – значение. Порядок параметров в закодированной строке будет соответствовать порядку кортежей параметров в последовательности. Этот модуль содержит функции parse_qs() и parse_qsl(), которые используются для разбора строк запроса в структуры данных Python.