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 и, следовательно, начинаются с компонента path.

>>> 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	Параметры для последнего элемента path	пустая строка
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 parsing security.

Изменено в версии 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 определяют, как декодировать последовательности, закодированные в процентах, в символы Юникода, как это принято в методе 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-адреса path (см. 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-адресе указан недопустимый порт. Дополнительную информацию о результирующем объекте смотрите в разделе Структурированные результаты синтаксического анализа.

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

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

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

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

urlsplit() проверка не выполняется. Подробности см. в URL parsing security.

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

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

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

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

urllib.parse.urlunsplit(parts)¶

Объедините элементы кортежа, возвращаемые с помощью urlsplit(), в полный URL-адрес в виде строки. Аргумент parts может быть любым из пяти повторяемых элементов. Это может привести к получению немного отличающегося, но эквивалентного URL-адреса, если URL-адрес, который был проанализирован изначально, содержал ненужные разделители (например, a? с пустым запросом; в 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: Результатом является структурированный объект, а не простой кортеж из 2 элементов.

urllib.parse.unwrap(url)¶

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

Безопасность анализа URL-адресов¶

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

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

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

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

Синтаксический анализ байтов, закодированных в формате 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, используя escape-команду %xx. Буквы, цифры и символы '_.-~' никогда не заключаются в кавычки. По умолчанию эта функция предназначена для указания пути в URL-адресе. Необязательный параметр safe указывает дополнительные символы ASCII, которые не следует заключать в кавычки - его значение по умолчанию равно '/'.

строка может быть либо str, либо bytes объектом.

Изменено в версии 3.7: Изменено значение RFC 2396 на RFC 3986 для цитирования строк URL-адресов. «~» теперь включен в набор символов, не подлежащих кавычкам.

Необязательные параметры encoding и errors определяют, как работать с символами, отличными от ASCII, в соответствии с методом str.encode(). encoding по умолчанию имеет значение 'utf-8'. ошибки по умолчанию используется значение 'strict', что означает, что неподдерживаемые символы вызывают UnicodeEncodeError. кодировка и ошибки не должны указываться, если строка равна 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 объектом.

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

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

Изменено в версии 3.9: параметр string поддерживает байты и объекты 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, в 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.

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

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