urllib.parse — Разбор URL-адресов на компоненты

Разбор URL

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

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

Разбирает URL-адрес на шесть компонентов, возвращая кортеж из 6 элементов именованный кортеж. Это соответствует общей структуре 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 не указывает её. Он должен быть того же типа (текст или байты), что и urlstring, за исключением того, что значение по умолчанию '' всегда разрешено и автоматически преобразуется в b'' при необходимости.

Если аргумент allow_fragments равен false, идентификаторы фрагментов не распознаются. Вместо этого они разбираются как часть компонента пути, параметров или запроса, и fragment в значении возврата устанавливается в пустую строку.

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

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

Обращение к атрибуту port вызовет ValueError, если в URL указан недопустимый порт. Дополнительную информацию об объекте результата см. в разделе Структурированные результаты разбора.

Несовпадающие квадратные скобки в атрибуте netloc вызовут ValueError.

Символы в атрибуте netloc который раскладываются при нормализации NFKC (как используется кодированием IDNA) в любой из /, ?, #, @, или : вызовут ValueError. Если URL разложен перед разбором, ошибка не будет поднята.

Как и во всех именованных кортежах, подкласс имеет несколько дополнительных методов и атрибутов, которые особенно полезны. Один из таких методов — _replace(). Метод _replace() вернёт новый объект ParseResult, заменяющий указанные поля новыми значениями.

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

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

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

Изменено в версии 3.6: Порты вне диапазона теперь вызывают ValueError, а не возвращают None.

Изменено в версии 3.8: Символы, влияющие на разбор netloc при нормализации NFKC, теперь вызовут ValueError.

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

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

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

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

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

Необязательный аргумент max_num_fields — максимальное количество полей для чтения. При его установке, если прочитано более max_num_fields полей, выбрасывается ValueError.

Необязательный аргумент separator — символ, используемый для разделения аргументов запроса. По умолчанию &.

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

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

Изменено в версии 3.8: Добавлен параметр max_num_fields.

Изменено в версии 3.8.8: Добавлен параметр separator со значением по умолчанию &. В версиях Python до Python 3.8.8 разрешалось использовать как ;, так и & в качестве разделителя параметров запроса. Это было изменено, чтобы разрешить использовать только один разделитель, по умолчанию &.

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

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

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

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

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

Необязательный аргумент max_num_fields — максимальное количество полей для чтения. Если задано, то при чтении более max_num_fields полей генерирует исключение ValueError.

Необязательный аргумент separator — символ, используемый для разделения аргументов запроса. По умолчанию &.

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

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

Изменено в версии 3.8: Добавлен параметр max_num_fields.

Изменено в версии 3.8.8: Добавлен параметр separator со значением по умолчанию &. В версиях Python, более ранних чем Python 3.8.8, разрешалось использовать ; и & в качестве разделителя параметров запроса. Это было изменено для разрешения использования только одного разделителя, по умолчанию &.

urllib.parse.urlunparse(parts)

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

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

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

(addressing scheme, network location, path, query, fragment identifier).

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

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

Чтение атрибута port вызовет ValueError, если в URL указан неверный порт. Дополнительную информацию об объекте результата см. в разделе Структурированные результаты разбора.

Несоответствующие квадратные скобки в атрибуте netloc вызовут ValueError.

Символы в атрибуте netloc , которые разлагаются при нормализации NFKC (как используется в кодировании IDNA) на любой из /, ?, #, @, или : вызовут ValueError. Если URL разложен до разбора, ошибка не будет поднята.

В соответствии со спецификацией WHATWG https://url.spec.whatwg.org/#concept-basic-url-parser, которая обновляет RFC 3986, символы ASCII новой строки \n, \r и табуляции \t удаляются из URL.

Изменено в версии 3.6: Номера портов вне диапазона теперь вызывают ValueError, а не возвращают None.

Изменено в версии 3.8: Символы, которые влияют на разбор netloc при нормализации NFKC, теперь вызовут ValueError.

Изменено в версии 3.8.10: Символы ASCII новой строки и табуляции удаляются из URL.

urllib.parse.urlunsplit(parts)

Объединяет элементы кортежа, возвращаемого функцией urlsplit(), в полную строку URL. Аргумент parts может быть любым итерируемым объектом из пяти элементов. Это может привести к немного другому, но эквивалентному URL, если исходный 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.

Изменено в версии 3.5: Поведение обновлено для соответствия семантике, определённой в RFC 3986.

urllib.parse.urldefrag(url)

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

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

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

Дополнительную информацию об объекте результата см. в разделе Структурированные результаты разбора.

Изменено в версии 3.2: Результат — структурированный объект, а не простая 2-кортеж.

urllib.parse.unwrap(url)

Извлечь URL из обернутого URL (то есть строку, отформатированную как <URL:scheme://host/path>, <scheme://host/path>, URL:scheme://host/path или scheme://host/path). Если url не является обернутым URL, он возвращается без изменений.

Парсинг байтов, закодированных в ASCII

Функции парсинга 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.

Структурированные результаты разбора

Объекты результата функций 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.

Кодирование URL-адресов

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

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

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

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

Изменено в версии 3.7: Перемещено из RFC 2396 в RFC 3986 для кодирования URL-строк. “~” теперь включён в набор нерезервированных символов.

Необязательные параметры encoding и errors задают способ обработки не-ASCII символов, как это принимается методом str.encode(). encoding по умолчанию 'utf-8'. errors по умолчанию 'strict', что означает, что недопустимые символы вызывают исключение UnicodeEncodeError. Параметры encoding и errors не должны передаваться, если строка является 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().

строка должна быть 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-форм.

строка должна быть str.

Пример: unquote_plus('/El+Ni%C3%B1o/') даёт '/El Niño/'.

urllib.parse.unquote_to_bytes(string)

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

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

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

Пример: unquote_to_bytes('a%26%EF') даёт b'a&\xef'.

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

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

Результат — это серия пар «ключ-значение» key=value разделённых символами '&', где и ключ, и значение кодируются с помощью функции quote_via. По умолчанию используется quote_plus() для кодирования значений, что означает, что пробелы кодируются как '+' символ, а символы ‘/’ кодируются как %2F, что соответствует стандарту для запросов GET (application/x-www-form-urlencoded). Альтернативная функция, которая может быть передана в качестве quote_via, — это quote(), которая закодирует пробелы как %20 и не будет кодировать символы ‘/’. Для максимального контроля над тем, что кодируется, используйте quote и укажите значение для safe.

Когда в качестве аргумента query используется последовательность пар «ключ-значение», первый элемент каждой пары — ключ, а второй — значение. Сам элемент значения может быть последовательностью, и в этом случае, если необязательный параметр doseq имеет значение True, для каждого элемента последовательности значений для ключа генерируются отдельные пары key=value разделённые символами '&'.

Параметры safe, encoding и errors передаются в quote_via (параметры encoding и errors передаются только когда элемент запроса является str).

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

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

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

Добавлен в версии 3.5: параметр quote_via.