20.7. 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, 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   # 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'

Следуя синтаксическим спецификациям 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:80/%7Eguido/Python.html')
ParseResult(scheme='', netloc='', path='www.cwi.nl:80/%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, идентификаторы фрагментов не допускаются, даже если схема адресации 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=False, strict_parsing=False)¶

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

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

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

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

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False)¶

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

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

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

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

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

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

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 без изменений и пустую строку.

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 функции urlopen() (см. выше). Это удобно для передачи словаря полей формы в запросе POST. Результирующая строка представляет собой последовательность пар key=value, разделённых символами '&', где и key, и value кодируются с помощью quote_plus() (см. выше). Если в качестве аргумента query передаётся последовательность двухэлементных кортежей, то первый элемент каждого кортежа – это ключ, а второй – значение. Само значение может быть последовательностью, и в этом случае, если необязательный параметр doseq принимает значение True, для каждого элемента последовательности значений данного ключа генерируются отдельные пары key=value, разделённые '&'. Порядок параметров в закодированной строке будет соответствовать порядку кортежей параметров в последовательности. Этот модуль предоставляет функции parse_qs() и parse_qsl(), которые используются для разбора строк запроса в структуры данных Python.

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

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