urllib.parse – Разбор URL на компоненты¶urllib.parse – Parse URLs into components

Разбор URL¶URL Parsing

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

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

Разбирает URL на пять компонентов и возвращает именованный кортеж из пяти элементов 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: Символы ASCII перевода строки и табуляции удаляются из URL.

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

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 до 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 до 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 (см. 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¶URL parsing security

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

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

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

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

Разбор ASCII-кодированных байтов¶Parsing ASCII Encoded Bytes

Функции разбора 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.

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

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

Функции экранирования 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 задают способ декодирования процентно-кодированных последовательностей в символы 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)¶

Преобразует объект отображения (mapping) или последовательность кортежей из двух элементов, которые могут содержать объекты 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, для каждого элемента последовательности значений по данному ключу генерируются отдельные пары 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, теперь считается устаревшим.