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

Источник: Lib/urllib/parse.py

---

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

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

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

В функциях этого модуля используется устаревший термин netloc (или net_loc), который был введен в RFC 1808. Однако этот термин был устаревшим в RFC 3986, который ввел термин authority в качестве его замены. Использование netloc продолжается для обратной совместимости.

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

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

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 (см. 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 удаляются ведущие управляющие символы C0 и пробелы. Символы \n, \r и табуляция \t удаляются из URL в любой позиции.

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

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

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

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

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

Изменено в версии 3.12: Ведущие управляющие символы WHATWG C0 и пробелы удаляются из 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	Идентификатор фрагмента	пустая строка

Дополнительные сведения об объекте result см. в разделе Результаты структурированного разбора.

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

urllib.parse.unwrap(url)

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

Безопасность разбора URL-адресов

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

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

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

Определение URL-адреса не является универсальным. Различные приложения имеют разные потребности и желаемые ограничения. Например, живая 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.

Изменено в версии 3.2: Функции разбора URL теперь принимают последовательности байтов в ASCII-кодировке

Результаты структурированного разбора

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

Added in version 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.

Added in version 3.2.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)

Конкретный класс для urlparse() результатов, содержащих bytes данные. Метод decode() возвращает экземпляр ParseResult.

Added in version 3.2.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)

Конкретный класс для urlsplit() результатов, содержащих bytes данные. Метод decode() возвращает экземпляр SplitResult.

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

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

См.также

WHATWG - URL Уровень жизни

Рабочая группа по стандарту URL, определяющая URL, домены, IP-адреса, формат application/x-www-form-urlencoded и их API.

RFC 3986 - Единые идентификаторы ресурсов

Это текущий стандарт (STD66). Любые изменения в модуле urllib.parse должны соответствовать ему. Возможны некоторые отклонения, в основном для обратной совместимости и для некоторых де-факто требований к разбору, как это обычно наблюдается в основных браузерах.

RFC 2732 - Формат для буквенных IPv6-адресов в URL.

Здесь указываются требования к разбору URL-адресов IPv6.

RFC 2396 - Унифицированные идентификаторы ресурсов (URI): общий синтаксис

Документ, описывающий общие синтаксические требования к унифицированным именам ресурсов (URN) и унифицированным локаторам ресурсов (URL).

RFC 2368 - Схема URL-адреса mailto.

Требования к разбору схем URL mailto.

RFC 1808 - Относительные унифицированные указатели ресурсов

Этот запрос на комментарии включает правила соединения абсолютного и относительного URL, а также достаточное количество «Ненормальных примеров», которые регулируют обработку пограничных случаев.

RFC 1738 - Единые указатели ресурсов (URL)

Это определяет формальный синтаксис и семантику абсолютных URL.