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

Разбор URL

Функции разбора URL предназначены для разделения строки URL на компоненты или объединения компонентов URL в строку URL.

urllib.parse.urlsplit(urlstring, scheme=None, allow_fragments=True)

Разбирает URL на пять компонентов и возвращает именованный кортеж из 5 элементов именованный кортеж SplitResult или SplitResultBytes. Это соответствует общей структуре URL: scheme://netloc/path?query#fragment. Каждый элемент кортежа — строка, возможно пустая.

Показанные выше разделители не входят в результат, за исключением начальной косой черты в компоненте path, которая сохраняется, если присутствует.

Кроме того, свойство netloc разбивается на следующие дополнительные атрибуты, добавленные к возвращаемому объекту: username, password, hostname и port.

Последовательности с процентным кодированием не декодируются.

Например:

>>> from urllib.parse import urlsplit
>>> urlsplit("scheme://netloc/path?query#fragment")
SplitResult(scheme='scheme', netloc='netloc', path='/path',
            query='query', fragment='fragment')
>>> o = urlsplit("http://docs.python.org:80/3/library/urllib.parse.html?"
...              "highlight=params#url-parsing")
>>> o
SplitResult(scheme='http', netloc='docs.python.org:80',
            path='/3/library/urllib.parse.html',
            query='highlight=params', fragment='url-parsing')
>>> o.scheme
'http'
>>> o.netloc
'docs.python.org:80'
>>> o.hostname
'docs.python.org'
>>> o.port
80
>>> o._replace(fragment="").geturl()
'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'

Согласно синтаксическим спецификациям RFC 1808, urlsplit() распознаёт netloc только в том случае, если перед ним правильно указано «//». В противном случае предполагается, что входные данные представляют собой относительный URL, начинающийся с компонента пути.

>>> from urllib.parse import urlsplit
>>> urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')
SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            query='', fragment='')
>>> urlsplit('www.cwi.nl/%7Eguido/Python.html')
SplitResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',
            query='', fragment='')
>>> urlsplit('help/Python.html')
SplitResult(scheme='', netloc='', path='help/Python.html',
            query='', fragment='')

Аргумент scheme задаёт схему адресации по умолчанию, которая используется, только если URL не задаёт собственную. Он должен иметь тот же тип (текст или байты), что и urlstring, за исключением значения по умолчанию '', которое всегда допустимо и при необходимости автоматически преобразуется в b''.

Если аргумент allow_fragments имеет значение false, идентификаторы фрагментов не распознаются. Вместо этого они разбираются как часть компонента пути, параметров или запроса, а fragment в возвращаемом значении устанавливается в пустую строку.

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

Атрибут	Индекс	Значение	Значение при отсутствии
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 нормализован до разбора, исключение вызвано не будет.

В соответствии с некоторыми положениями спецификации WHATWG, обновляющей RFC 3986, начальные управляющие символы C0 и пробелы удаляются из URL. Символы \n, \r и табуляции \t удаляются из URL в любой позиции.

Как и у всех именованных кортежей, у этого подкласса есть несколько дополнительных методов и атрибутов, которые могут быть особенно полезны. Один из таких методов — _replace(). Метод _replace() возвращает новый объект SplitResult, в котором указанные поля заменены новыми значениями.

>>> from urllib.parse import urlsplit
>>> u = urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')
>>> u
SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            query='', fragment='')
>>> u._replace(scheme='http')
SplitResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            query='', fragment='')

Предупреждение

urlsplit() не выполняет проверку корректности. Подробнее см. в разделе Безопасность при разборе URL.

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

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

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

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

Изменено в версии 3.10: Из URL удаляются символы ASCII новой строки и табуляции.

Изменено в версии 3.12: Из URL удаляются начальные управляющие символы WHATWG C0 и пробелы.

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

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

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

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

Необязательный аргумент separator задаёт символ, используемый для разделения аргументов запроса. По умолчанию используется &.

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

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

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

Изменено в версии 3.10: Добавлен параметр separator со значением по умолчанию &. В версиях Python до Python 3.10 в качестве разделителя параметров запроса можно было использовать и ;, и &. Это изменено: теперь допускается только один ключ-разделитель, а разделителем по умолчанию является &.

Устарело с версии 3.14: Использование объектов с ложным значением (например, 0 и []), за исключением пустых строк, байтовых объектов и None, теперь считается устаревшим.

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

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

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

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

Необязательный аргумент separator задаёт символ, используемый для разделения аргументов запроса. По умолчанию используется &.

Чтобы преобразовать такие списки пар в строки запроса, используйте функцию urllib.parse.urlencode().

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

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

Изменено в версии 3.10: Добавлен параметр separator со значением по умолчанию &. В версиях Python до Python 3.10 в качестве разделителя параметров запроса можно было использовать и ;, и &. Это изменено: теперь допускается только один ключ-разделитель, а разделителем по умолчанию является &.

urllib.parse.urlunsplit(parts)

Создаёт URL из кортежа, возвращаемого функцией urlsplit(). Аргумент parts может быть любым итерируемым объектом из пяти элементов. В результате может получиться немного отличающийся, но эквивалентный URL, если в исходном разобранном URL были ненужные разделители (например, ? с пустым запросом; согласно RFC, такие варианты эквивалентны).

urllib.parse.urlparse(urlstring, scheme=None, allow_fragments=True)

Эта функция похожа на urlsplit(), но дополнительно разделяет компонент path на path и params. Функция возвращает именованный кортеж из 6 элементов именованный кортеж ParseResult или ParseResultBytes. Его элементы совпадают с элементами результата urlsplit(), за исключением того, что params вставляется под индексом 3, между path и query.

Эта функция основана на устаревших RFC 1738 и RFC 1808, в которых params указывался как основной компонент URL. Более современный синтаксис URL допускает применение параметров к каждому сегменту части path URL (см. RFC 3986). Обычно вместо urlparse() следует использовать urlsplit(). Для разделения сегментов пути и параметров требуется отдельная функция.

urllib.parse.urlunparse(parts)

Объединяет элементы кортежа, возвращаемого функцией urlparse(), в полный 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 имеет то же значение и значение по умолчанию, что и у urlsplit().

Примечание

Если 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.

Предупреждение

Поскольку в качестве параметра url может быть передан абсолютный URL, использовать urljoin с контролируемым злоумышленником значением url обычно небезопасно. Например, в urljoin("https://website.com/users/", username), если username может содержать абсолютный URL, результатом urljoin будет этот абсолютный URL.

Изменено в версии 3.5: Поведение обновлено в соответствии с семантикой, определённой в RFC 3986.

urllib.parse.urldefrag(url)

Если url содержит идентификатор фрагмента, возвращает изменённую версию url без идентификатора фрагмента, а сам идентификатор фрагмента — отдельной строкой. Если в url нет идентификатора фрагмента, возвращает url без изменений и пустую строку.

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

Атрибут	Индекс	Значение	Значение при отсутствии
url	0	URL без фрагмента	пустая строка
fragment	1	Идентификатор фрагмента	пустая строка

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

Изменено в версии 3.2: Результат теперь является структурированным объектом, а не простым кортежем из двух элементов.

urllib.parse.unwrap(url)

Извлекает URL из обёрнутого URL (то есть строки в формате <URL:scheme://host/path>, <scheme://host/path>, URL:scheme://host/path или scheme://host/path). Если url не является обёрнутым URL, он возвращается без изменений.

Безопасность при разборе URL

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

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

Мы рекомендуем пользователям этих API, если полученные значения могут применяться в контекстах, связанных с безопасностью, писать защитный код. Проверяйте данные в своём коде, прежде чем доверять возвращаемому компоненту. Имеет ли этот scheme смысл? Является ли это разумным path? Нет ли чего-нибудь подозрительного в этом hostname? И так далее.

Общепринятого определения URL не существует. У разных приложений разные потребности и ограничения. Например, развивающаяся спецификация WHATWG описывает требования пользовательских веб-клиентов, таких как браузеры, тогда как RFC 3986 имеет более общий характер. Эти функции учитывают некоторые аспекты обоих стандартов, но не могут считаться соответствующими ни одному из них. API и существующий пользовательский код, поведение которых опирается на определённые особенности, появились раньше обоих стандартов, поэтому мы очень осторожно относимся к изменению поведения API.

Разбор байтов в кодировке ASCII

Изначально функции разбора URL были предназначены только для работы со строками символов. На практике полезно иметь возможность обрабатывать правильно экранированные и закодированные URL как последовательности байтов ASCII. Поэтому все функции разбора URL в этом модуле работают не только с объектами str, но и с объектами bytes и bytearray.

Если переданы данные типа 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.

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

Объекты результатов, возвращаемые функциями urlsplit(), urlparse() и 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: При экранировании строк URL стандарт RFC 2396 заменён на RFC 3986. Символ «~» теперь входит в набор незарезервированных символов.

Необязательные параметры encoding и errors задают способ обработки символов, не относящихся к ASCII, согласно правилам метода str.encode(). Хотя в сигнатуре функции значения этих параметров по умолчанию равны None, при обработке входных данных типа str фактическим значением encoding по умолчанию является 'utf-8', а errors — 'strict'. Это означает, что неподдерживаемые символы вызывают исключение UnicodeEncodeError. Если string имеет тип bytes, параметры encoding и errors указывать нельзя, иначе будет вызвано исключение 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 задают способ декодирования последовательностей с процентным кодированием в символы Unicode согласно правилам метода bytes.decode().

string может быть объектом str или bytes.

Значение encoding по умолчанию — 'utf-8'. Значение errors по умолчанию — 'replace', поэтому некорректные последовательности заменяются символом-заполнителем.

Пример: unquote('/El%20Ni%C3%B1o/') возвращает '/El Niño/'.

Изменено в версии 3.9: Параметр string поддерживает объекты bytes и str (ранее поддерживались только объекты str).

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: там показано, как применять метод urllib.parse.urlencode() для формирования строки запроса URL или данных для POST-запроса.

Изменено в версии 3.2: Аргумент query поддерживает объекты bytes и string.

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

Устарело с версии 3.14: Использование объектов с ложным значением (например, 0 и []), за исключением пустых строк, байтовых объектов и None, теперь считается устаревшим.