`urllib.parse.md`

392 строк · 48.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.6/library/urllib.parse.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 21.8. [`urllib.parse`](https://python-all.ru/3.6/library/urllib.parse.html#module-urllib.parse) – Разбор URL на составные части89**Исходный код:** [Lib/urllib/parse.py](https://python-all.ru/src/3.6/Lib/urllib/parse.py)1011---1213Этот модуль предоставляет стандартный интерфейс для разбора строки URL на компоненты (схема адресации, сетевое расположение, путь и т.д.), обратной сборки компонентов в строку URL, а также для преобразования «относительного URL» в абсолютный по заданному «базовому URL».1415Модуль спроектирован в соответствии с интернет-стандартом RFC на относительные унифицированные указатели ресурсов. Он поддерживает следующие схемы 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`.1617Модуль [`urllib.parse`](https://python-all.ru/3.6/library/urllib.parse.html#module-urllib.parse) определяет функции, которые делятся на две большие категории: разбор URL и квотирование URL. Они подробно рассматриваются в следующих разделах.1819## 21.8.1. Разбор URL2021Функции разбора URL предназначены для разделения строки URL на компоненты или для объединения компонентов URL в строку URL.2223#### `urllib.parse.urlparse(urlstring, scheme='', allow_fragments=True)`2425Разбирает URL на шесть компонентов и возвращает кортеж из шести элементов. Это соответствует общей структуре URL: `scheme://netloc/path;parameters?query#fragment`. Каждый элемент кортежа – строка, возможно пустая. Компоненты не разбиваются на более мелкие части (например, сетевое расположение – это одна строка), а процентные экранирования не раскрываются. Разделители, показанные выше, не являются частью результата, за исключением начального слеша в компоненте *path*, который сохраняется, если присутствует. Например:2627```python28>>> from urllib.parse import urlparse29>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')30>>> o   31ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',32            params='', query='', fragment='')33>>> o.scheme34'http'35>>> o.port368037>>> o.geturl()38'http://www.cwi.nl:80/%7Eguido/Python.html'39```4041Следуя синтаксическим спецификациям [**RFC 1808**](https://python-all.ru/3.6/library/urllib.parse.html), urlparse распознаёт netloc только в том случае, если она правильно введена символами '//'. В противном случае считается, что входные данные – это относительный URL, и, следовательно, они начинаются с компонента пути.4243```python44>>> from urllib.parse import urlparse45>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')46ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',47           params='', query='', fragment='')48>>> urlparse('www.cwi.nl/%7Eguido/Python.html')49ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',50           params='', query='', fragment='')51>>> urlparse('help/Python.html')52ParseResult(scheme='', netloc='', path='help/Python.html', params='',53           query='', fragment='')54```5556Аргумент *scheme* задаёт схему адресации по умолчанию, которая используется только если URL её не указывает. Он должен быть того же типа (текст или байты), что и *urlstring*, за исключением того, что значение по умолчанию `''` всегда разрешено и автоматически преобразуется в `b''` при необходимости.5758Если аргумент *allow\_fragments* равен false, идентификаторы фрагментов не распознаются. Вместо этого они анализируются как часть пути, параметров или компонента запроса, а `fragment` в возвращаемом значении устанавливается в пустую строку.5960Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/3.6/library/stdtypes.html#tuple). У этого класса есть следующие дополнительные атрибуты только для чтения:6162| Атрибут | Индекс | Значение | Значение, если отсутствует |63| --- | --- | --- | --- |64| `scheme` | 0 | Спецификатор схемы URL | Параметр *scheme* |65| `netloc` | 1 | Сетевое расположение | пустая строка |66| `path` | 2 | Иерархический путь | пустая строка |67| `params` | 3 | Параметры последнего элемента пути | пустая строка |68| `query` | 4 | Компонент запроса | пустая строка |69| `fragment` | 5 | Идентификатор фрагмента | пустая строка |70| `username` |  | Имя пользователя | [`None`](https://python-all.ru/3.6/library/constants.html#None) |71| `password` |  | Пароль | [`None`](https://python-all.ru/3.6/library/constants.html#None) |72| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/3.6/library/constants.html#None) |73| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/3.6/library/constants.html#None) |7475Чтение атрибута `port` возбуждает [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError), если в URL указан недопустимый порт. Дополнительную информацию об объекте результата см. в разделе [Результаты структурированного разбора](https://python-all.ru/3.6/library/urllib.parse.html#urlparse-result-object).7677Непарные квадратные скобки в атрибуте `netloc` возбуждают [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError).7879Символы в атрибуте `netloc`, которые при NFKC-нормализации (используемой в кодировке IDNA) раскладываются в любой из `/`, `?`, `#`, `@` или `:`, возбуждают [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError). Если URL разложен до разбора, ошибка не возникнет.8081Изменено в версии 3.2: Добавлена возможность разбора URL с IPv6.8283Изменено в версии 3.3: Теперь фрагмент разбирается для всех схем URL (если только *allow\_fragment* не равно false), в соответствии с [**RFC 3986**](https://python-all.ru/3.6/library/urllib.parse.html). Ранее существовал белый список схем, поддерживающих фрагменты.8485Изменено в версии 3.6: Номера портов вне диапазона теперь возбуждают [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError) вместо возврата [`None`](https://python-all.ru/3.6/library/constants.html#None).8687Изменено в версии 3.6.9: Символы, влияющие на разбор netloc при нормализации NFKC, теперь вызывают [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError).8889#### `urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')`9091Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде словаря. Ключами словаря являются уникальные имена переменных запроса, а значениями – списки значений для каждого имени.9293Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение True означает, что пустые значения должны сохраняться как пустые строки. Значение False по умолчанию означает, что пустые значения игнорируются и считаются отсутствующими.9495Необязательный аргумент *strict\_parsing* – это флаг, указывающий, что делать с ошибками разбора. Если False (по умолчанию), ошибки молча игнорируются. Если True, ошибки возбуждают исключение [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError).9697Необязательные параметры *encoding* и *errors* определяют, как декодировать процентно-кодированные последовательности в символы Unicode, как это принимается методом [`bytes.decode()`](https://python-all.ru/3.6/library/stdtypes.html#bytes.decode).9899Необязательный аргумент *max\_num\_fields* – это максимальное количество полей для чтения. Если он задан, то при чтении более *max\_num\_fields* полей возбуждается [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError).100101Необязательный аргумент *separator* – это символ, используемый для разделения аргументов запроса. По умолчанию он равен `&`.102103Для преобразования таких словарей в строки запроса используется функция [`urllib.parse.urlencode()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlencode) (с параметром `doseq`, установленным в `True`).104105Изменено в версии 3.2: Добавлены параметры *encoding* и *errors*.106107Изменено в версии 3.6.8: Добавлен параметр *max\_num\_fields*.108109Изменено в версии 3.6.13: Добавлен параметр *separator* со значением по умолчанию `&`. Версии Python до 3.6.13 позволяли использовать как `;`, так и `&` в качестве разделителя параметров запроса. Это было изменено, чтобы допускать только один ключ-разделитель, при этом `&` используется по умолчанию.110111#### `urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')`112113Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде списка пар имя, значение.114115Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение True означает, что пустые значения должны сохраняться как пустые строки. Значение False по умолчанию означает, что пустые значения игнорируются и считаются отсутствующими.116117Необязательный аргумент *strict\_parsing* – это флаг, указывающий, что делать с ошибками разбора. Если False (по умолчанию), ошибки молча игнорируются. Если True, ошибки возбуждают исключение [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError).118119Необязательные параметры *encoding* и *errors* определяют, как декодировать процентно-кодированные последовательности в символы Unicode, как это принимается методом [`bytes.decode()`](https://python-all.ru/3.6/library/stdtypes.html#bytes.decode).120121Необязательный аргумент *max\_num\_fields* – это максимальное количество полей для чтения. Если он задан, то при чтении более *max\_num\_fields* полей возбуждается [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError).122123Необязательный аргумент *separator* – это символ, используемый для разделения аргументов запроса. По умолчанию он равен `&`.124125Используйте функцию [`urllib.parse.urlencode()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlencode) для преобразования таких списков пар в строки запроса.126127Изменено в версии 3.2: Добавлены параметры *encoding* и *errors*.128129Изменено в версии 3.6.8: Добавлен параметр *max\_num\_fields*.130131Изменено в версии 3.6.13: Добавлен параметр *separator* со значением по умолчанию `&`. Версии Python до 3.6.13 позволяли использовать как `;`, так и `&` в качестве разделителя параметров запроса. Это было изменено, чтобы допускать только один ключ-разделитель, при этом `&` используется по умолчанию.132133#### `urllib.parse.urlunparse(parts)`134135Собирает URL из кортежа, возвращаемого `urlparse()`. Аргумент *parts* может быть любым итерируемым объектом из шести элементов. Результат может незначительно отличаться от исходного URL, но быть эквивалентным, если исходный разобранный URL содержал лишние разделители (например, `?` с пустым запросом; RFC утверждает, что они эквивалентны).136137#### `urllib.parse.urlsplit(urlstring, scheme='', allow_fragments=True)`138139Эта функция похожа на [`urlparse()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlparse), но не отделяет параметры от URL. Её следует использовать вместо [`urlparse()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlparse), если требуется более современный синтаксис URL, позволяющий применять параметры к каждому сегменту части *path* URL (см. [**RFC 2396**](https://python-all.ru/3.6/library/urllib.parse.html)). Для разделения сегментов пути и параметров нужна отдельная функция. Эта функция возвращает кортеж из пяти элементов: (схема адресации, сетевое расположение, путь, запрос, идентификатор фрагмента).140141Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/3.6/library/stdtypes.html#tuple). У этого класса есть следующие дополнительные атрибуты только для чтения:142143| Атрибут | Индекс | Значение | Значение, если отсутствует |144| --- | --- | --- | --- |145| `scheme` | 0 | Спецификатор схемы URL | Параметр *scheme* |146| `netloc` | 1 | Сетевое расположение | пустая строка |147| `path` | 2 | Иерархический путь | пустая строка |148| `query` | 3 | Компонент запроса | пустая строка |149| `fragment` | 4 | Идентификатор фрагмента | пустая строка |150| `username` |  | Имя пользователя | [`None`](https://python-all.ru/3.6/library/constants.html#None) |151| `password` |  | Пароль | [`None`](https://python-all.ru/3.6/library/constants.html#None) |152| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/3.6/library/constants.html#None) |153| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/3.6/library/constants.html#None) |154155Чтение атрибута `port` возбуждает [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError), если в URL указан недопустимый порт. Дополнительную информацию об объекте результата см. в разделе [Результаты структурированного разбора](https://python-all.ru/3.6/library/urllib.parse.html#urlparse-result-object).156157Непарные квадратные скобки в атрибуте `netloc` возбуждают [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError).158159Символы в атрибуте `netloc`, которые при NFKC-нормализации (используемой в кодировке IDNA) раскладываются в любой из `/`, `?`, `#`, `@` или `:`, возбуждают [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError). Если URL разложен до разбора, ошибка не возникнет.160161В соответствии со спецификацией [WHATWG](https://python-all.ru/3.6/library/urllib.parse.html), обновляющей RFC 3986, символы ASCII перевода строки `\n`, `\r` и табуляции `\t` удаляются из URL.162163Изменено в версии 3.6: Номера портов вне диапазона теперь возбуждают [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError) вместо возврата [`None`](https://python-all.ru/3.6/library/constants.html#None).164165Изменено в версии 3.6.9: Символы, влияющие на разбор netloc при нормализации NFKC, теперь вызывают [`ValueError`](https://python-all.ru/3.6/library/exceptions.html#ValueError).166167Изменено в версии 3.6.14: Символы ASCII перевода строки и табуляции удаляются из URL.168169#### `urllib.parse.urlunsplit(parts)`170171Объединяет элементы кортежа, возвращаемого [`urlsplit()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlsplit), в полный URL в виде строки. Аргумент *parts* может быть любым итерируемым объектом из пяти элементов. Результат может незначительно отличаться от исходного URL, но быть эквивалентным, если исходный разобранный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны).172173#### `urllib.parse.urljoin(base, url, allow_fragments=True)`174175Строит полный («абсолютный») URL путём объединения «базового URL» (*base*) с другим URL (*url*). Неформально: используются компоненты базового URL, в частности схема адресации, сетевое расположение и (часть) пути, чтобы предоставить недостающие компоненты в относительном URL. Например:176177```python178>>> from urllib.parse import urljoin179>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')180'http://www.cwi.nl/%7Eguido/FAQ.html'181```182183Аргумент *allow\_fragments* имеет то же значение и значение по умолчанию, что и для [`urlparse()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlparse).184185> **Примечание**186>187> Если *url* – абсолютный URL (то есть начинается с `//` или `scheme://`), то имя хоста и/или схема *url* будут присутствовать в результате. Например:188189```pycon190>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',191...         '//www.python.org/%7Eguido')192'http://www.python.org/%7Eguido'193```194195Если такое поведение нежелательно, предварительно обработайте *url* с помощью [`urlsplit()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlsplit) и [`urlunsplit()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlunsplit), удалив возможные части *scheme* и *netloc*.196197Изменено в версии 3.5: Поведение обновлено в соответствии с семантикой, определённой в [**RFC 3986**](https://python-all.ru/3.6/library/urllib.parse.html).198199#### `urllib.parse.urldefrag(url)`200201Если *url* содержит идентификатор фрагмента, возвращает изменённую версию *url* без идентификатора фрагмента и сам идентификатор фрагмента в виде отдельной строки. Если в *url* нет идентификатора фрагмента, возвращает *url* без изменений и пустую строку.202203Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/3.6/library/stdtypes.html#tuple). У этого класса есть следующие дополнительные атрибуты только для чтения:204205| Атрибут | Индекс | Значение | Значение, если отсутствует |206| --- | --- | --- | --- |207| `url` | 0 | URL без фрагмента | пустая строка |208| `fragment` | 1 | Идентификатор фрагмента | пустая строка |209210См. раздел [Структурированные результаты разбора](https://python-all.ru/3.6/library/urllib.parse.html#urlparse-result-object) для получения дополнительной информации об объекте результата.211212Изменено в версии 3.2: Результат – структурированный объект, а не простой кортеж из двух элементов.213214## 21.8.2. Разбор ASCII-закодированных байтов215216Функции разбора URL изначально были разработаны для работы только с символьными строками. На практике полезно иметь возможность манипулировать правильно экранированными и закодированными URL как последовательностями ASCII байтов. Соответственно, все функции разбора URL в этом модуле работают с объектами [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) и [`bytearray`](https://python-all.ru/3.6/library/stdtypes.html#bytearray) в дополнение к объектам [`str`](https://python-all.ru/3.6/library/stdtypes.html#str).217218Если передаются данные [`str`](https://python-all.ru/3.6/library/stdtypes.html#str), результат также будет содержать только данные [`str`](https://python-all.ru/3.6/library/stdtypes.html#str). Если передаются данные [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.6/library/stdtypes.html#bytearray), результат будет содержать только данные [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes).219220Попытка смешать данные [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) с [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.6/library/stdtypes.html#bytearray) в одном вызове функции приведет к возникновению [`TypeError`](https://python-all.ru/3.6/library/exceptions.html#TypeError), а попытка передать не-ASCII байтовые значения вызовет [`UnicodeDecodeError`](https://python-all.ru/3.6/library/exceptions.html#UnicodeDecodeError).221222Чтобы упростить преобразование объектов результатов между [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) и [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes), все возвращаемые значения функций разбора URL предоставляют либо метод `encode()` (если результат содержит данные [`str`](https://python-all.ru/3.6/library/stdtypes.html#str)), либо метод `decode()` (если результат содержит данные [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes)). Сигнатуры этих методов соответствуют сигнатурам соответствующих методов [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) и [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) (за исключением того, что кодировка по умолчанию – `'ascii'` вместо `'utf-8'`). Каждый из них создает значение соответствующего типа, содержащее либо данные [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) (для методов `encode()`), либо данные [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) (для методов `decode()`).223224Приложениям, которым необходимо работать с потенциально неправильно экранированными URL, которые могут содержать не-ASCII данные, потребуется выполнить собственное декодирование из байтов в символы перед вызовом методов разбора URL.225226Поведение, описанное в этом разделе, применяется только к функциям разбора URL. Функции экранирования URL используют свои собственные правила при создании или потреблении последовательностей байтов, как подробно описано в документации отдельных функций экранирования URL.227228Изменено в версии 3.2: Функции разбора URL теперь принимают ASCII-кодированные последовательности байтов229230## 21.8.3. Структурированные результаты разбора231232Объекты результатов функций [`urlparse()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlparse), [`urlsplit()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlsplit) и [`urldefrag()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urldefrag) являются подклассами типа [`tuple`](https://python-all.ru/3.6/library/stdtypes.html#tuple). Эти подклассы добавляют атрибуты, перечисленные в документации этих функций, поддержку кодирования и декодирования, описанную в предыдущем разделе, а также дополнительный метод:233234#### `urllib.parse.SplitResult.geturl()`235236Возвращает перекомбинированную версию исходного URL в виде строки. Она может отличаться от исходного URL тем, что схема может быть нормализована к нижнему регистру, а пустые компоненты могут быть отброшены. В частности, пустые параметры, запросы и идентификаторы фрагментов будут удалены.237238Для результатов [`urldefrag()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urldefrag) будут удалены только пустые идентификаторы фрагментов. Для результатов [`urlsplit()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlsplit) и [`urlparse()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlparse) все отмеченные изменения будут применены к URL, возвращаемому этим методом.239240Результат этого метода остается неизменным, если его снова передать через исходную функцию разбора:241242```python243>>> from urllib.parse import urlsplit244>>> url = 'HTTP://www.Python.org/doc/#'245>>> r1 = urlsplit(url)246>>> r1.geturl()247'http://www.Python.org/doc/'248>>> r2 = urlsplit(r1.geturl())249>>> r2.geturl()250'http://www.Python.org/doc/'251```252253Следующие классы предоставляют реализации структурированных результатов разбора при работе с объектами [`str`](https://python-all.ru/3.6/library/stdtypes.html#str):254255#### `class urllib.parse.DefragResult(url, fragment)`256257Конкретный класс для результатов [`urldefrag()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urldefrag), содержащих данные [`str`](https://python-all.ru/3.6/library/stdtypes.html#str). Метод `encode()` возвращает экземпляр [`DefragResultBytes`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.DefragResultBytes).258259Новое в версии 3.2.260261#### `class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)`262263Конкретный класс для результатов [`urlparse()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlparse), содержащих данные [`str`](https://python-all.ru/3.6/library/stdtypes.html#str). Метод `encode()` возвращает экземпляр [`ParseResultBytes`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.ParseResultBytes).264265#### `class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)`266267Конкретный класс для результатов [`urlsplit()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlsplit), содержащих данные [`str`](https://python-all.ru/3.6/library/stdtypes.html#str). Метод `encode()` возвращает экземпляр [`SplitResultBytes`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.SplitResultBytes).268269Следующие классы предоставляют реализации результатов разбора при работе с объектами [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.6/library/stdtypes.html#bytearray):270271#### `class urllib.parse.DefragResultBytes(url, fragment)`272273Конкретный класс для результатов [`urldefrag()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urldefrag), содержащих данные [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes). Метод `decode()` возвращает экземпляр [`DefragResult`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.DefragResult).274275Новое в версии 3.2.276277#### `class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)`278279Конкретный класс для результатов [`urlparse()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlparse), содержащих данные [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes). Метод `decode()` возвращает экземпляр [`ParseResult`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.ParseResult).280281Новое в версии 3.2.282283#### `class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)`284285Конкретный класс для результатов [`urlsplit()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.urlsplit), содержащих данные [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes). Метод `decode()` возвращает экземпляр [`SplitResult`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.SplitResult).286287Новое в версии 3.2.288289## 21.8.4. Экранирование URL290291Функции экранирования URL предназначены для преобразования программных данных в безопасный формат для использования в компонентах URL: они экранируют специальные символы и кодируют не-ASCII текст. Они также поддерживают обратные операции для восстановления исходных данных из содержимого компонента URL, если эта задача ещё не решается описанными выше функциями разбора URL.292293#### `urllib.parse.quote(string, safe='/', encoding=None, errors=None)`294295Заменяет специальные символы в *string* с помощью escape-последовательности `%xx`. Буквы, цифры и символы `'_.-'` никогда не экранируются. По умолчанию эта функция предназначена для экранирования части пути URL. Необязательный параметр *safe* задаёт дополнительные символы ASCII, которые не следует экранировать – его значение по умолчанию – `'/'`.296297*Строка* может быть либо [`str`](https://python-all.ru/3.6/library/stdtypes.html#str), либо [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes).298299Необязательные параметры *encoding* и *errors* задают способ обработки не-ASCII символов, как это принимается методом [`str.encode()`](https://python-all.ru/3.6/library/stdtypes.html#str.encode). Параметр *encoding* по умолчанию равен `'utf-8'`. Параметр *errors* по умолчанию равен `'strict'`, что означает, что неподдерживаемые символы вызывают исключение [`UnicodeEncodeError`](https://python-all.ru/3.6/library/exceptions.html#UnicodeEncodeError). Параметры *encoding* и *errors* не должны передаваться, если *string* является объектом [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes), иначе будет вызвано исключение [`TypeError`](https://python-all.ru/3.6/library/exceptions.html#TypeError).300301Обратите внимание, что `quote(string, safe, encoding, errors)` эквивалентно `quote_from_bytes(string.encode(encoding, errors), safe)`.302303Пример: `quote('/El Niño/')` даёт `'/El%20Ni%C3%B1o/'`.304305#### `urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)`306307Как [`quote()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.quote), но также заменяет пробелы на знаки плюс, как требуется для экранирования значений HTML-форм при формировании строки запроса для URL. Знаки плюс в исходной строке экранируются, если они не включены в *safe*. Кроме того, значение по умолчанию *safe* не равно `'/'`.308309Пример: `quote_plus('/El Niño/')` даёт `'%2FEl+Ni%C3%B1o%2F'`.310311#### `urllib.parse.quote_from_bytes(bytes, safe='/')`312313Как [`quote()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.quote), но принимает объект [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes) вместо [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) и не выполняет кодирование строки в байты.314315Пример: `quote_from_bytes(b'a&\xef')` даёт `'a%26%EF'`.316317#### `urllib.parse.unquote(string, encoding='utf-8', errors='replace')`318319Замените `%xx` экранирующие последовательности на эквивалентные им одиночные символы. Необязательные параметры *encoding* и *errors* задают способ декодирования процентно-кодированных последовательностей в символы Юникода, как это принято в методе [`bytes.decode()`](https://python-all.ru/3.6/library/stdtypes.html#bytes.decode).320321*string* должен быть строкой [`str`](https://python-all.ru/3.6/library/stdtypes.html#str).322323Значение *encoding* по умолчанию – `'utf-8'`. Значение *errors* по умолчанию – `'replace'`, что означает, что недопустимые последовательности заменяются символом-заполнителем.324325Пример: `unquote('/El%20Ni%C3%B1o/')` даёт `'/El Niño/'`.326327#### `urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')`328329Как [`unquote()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.unquote), но также заменяет знаки плюса на пробелы, как требуется для декодирования значений HTML-форм.330331*string* должен быть строкой [`str`](https://python-all.ru/3.6/library/stdtypes.html#str).332333Пример: `unquote_plus('/El+Ni%C3%B1o/')` даёт `'/El Niño/'`.334335#### `urllib.parse.unquote_to_bytes(string)`336337Заменяет экранированные последовательности `%xx` на соответствующий однобайтовый эквивалент и возвращает объект [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes).338339*Строка* может быть либо [`str`](https://python-all.ru/3.6/library/stdtypes.html#str), либо [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes).340341Если это строка [`str`](https://python-all.ru/3.6/library/stdtypes.html#str), то неэкранированные не-ASCII символы в *string* кодируются в UTF-8 байты.342343Пример: `unquote_to_bytes('a%26%EF')` даёт `b'a&\xef'`.344345#### `urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)`346347Преобразует объект отображения (mapping) или последовательность кортежей из двух элементов, которые могут содержать объекты [`str`](https://python-all.ru/3.6/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.6/library/stdtypes.html#bytes), в процентно-кодированную ASCII-строку. Если результирующая строка должна использоваться как данные *data* для операции POST с функцией [`urlopen()`](https://python-all.ru/3.6/library/urllib.request.html#urllib.request.urlopen), то её следует закодировать в байты; в противном случае это приведёт к ошибке [`TypeError`](https://python-all.ru/3.6/library/exceptions.html#TypeError).348349Результирующая строка состоит из последовательности пар `key=value`, разделённых символами `'&'`, при этом и *ключ*, и *значение* экранируются с помощью функции *quote\_via*. По умолчанию для экранирования значений используется [`quote_plus()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.quote_plus), то есть пробелы заменяются на символ `'+'`, а символы '/' кодируются как `%2F`, что соответствует стандарту для GET-запросов (`application/x-www-form-urlencoded`). Альтернативная функция, которую можно передать как *quote\_via* – это [`quote()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.quote), которая кодирует пробелы как `%20` и не кодирует символы '/'. Для максимального контроля над тем, что экранируется, используйте `quote` и задайте значение для *safe*.350351Когда последовательность двухэлементных кортежей используется в качестве аргумента *query*, первый элемент каждого кортежа – это ключ, а второй – значение. Сам элемент значения может быть последовательностью, и в этом случае, если необязательный параметр *doseq* принимает значение `True`, для каждого элемента последовательности значений генерируются отдельные пары `key=value`, разделённые `'&'`. Порядок параметров в закодированной строке будет соответствовать порядку кортежей параметров в последовательности.352353Параметры *safe*, *encoding* и *errors* передаются в функцию *quote\_via* (параметры *encoding* и *errors* передаются только когда элемент запроса является [`str`](https://python-all.ru/3.6/library/stdtypes.html#str)).354355Для обращения этого процесса кодирования в модуле предусмотрены [`parse_qs()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.parse_qs) и [`parse_qsl()`](https://python-all.ru/3.6/library/urllib.parse.html#urllib.parse.parse_qsl), которые преобразуют строки запроса в структуры данных Python.356357Обратитесь к [примерам urllib](https://python-all.ru/3.6/library/urllib.request.html#urllib-examples), чтобы узнать, как метод urlencode можно использовать для создания строки запроса для URL или данных для POST.358359Изменено в версии 3.2: Параметр Query поддерживает объекты bytes и string.360361Новое в версии 3.5: *quote\_via* параметр.362363> **См. также**364>365> **[WHATWG](https://python-all.ru/3.6/library/urllib.parse.html) – URL Living Standard**366>367> Рабочая группа по стандарту URL, которая определяет URL, домены, IP-адреса, формат application/x-www-form-urlencoded и их API.368>369> **[**RFC 3986**](https://python-all.ru/3.6/library/urllib.parse.html) – Uniform Resource Identifiers**370>371> Это текущий стандарт (STD66). Любые изменения в модуле urllib.parse должны ему соответствовать. Могут наблюдаться некоторые отклонения, которые в основном обусловлены обратной совместимостью и некоторыми фактическими требованиями парсинга, обычно встречающимися в основных браузерах.372>373> **[**RFC 2732**](https://python-all.ru/3.6/library/urllib.parse.html) – Формат литеральных IPv6-адресов в URL.**374>375> В нём описываются требования к парсингу IPv6 URL.376>377> **[**RFC 2396**](https://python-all.ru/3.6/library/urllib.parse.html) – Uniform Resource Identifiers (URI): Generic Syntax**378>379> Документ, описывающий общие синтаксические требования как для Uniform Resource Names (URN), так и для Uniform Resource Locators (URL).380>381> **[**RFC 2368**](https://python-all.ru/3.6/library/urllib.parse.html) – Схема URL mailto.**382>383> Требования к парсингу схем URL mailto.384>385> **[**RFC 1808**](https://python-all.ru/3.6/library/urllib.parse.html) – Relative Uniform Resource Locators**386>387> Этот документ (RFC) включает правила объединения абсолютного и относительного URL, включая значительное количество «Аномальных примеров», которые определяют обработку граничных случаев.388>389> **[**RFC 1738**](https://python-all.ru/3.6/library/urllib.parse.html) – Uniform Resource Locators (URL)**390>391> В нём описывается формальный синтаксис и семантика абсолютных URL.392