urlparse — Разбор URL на составляющие

Исходный код: Lib/urlparse.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.

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

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

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

>>> from urlparse 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 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: Добавлены возможности разбора IPv6 URL.

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

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

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

Используйте функцию 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). Данные возвращаются в виде списка пар имя-значение.

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

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

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

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

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

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

Дополнительную информацию об объекте результата см. в разделе Результаты urlparse() и urlsplit().

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

В версии 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 без изменений и пустую строку.

1. Результаты urlparse() и urlsplit()

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

ParseResult.geturl()

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

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

>>> 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().