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

Разбор URL-адресов¶

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

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

Разбирает URL на шесть компонентов, возвращая 6 элементов named tuple. Это соответствует общей структуре 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 устанавливается пустая строка.

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

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

Чтение атрибута port вызовет ошибку ValueError, если в URL указан недопустимый порт. Дополнительную информацию об объекте result см. в разделе Результаты структурированного разбора.

Несовпадение квадратных скобок в атрибуте 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: Добавлена возможность разбора 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 указывают, как декодировать закодированные в процентах последовательности в символы Unicode, принимаемые методом 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, позволяющий применять параметры к каждому сегменту пути части URL (см. RFC 2396). Для разделения сегментов пути и параметров необходима отдельная функция. Эта функция возвращает 5-элементный named tuple:

(addressing scheme, network location, path, query, fragment identifier).

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

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

Чтение атрибута port вызовет ошибку ValueError, если в URL указан недопустимый порт. Дополнительную информацию об объекте result см. в разделе Результаты структурированного разбора.

Несовпадение квадратных скобок в атрибуте netloc вызовет ошибку ValueError.

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

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

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

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

Изменено в версии 3.10: Символы новой строки и табуляции ASCII удаляются из 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 немодифицированным и пустую строку.

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

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

Разбор байтов в кодировке 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)¶

Замените специальные символы в 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'. ошибки по умолчанию '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.

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 с процентной кодировкой. Если полученная строка будет использоваться в качестве данных для операции 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 examples, чтобы узнать, как метод urllib.parse.urlencode() можно использовать для генерации строки запроса URL или данных для POST-запроса.

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

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