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. Каждый элемент кортежа — это строка, возможно, пустая. Компоненты не разбиваются на более мелкие части (например, сетевое расположение — это одна строка), и % эскапированные символы не расширяются. Разделители, как показано выше, не являются частью результата, за исключением ведущей косой черты в компоненте пути, которая сохраняется, если она присутствует. Например:

>>> from urllib.parse import urlparse
>>> urlparse("scheme://netloc/path;parameters?query#fragment")
ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='',
            query='query', fragment='fragment')
>>> o = urlparse("http://docs.python.org:80/3/library/urllib.parse.html?"
...              "highlight=params#url-parsing")
>>> o
ParseResult(scheme='http', netloc='docs.python.org:80',
            path='/3/library/urllib.parse.html', params='',
            query='highlight=params', fragment='url-parsing')
>>> o.scheme
'http'
>>> o.netloc
'docs.python.org:80'
>>> o.hostname
'docs.python.org'
>>> o.port
80
>>> o._replace(fragment="").geturl()
'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'

В соответствии со спецификациями синтаксиса в 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 не равен false), в соответствии с 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 — это флаг, указывающий, должны ли пустые значения в кодированных посимвольно запросах обрабатываться как пустые строки. Истинное значение указывает, что пустые значения должны сохраняться как пустые строки. Ложное значение по умолчанию указывает, что пустые значения должны игнорироваться и обрабатываться так, как если бы они не были включены.

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

Необязательные параметры encoding и errors задают способ декодирования кодированных посимвольно последовательностей в символы Юникода, как это принимается методом 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.9.2: Добавлен параметр separator со значением по умолчанию &. Версии Python, предшествующие Python 3.9.2, позволяли использовать как ;, так и & в качестве разделителя параметров запроса. Это было изменено, чтобы разрешить использовать только один разделитель, с & в качестве разделителя по умолчанию.

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 — максимальное количество полей для чтения. Если задано, то вызывает исключение ValueError, если прочитано более max_num_fields полей.

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

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

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

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

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

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.9.5: 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)

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

string может быть объектом str или bytes.

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

Необязательные параметры 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 или bytes.

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

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

Изменено в версии 3.9: Параметр string поддерживает объекты bytes и str (ранее только str).

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 на их эквиваленты с одним байтом и возвращает объект bytes.

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, 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, чтобы узнать, как использовать метод urllib.parse.urlencode() для создания строки запроса URL или данных для запроса POST.

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

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