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

Исходный код: Lib/urllib/parse.py

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

Модуль разработан в соответствии с RFC Интернета относительно относительных Uniform Resource Locators. Он поддерживает следующие схемы 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, ws, wss.

Модуль urllib.parse определяет функции, которые можно разделить на две основные категории: разбор URL и кодирование URL. Они подробно рассмотрены в следующих разделах.

1. Разбор 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   # 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/%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

См. раздел Структурированные результаты разбора для получения дополнительной информации об объекте результата.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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: Результат — структурированный объект, а не простой 2-кортеж.

2. Разбор 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.

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

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

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

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

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

Заменяет специальные символы в строке с использованием кодирования %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 на их эквиваленты из одного октета и возвращает байтовый объект 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 с кодировкой процентов. Если полученная строка должна быть использована в качестве данных для операции 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 examples, чтобы узнать, как можно использовать метод urlencode для создания строки запроса для URL или данных для POST.

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

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