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-адресов. Эти функции подробно рассматриваются в следующих разделах.

Разбор 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   
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 не равен false), в соответствии с RFC 3986. Раньше существовал белый список схем, поддерживающих фрагменты.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.7.3: Символы, влияющие на разбор 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-кортеж.

Разбор байтов, закодированных в 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.

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

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

Замените специальные символы в строке, используя escape-последовательность %xx. Буквы, цифры и символы '_.-~' никогда не экранируются. По умолчанию, эта функция предназначена для экранирования секции пути URL. Необязательный параметр safe определяет дополнительные ASCII-символы, которые не должны экранироваться — его значение по умолчанию '/'.

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

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

Строка должна быть 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-форм.

Строка должна быть str.

Пример: unquote_plus('/El+Ni%C3%B1o/') приводит к '/El Niño/'.

urllib.parse.unquote_to_bytes(string)

Заменяет escape-последовательности %xx на их однобайтовые эквиваленты и возвращает объект bytes.

Строка может быть как str, так и bytes.

Если это str, то не-ASCII символы в строке кодируются в 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, где как ключ, так и значение кодируются с помощью функции quote_via. По умолчанию используется quote_plus() для кодирования значений, что означает, что пробелы кодируются как '+' символ, а символы ‘/’ кодируются как %2F, что соответствует стандарту для запросов GET (application/x-www-form-urlencoded). Альтернативная функция, которая может быть передана в качестве quote_via, это quote(), которая закодирует пробелы как %20 и не закодирует символы ‘/’. Для максимального контроля над тем, что кодируется, используйте quote и укажите значение для safe.

Когда в качестве аргумента query используется последовательность пар из двух элементов, первый элемент каждой пары — это ключ, а второй — значение. Значение само по себе может быть последовательностью, и в этом случае, если необязательный параметр doseq равен True, отдельные пары ключ-значение, разделённые символами '&', генерируются для каждого элемента последовательности значений для ключа. Порядок параметров в закодированной строке будет соответствовать порядку пар параметров в последовательности.

Параметры safe, encoding и errors передаются в quote_via (параметры encoding и errors передаются только тогда, когда элемент запроса является str).

Для обратного преобразования этой кодировки в этом модуле предоставляются parse_qs() и parse_qsl() для разбора строк запроса в структуры данных Python.

Обратитесь к urllib examples для получения информации о том, как использовать метод urlencode для генерации строки запроса для URL или данных для POST.

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

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