urllib.parse — Разбор 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
>>> urlparse("scheme://netloc/path;parameters?query#fragment")
ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='',
            query='query', fragment='fragment')
>>> o = urlparse("http://docs.python.org:80/3/library/urllib.parse.html?"
...              "highlight=params#url-parsing")
>>> o
ParseResult(scheme='http', netloc='docs.python.org:80',
            path='/3/library/urllib.parse.html', params='',
            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, 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='')

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

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

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

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

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

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

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 определяют, как декодировать проценты закодированные последовательности в символы Юникода, как это принимается методом bytes.decode().

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

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

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

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

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

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

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 — максимальное количество полей для чтения. Если задано, то выбросит исключение ValueError, если прочитано более max_num_fields полей.

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

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

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

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

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

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 разложен перед разбором, ошибка не будет поднята.

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

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

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

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

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

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

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

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 элементов.

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? и т. д.

Разбор 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')

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

строка может быть как объектом 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-форм.

строка должна быть объектом str.

Пример: unquote_plus('/El+Ni%C3%B1o/') даёт '/El Niño/'.

urllib.parse.unquote_to_bytes(string)

Заменить %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 текста с процентным кодированием. Если полученная строка должна использоваться как данные для операции 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.