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

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


Модуль определяет стандартный интерфейс для разрыва Единого указателя ресурса (Uniform Resource Locator, URL) на строки из компонент (схема адресации, сетевое расположение, путь и т.д.), для объединения компонентов обратно в строка 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, ws, wss.

Модуль urllib.parse определяет функции, которые подразделяются на две широкие категории: URL парсинг и 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   # 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 устанавливается в пустой строкой в возвращаемой значении.

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

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

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

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

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

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

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

Изменено в версии 3.8: Символы, влияющие на парсинг 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 не изменен и пустой строка.

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

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

Изменено в версии 3.2: Функции парсинг URL теперь принимают последовательности кодированный байтов ASCII

Структурированные результаты парсинга

Объекты результата от 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.

По умолчанию 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 процент-кодированной строки. Если результирующий строка должен быть используемый как data для операции POST с функцией urlopen(), то он должен быть кодированный в байты, в противном случае это приведет к TypeError.

Результирующая строка представляет собой ряд пар key=value, разделённых '&' символами, где и 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 параметр.

См.также

RFC 3986 - унифицированные идентификаторы ресурсов
Текущий стандарт (STD66). Любые изменения модуля urllib.parse должны соответствовать этому. Можно было бы наблюдать некоторые отклонения, которые в основном предназначены для целей обратной совместимости и для определенных фактических требований к парсинг, как это обычно наблюдается в основных браузерах.
RFC 2732 - формат для адресов IPv6 литералов в URL-адресах.
Указывает требования к парсинг IPv6 URL-адресов.
RFC 2396 - Uniform Resource Identifiers (URI): Общий синтаксис
Документ, описывающий общие синтаксические требования как для унифицированных имен ресурсов (URN), так и для унифицированных локаторов ресурсов (URL).
RFC 2368 - схема URL-адресов почтовых отправлений.
Анализ требований к схемам URL-адресов почтовых сообщений.
RFC 1808 - относительные унифицированные локаторы ресурсов
Запрос на комментарии включает правила присоединения абсолютного и относительного URL, включая значительное количество «ненормальных примеров», которые регулируют обработку пограничных случаев.
RFC 1738 - Uniform Resource Locators (URL)
Задает формальный синтаксис и семантику абсолютных URL-адресов.