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

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

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

Атрибут	Индекс	Значение	Значение, если отсутствует
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 разложен до разбора, ошибка не возникнет.

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

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

Изменено в версии 3.6: Номера портов вне диапазона теперь возбуждают ValueError вместо возврата None.

Изменено в версии 3.6.9: Символы, влияющие на разбор 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.6.8: Добавлен параметр max_num_fields.

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

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 определяют, как декодировать процентно-кодированные последовательности в символы Unicode, как это принимается методом bytes.decode().

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

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

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

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

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

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

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). Для разделения сегментов пути и параметров нужна отдельная функция. Эта функция возвращает кортеж из пяти элементов: (схема адресации, сетевое расположение, путь, запрос, идентификатор фрагмента).

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

Атрибут	Индекс	Значение	Значение, если отсутствует
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, обновляющей RFC 3986, символы ASCII перевода строки \n, \r и табуляции \t удаляются из URL.

Изменено в версии 3.6: Номера портов вне диапазона теперь возбуждают ValueError вместо возврата None.

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

Изменено в версии 3.6.14: Символы 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 без изменений и пустую строку.

Возвращаемое значение на самом деле является экземпляром подкласса 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 с помощью escape-последовательности %xx. Буквы, цифры и символы '_.-' никогда не экранируются. По умолчанию эта функция предназначена для экранирования части пути URL. Необязательный параметр safe задаёт дополнительные символы ASCII, которые не следует экранировать – его значение по умолчанию – '/'.

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

Строка может быть либо 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)¶

Преобразует объект отображения (mapping) или последовательность кортежей из двух элементов, которые могут содержать объекты 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: Параметр Query поддерживает объекты bytes и string.

Новое в версии 3.5: quote_via параметр.