urllib.parse — Разбор URL-адресов на составляющие

Исходный код: Lib/urllib/parse.py

Этот модуль определяет стандартный интерфейс для разбиения строк URL (Uniform Resource Locator) на составляющие (схема адресации, сетевое расположение, путь и т. д.), для объединения составляющих обратно в строку URL и для преобразования «относительного URL» в абсолютный URL, заданный «базовым URL».

Модуль разработан в соответствии с интернет-RFC по относительным URL. Он поддерживает следующие схемы URL: file, ftp, gopher, hdl, http, https, imap, mailto, mms, news, nntp, prospero, rsync, rtsp, rtspu, sftp, shttp, sip, sips, snews, svn, svn+ssh, telnet, wais, ws, wss.

Модуль urllib.parse определяет функции, которые можно разделить на две широкие категории: разбор URL и кодирование URL. Эти функции подробно рассматриваются в следующих разделах.

21.8.1. Разбор URL

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

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

Разбирает URL на шесть составляющих, возвращая 6-кортеж. Это соответствует общему структуре URL: scheme://netloc/path;parameters?query#fragment. Каждый элемент кортежа — это строка, возможно пустая. Составляющие не разбиваются на более мелкие части (например, сетевое расположение — это одна строка), и обратные слэши не расширяются. Разделители, как показано выше, не являются частью результата, за исключением ведущего слэша в компоненте путь, который сохраняется, если он присутствует. Например:

>>> from urllib.parse import urlparse
>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
>>> o   
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> o.scheme
'http'
>>> o.port
80
>>> o.geturl()
'http://www.cwi.nl:80/%7Eguido/Python.html'

В соответствии с синтаксическими спецификациями в RFC 1808, urlparse распознаёт netloc только если он должным образом введен с помощью ‘//’. В противном случае вход интерпретируется как относительный URL, а следовательно, начинается с компонента пути.

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

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

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

Возвращаемое значение фактически представляет собой экземпляр подкласса tuple. Этот класс имеет следующие дополнительные удобные атрибуты только для чтения:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

urllib.parse.urlunparse(parts)

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

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

Это аналогично urlparse(), но не разделяет параметры от URL. Это следует использовать вместо urlparse(), если требуется более новая синтаксическая конструкция URL, позволяющая применять параметры к каждому сегменту части path URL (см. RFC 2396). Для разделения сегментов пути и параметров требуется отдельная функция. Эта функция возвращает 5-кортеж: (схема адресации, сетевое расположение, путь, запрос, идентификатор фрагмента).

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

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

Чтение атрибута port вызовет ValueError, если в URL указан недопустимый порт. Подробности о результате объекта см. в разделе Структурированные результаты разбора.

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

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

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

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

urllib.parse.urlunsplit(parts)

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

urllib.parse.urljoin(base, url, allow_fragments=True)

Составление полного («абсолютного») URL путем объединения «базового URL» (base) с другим URL (url). Неформально, это использует компоненты базового URL, в частности схему адресации, сетевое расположение и (часть) пути, чтобы предоставить отсутствующие компоненты в относительном URL. Например:

>>> from urllib.parse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'

Аргумент allow_fragments имеет то же значение и значение по умолчанию, что и для urlparse().

Примечание

Если url — абсолютный URL (т. е., начинающийся с // или scheme://), имя хоста и/или схема url будут присутствовать в результате. Например:

>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
...         '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'

Если вы не хотите этого поведения, предварительно обработайте url с помощью urlsplit() и urlunsplit(), удалив возможные части scheme и netloc.

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

urllib.parse.urldefrag(url)

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

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

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

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

Изменено в версии 3.2: Результат — структурированный объект, а не простой 2-кортеж.

21.8.2. Разбор ASCII-кодированных байтов

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

Если передаются данные типа str, результат также будет содержать только данные типа str. Если передаются данные типа bytes или bytearray, результат будет содержать только данные типа bytes.

Попытка смешать данные типа str с данными типа bytes или bytearray в одном вызове функции приведет к возбуждению исключения TypeError, а попытка передачи байтовых значений, не являющихся ASCII, вызовет UnicodeDecodeError.

Для облегчения преобразования объектов результатов между str и bytes все возвращаемые значения функций парсинга URL предоставляют либо метод encode() (когда результат содержит данные типа str), либо метод decode() (когда результат содержит данные типа bytes). Подписи этих методов соответствуют подписям соответствующих методов str и bytes (за исключением того, что кодировка по умолчанию — 'ascii', а не 'utf-8'). Каждый из них производит значение соответствующего типа, содержащее либо данные типа bytes (для методов encode()), либо данные типа str (для методов decode()).

Приложениям, которым необходимо работать с потенциально неправильно процитированными URL, которые могут содержать данные, не являющиеся ASCII, необходимо выполнить собственное декодирование из байтов в символы перед вызовом методов парсинга URL.

Описание поведения в этом разделе относится только к функциям парсинга URL. Функции цитирования URL используют свои собственные правила при создании или использовании последовательностей байтов, как подробно описано в документации по отдельным функциям цитирования URL.

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

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

21.8.4. Кодирование URL

Функции кодирования URL сосредоточены на приёме данных программы и обеспечении их безопасности в качестве компонентов URL путём цитирования специальных символов и правильного кодирования данных, не являющихся ASCII. Они также поддерживают обращение этих операций для восстановления исходных данных из содержимого компонента URL, если эта задача не решена функциями парсинга URL выше.

urllib.parse.quote(string, safe='/', encoding=None, errors=None)

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

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

Опциональные параметры 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().

string должен быть объектом str.

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

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

urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')

Как unquote(), но также заменяет знаки плюс на пробелы, как требуется для раскодирования значений HTML-форм.

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 разделенных символами '&', где и ключ и значение кодируются с использованием функции 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, чтобы узнать, как метод urlencode можно использовать для генерации строки запроса для URL или данных для POST.

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

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