Содержание страницы

20.16. `urlparse` – Разбор URL на составные части¶urlparse – Parse URLs into components

Примечание

Модуль urlparse переименован в urllib.parse в Python 3. Инструмент 2to3 автоматически адаптирует импорты при преобразовании исходных кодов в Python 3.

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

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

Модуль спроектирован в соответствии с RFC на относительные URL. Он поддерживает следующие схемы 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.

Новое в версии 2.5: Поддержка схем sftp и sips.

Модуль urlparse определяет следующие функции:

urlparse.urlparse(urlstring[, scheme[, allow_fragments]])¶

Разбирает URL на шесть компонентов и возвращает кортеж из шести элементов. Это соответствует общей структуре URL: scheme://netloc/path;parameters?query#fragment. Каждый элемент кортежа – строка, возможно пустая. Компоненты не разбиваются на более мелкие части (например, сетевое расположение – это одна строка), а процентные экранирования не раскрываются. Разделители, показанные выше, не являются частью результата, за исключением начального слеша в компоненте path, который сохраняется, если присутствует. Например:

>>> from urlparse 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 urlparse 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 сам её не указывает. Значение по умолчанию для этого аргумента – пустая строка.

Если аргумент allow_fragments равен false, идентификаторы фрагментов не распознаются и разбираются как часть предыдущего компонента, даже если схема адресации URL обычно их поддерживает. Значение этого аргумента по умолчанию – True.

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

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

См. раздел Результаты urlparse() и urlsplit() для получения дополнительной информации о результирующем объекте.

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

Изменено в версии 2.5: Добавлены атрибуты возвращаемого значения.

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

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

urlparse.parse_qs(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])¶

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

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

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

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

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

Новое в версии 2.6: Скопировано из модуля cgi.

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

urlparse.parse_qsl(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])¶

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

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

Новое в версии 2.6: Скопировано из модуля cgi.

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

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

urlparse.urlsplit(urlstring[, scheme[, allow_fragments]])¶

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

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

См. раздел Результаты urlparse() и urlsplit() для получения дополнительной информации о результирующем объекте.

Новое в версии 2.2.

Изменено в версии 2.5: Добавлены атрибуты возвращаемого значения.

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

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

Новое в версии 2.2.

urlparse.urljoin(base, url[, allow_fragments])¶

Собирает полный («абсолютный») URL, объединяя «базовый URL» (base) с другим URL (url). Неформально говоря, используются компоненты базового URL, в частности схема адресации, сетевое расположение и (часть) пути, чтобы заполнить отсутствующие компоненты в относительном URL. Например:

>>> from urlparse 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.

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

См. также

RFC 3986 – Uniform Resource Identifiers: Это текущий стандарт (STD66). Любые изменения модуля urlparse должны ему соответствовать. Могут наблюдаться некоторые отклонения, которые в основном обусловлены обратной совместимостью и определёнными фактическими требованиями к разбору, как это обычно принято в основных браузерах.
RFC 2732 – Формат литеральных IPv6-адресов в URL.: В нём описываются требования к парсингу IPv6 URL.
RFC 2396 – Uniform Resource Identifiers (URI): Generic Syntax: Документ, описывающий общие синтаксические требования как для Uniform Resource Names (URN), так и для Uniform Resource Locators (URL).
RFC 2368 – Схема URL mailto.: Требования к парсингу схем URL mailto.
RFC 1808 – Relative Uniform Resource Locators: Этот документ (RFC) включает правила объединения абсолютного и относительного URL, включая значительное количество «Аномальных примеров», которые определяют обработку граничных случаев.
RFC 1738 – Uniform Resource Locators (URL): В нём описывается формальный синтаксис и семантика абсолютных URL.

20.16.1. Результаты `urlparse()` и `urlsplit()`¶Results of urlparse() and urlsplit()

Объекты-результаты функций urlparse() и urlsplit() являются подклассами типа tuple. Эти подклассы добавляют атрибуты, описанные в этих функциях, а также предоставляют дополнительный метод:

ParseResult.geturl()¶

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

Результат этого метода является неподвижной точкой (fixpoint), если передать его обратно в исходную функцию разбора:

>>> import urlparse
>>> url = 'HTTP://www.Python.org/doc/#'

>>> r1 = urlparse.urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'

>>> r2 = urlparse.urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'

Новое в версии 2.5.

Следующие классы предоставляют реализацию результатов разбора:

class urlparse.ParseResult(scheme, netloc, path, params, query, fragment)¶: Конкретный класс для результатов urlparse().

class urlparse.SplitResult(scheme, netloc, path, query, fragment)¶: Конкретный класс для результатов urlsplit().

20.16. urlparse – Разбор URL на составные части¶urlparse – Parse URLs into components

20.16.1. Результаты urlparse() и urlsplit()¶Results of urlparse() and urlsplit()

20.16. `urlparse` – Разбор URL на составные части¶urlparse – Parse URLs into components

20.16.1. Результаты `urlparse()` и `urlsplit()`¶Results of urlparse() and urlsplit()