`urllib.parse.md`

452 строк · 55.4 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.12/library/urllib.parse.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `urllib.parse` – Разбор URL на компоненты89**Исходный код:** [Lib/urllib/parse.py](https://python-all.ru/src/3.12/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`, `rtsps`, `rtspu`, `sftp`, `shttp`, `sip`, `sips`, `snews`, `svn`, `svn+ssh`, `telnet`, `wais`, `ws`, `wss`.1617Модуль [`urllib.parse`](https://python-all.ru/3.12/library/urllib.parse.html#module-urllib.parse) определяет функции, которые делятся на две большие категории: разбор URL и квотирование URL. Они подробно рассматриваются в следующих разделах.1819Функции этого модуля используют устаревший термин `netloc` (или `net_loc`), который был введён в [**RFC 1808**](https://python-all.ru/3.12/library/urllib.parse.html). Однако этот термин был заменён [**RFC 3986**](https://python-all.ru/3.12/library/urllib.parse.html), который ввёл термин `authority`. Использование `netloc` сохранено для обратной совместимости.2021## Разбор URL2223Функции разбора URL предназначены для разделения строки URL на компоненты или для объединения компонентов URL в строку URL.2425#### `urllib.parse.urlparse(urlstring, scheme='', allow_fragments=True)`2627Разбирает URL на шесть компонентов и возвращает [именованный кортеж](https://python-all.ru/3.12/glossary.html#term-named-tuple) из 6 элементов. Это соответствует общей структуре URL: `scheme://netloc/path;parameters?query#fragment`. Каждый элемент кортежа – строка, возможно пустая. Компоненты не разбиваются на более мелкие части (например, сетевое расположение – единая строка), а %-последовательности не раскрываются. Разделители, показанные выше, не входят в результат, за исключением ведущего слеша в компоненте *path*, который сохраняется, если присутствует. Например:2829```pycon30>>> from urllib.parse import urlparse31>>> urlparse("scheme://netloc/path;parameters?query#fragment")32ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='',33            query='query', fragment='fragment')34>>> o = urlparse("http://docs.python.org:80/3/library/urllib.parse.html?"35...              "highlight=params#url-parsing")36>>> o37ParseResult(scheme='http', netloc='docs.python.org:80',38            path='/3/library/urllib.parse.html', params='',39            query='highlight=params', fragment='url-parsing')40>>> o.scheme41'http'42>>> o.netloc43'docs.python.org:80'44>>> o.hostname45'docs.python.org'46>>> o.port478048>>> o._replace(fragment="").geturl()49'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'50```5152Следуя синтаксическим спецификациям [**RFC 1808**](https://python-all.ru/3.12/library/urllib.parse.html), urlparse распознаёт netloc только в том случае, если она правильно введена символами '//'. В противном случае считается, что входные данные – это относительный URL, и, следовательно, они начинаются с компонента пути.5354```pycon55>>> from urllib.parse import urlparse56>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')57ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',58            params='', query='', fragment='')59>>> urlparse('www.cwi.nl/%7Eguido/Python.html')60ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',61            params='', query='', fragment='')62>>> urlparse('help/Python.html')63ParseResult(scheme='', netloc='', path='help/Python.html', params='',64            query='', fragment='')65```6667Аргумент *scheme* задаёт схему адресации по умолчанию, которая используется только если URL её не указывает. Он должен быть того же типа (текст или байты), что и *urlstring*, за исключением того, что значение по умолчанию `''` всегда разрешено и автоматически преобразуется в `b''` при необходимости.6869Если аргумент *allow\_fragments* равен false, идентификаторы фрагментов не распознаются. Вместо этого они анализируются как часть пути, параметров или компонента запроса, а `fragment` в возвращаемом значении устанавливается в пустую строку.7071Возвращаемое значение – это [именованный кортеж](https://python-all.ru/3.12/glossary.html#term-named-tuple), что означает, что к его элементам можно обращаться по индексу или по именованным атрибутам, которые:7273| Атрибут | Индекс | Значение | Значение, если отсутствует |74| --- | --- | --- | --- |75| `scheme` | 0 | Спецификатор схемы URL | Параметр *scheme* |76| `netloc` | 1 | Сетевое расположение | пустая строка |77| `path` | 2 | Иерархический путь | пустая строка |78| `params` | 3 | Параметры для последнего элемента пути | пустая строка |79| `query` | 4 | Компонент запроса | пустая строка |80| `fragment` | 5 | Идентификатор фрагмента | пустая строка |81| `username` |  | Имя пользователя | [`None`](https://python-all.ru/3.12/library/constants.html#None) |82| `password` |  | Пароль | [`None`](https://python-all.ru/3.12/library/constants.html#None) |83| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/3.12/library/constants.html#None) |84| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/3.12/library/constants.html#None) |8586Чтение атрибута `port` возбуждает [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError), если в URL указан недопустимый порт. Дополнительную информацию об объекте результата см. в разделе [Результаты структурированного разбора](https://python-all.ru/3.12/library/urllib.parse.html#urlparse-result-object).8788Непарные квадратные скобки в атрибуте `netloc` возбуждают [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).8990Символы в атрибуте `netloc`, которые при NFKC-нормализации (используемой в кодировке IDNA) раскладываются в любой из `/`, `?`, `#`, `@` или `:`, возбуждают [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError). Если URL разложен до разбора, ошибка не возникнет.9192Как и для всех именованных кортежей, у подкласса есть несколько дополнительных методов и атрибутов, которые особенно полезны. Один из таких методов – `_replace()`. Метод `_replace()` возвращает новый объект ParseResult, заменяя указанные поля новыми значениями.9394```pycon95>>> from urllib.parse import urlparse96>>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')97>>> u98ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',99            params='', query='', fragment='')100>>> u._replace(scheme='http')101ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',102            params='', query='', fragment='')103```104105> **Предупреждение**106>107> [`urlparse()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlparse) не выполняет проверку. Подробнее см. [безопасность разбора URL](https://python-all.ru/3.12/library/urllib.parse.html#url-parsing-security).108109Изменено в версии 3.2: Добавлена возможность разбора URL с IPv6.110111Изменено в версии 3.3: Фрагмент теперь разбирается для всех схем URL (если *allow\_fragments* не равен false), в соответствии с [**RFC 3986**](https://python-all.ru/3.12/library/urllib.parse.html). Ранее существовал список разрешённых схем, поддерживающих фрагменты.112113Изменено в версии 3.6: Номера портов вне диапазона теперь возбуждают [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError) вместо возврата [`None`](https://python-all.ru/3.12/library/constants.html#None).114115Изменено в версии 3.8: Символы, влияющие на разбор netloc при NFKC-нормализации, теперь возбуждают [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).116117#### `urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')`118119Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде словаря. Ключами словаря являются уникальные имена переменных запроса, а значениями – списки значений для каждого имени.120121Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение True означает, что пустые значения должны сохраняться как пустые строки. Значение False по умолчанию означает, что пустые значения игнорируются и считаются отсутствующими.122123Необязательный аргумент *strict\_parsing* – это флаг, указывающий, что делать с ошибками разбора. Если False (по умолчанию), ошибки молча игнорируются. Если True, ошибки возбуждают исключение [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).124125Необязательные параметры *encoding* и *errors* определяют, как декодировать процентно-кодированные последовательности в символы Unicode, как это принимается методом [`bytes.decode()`](https://python-all.ru/3.12/library/stdtypes.html#bytes.decode).126127Необязательный аргумент *max\_num\_fields* – это максимальное количество полей для чтения. Если он задан, то при чтении более *max\_num\_fields* полей возбуждается [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).128129Необязательный аргумент *separator* – это символ, используемый для разделения аргументов запроса. По умолчанию он равен `&`.130131Для преобразования таких словарей в строки запроса используется функция [`urllib.parse.urlencode()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlencode) (с параметром `doseq`, установленным в `True`).132133Изменено в версии 3.2: Добавлены параметры *encoding* и *errors*.134135Изменено в версии 3.8: Добавлен параметр *max\_num\_fields*.136137Изменено в версии 3.10: Добавлен параметр *separator* со значением по умолчанию `&`. В версиях Python до 3.10 допускалось использование как `;`, так и `&` в качестве разделителя параметров запроса. Теперь разрешён только один ключ-разделитель, и по умолчанию используется `&`.138139#### `urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')`140141Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде списка пар имя, значение.142143Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение True означает, что пустые значения должны сохраняться как пустые строки. Значение False по умолчанию означает, что пустые значения игнорируются и считаются отсутствующими.144145Необязательный аргумент *strict\_parsing* – это флаг, указывающий, что делать с ошибками разбора. Если False (по умолчанию), ошибки молча игнорируются. Если True, ошибки возбуждают исключение [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).146147Необязательные параметры *encoding* и *errors* определяют, как декодировать процентно-кодированные последовательности в символы Unicode, как это принимается методом [`bytes.decode()`](https://python-all.ru/3.12/library/stdtypes.html#bytes.decode).148149Необязательный аргумент *max\_num\_fields* – это максимальное количество полей для чтения. Если он задан, то при чтении более *max\_num\_fields* полей возбуждается [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).150151Необязательный аргумент *separator* – это символ, используемый для разделения аргументов запроса. По умолчанию он равен `&`.152153Используйте функцию [`urllib.parse.urlencode()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlencode) для преобразования таких списков пар в строки запроса.154155Изменено в версии 3.2: Добавлены параметры *encoding* и *errors*.156157Изменено в версии 3.8: Добавлен параметр *max\_num\_fields*.158159Изменено в версии 3.10: Добавлен параметр *separator* со значением по умолчанию `&`. В версиях Python до 3.10 допускалось использование как `;`, так и `&` в качестве разделителя параметров запроса. Теперь разрешён только один ключ-разделитель, и по умолчанию используется `&`.160161#### `urllib.parse.urlunparse(parts)`162163Собирает URL из кортежа, возвращаемого `urlparse()`. Аргумент *parts* может быть любым итерируемым объектом из шести элементов. Результат может незначительно отличаться от исходного URL, но быть эквивалентным, если исходный разобранный URL содержал лишние разделители (например, `?` с пустым запросом; RFC утверждает, что они эквивалентны).164165#### `urllib.parse.urlsplit(urlstring, scheme='', allow_fragments=True)`166167Эта функция похожа на [`urlparse()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlparse), но не отделяет параметры от URL. Её следует использовать вместо [`urlparse()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlparse), если нужен более современный синтаксис URL, позволяющий применять параметры к каждому сегменту части *path* URL (см. [**RFC 2396**](https://python-all.ru/3.12/library/urllib.parse.html)). Для разделения сегментов пути и параметров нужна отдельная функция. Эта функция возвращает [именованный кортеж](https://python-all.ru/3.12/glossary.html#term-named-tuple) из 5 элементов:168169```python170(addressing scheme, network location, path, query, fragment identifier).171```172173Возвращаемое значение – [именованный кортеж](https://python-all.ru/3.12/glossary.html#term-named-tuple), его элементы доступны по индексу или как именованные атрибуты:174175| Атрибут | Индекс | Значение | Значение, если отсутствует |176| --- | --- | --- | --- |177| `scheme` | 0 | Спецификатор схемы URL | Параметр *scheme* |178| `netloc` | 1 | Сетевое расположение | пустая строка |179| `path` | 2 | Иерархический путь | пустая строка |180| `query` | 3 | Компонент запроса | пустая строка |181| `fragment` | 4 | Идентификатор фрагмента | пустая строка |182| `username` |  | Имя пользователя | [`None`](https://python-all.ru/3.12/library/constants.html#None) |183| `password` |  | Пароль | [`None`](https://python-all.ru/3.12/library/constants.html#None) |184| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/3.12/library/constants.html#None) |185| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/3.12/library/constants.html#None) |186187Чтение атрибута `port` возбуждает [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError), если в URL указан недопустимый порт. Дополнительную информацию об объекте результата см. в разделе [Результаты структурированного разбора](https://python-all.ru/3.12/library/urllib.parse.html#urlparse-result-object).188189Непарные квадратные скобки в атрибуте `netloc` возбуждают [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).190191Символы в атрибуте `netloc`, которые при NFKC-нормализации (используемой в кодировке IDNA) раскладываются в любой из `/`, `?`, `#`, `@` или `:`, возбуждают [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError). Если URL разложен до разбора, ошибка не возникнет.192193Следуя некоторым положениям [спецификации WHATWG](https://python-all.ru/3.12/library/urllib.parse.html), которая обновляет RFC 3986, начальные управляющие символы C0 и пробелы удаляются из URL. Символы `\n`, `\r` и табуляции `\t` удаляются из URL в любой позиции.194195> **Предупреждение**196>197> [`urlsplit()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlsplit) не выполняет проверку. Подробнее см. [безопасность разбора URL](https://python-all.ru/3.12/library/urllib.parse.html#url-parsing-security).198199Изменено в версии 3.6: Номера портов вне диапазона теперь возбуждают [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError) вместо возврата [`None`](https://python-all.ru/3.12/library/constants.html#None).200201Изменено в версии 3.8: Символы, влияющие на разбор netloc при NFKC-нормализации, теперь возбуждают [`ValueError`](https://python-all.ru/3.12/library/exceptions.html#ValueError).202203Изменено в версии 3.10: Символы ASCII перевода строки и табуляции удаляются из URL.204205Изменено в версии 3.12: Начальные управляющие символы C0 и пробелы (по WHATWG) удаляются из URL.206207#### `urllib.parse.urlunsplit(parts)`208209Объединяет элементы кортежа, возвращаемого [`urlsplit()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlsplit), в полный URL в виде строки. Аргумент *parts* может быть любым итерируемым объектом из пяти элементов. Результат может незначительно отличаться от исходного URL, но быть эквивалентным, если исходный разобранный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны).210211#### `urllib.parse.urljoin(base, url, allow_fragments=True)`212213Строит полный («абсолютный») URL путём объединения «базового URL» (*base*) с другим URL (*url*). Неформально: используются компоненты базового URL, в частности схема адресации, сетевое расположение и (часть) пути, чтобы предоставить недостающие компоненты в относительном URL. Например:214215```python216>>> from urllib.parse import urljoin217>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')218'http://www.cwi.nl/%7Eguido/FAQ.html'219```220221Аргумент *allow\_fragments* имеет то же значение и значение по умолчанию, что и для [`urlparse()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlparse).222223> **Примечание**224>225> Если *url* является абсолютным URL (то есть начинается с `//` или `scheme://`), то имя хоста и/или схема из *url* будут присутствовать в результате. Например:226>227> ```pycon228> >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',229> ...         '//www.python.org/%7Eguido')230> 'http://www.python.org/%7Eguido'231> ```232>233> Если такое поведение нежелательно, предварительно обработайте *url* с помощью [`urlsplit()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlsplit) и [`urlunsplit()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlunsplit), удалив возможные части *scheme* и *netloc*.234235> **Предупреждение**236>237> Поскольку абсолютный URL может быть передан в качестве параметра `url`, в целом **небезопасно** использовать `urljoin` с контролируемым злоумышленником `url`. Например, в `urljoin("https://website.com/users/", username)`, если `username` может содержать абсолютный URL, результатом `urljoin` будет этот абсолютный URL.238239Изменено в версии 3.5: Поведение обновлено в соответствии с семантикой, определённой в [**RFC 3986**](https://python-all.ru/3.12/library/urllib.parse.html).240241#### `urllib.parse.urldefrag(url)`242243Если *url* содержит идентификатор фрагмента, возвращает изменённую версию *url* без идентификатора фрагмента и сам идентификатор фрагмента в виде отдельной строки. Если в *url* нет идентификатора фрагмента, возвращает *url* без изменений и пустую строку.244245Возвращаемое значение – [именованный кортеж](https://python-all.ru/3.12/glossary.html#term-named-tuple), его элементы доступны по индексу или как именованные атрибуты:246247| Атрибут | Индекс | Значение | Значение, если отсутствует |248| --- | --- | --- | --- |249| `url` | 0 | URL без фрагмента | пустая строка |250| `fragment` | 1 | Идентификатор фрагмента | пустая строка |251252См. раздел [Структурированные результаты разбора](https://python-all.ru/3.12/library/urllib.parse.html#urlparse-result-object) для получения дополнительной информации об объекте результата.253254Изменено в версии 3.2: Результат – структурированный объект, а не простой кортеж из двух элементов.255256#### `urllib.parse.unwrap(url)`257258Извлекает URL из обёрнутого URL (то есть строки, отформатированной как `<URL:scheme://host/path>`, `<scheme://host/path>`, `URL:scheme://host/path` или `scheme://host/path`). Если *url* не является обёрнутым URL, он возвращается без изменений.259260## Безопасность разбора URL261262API [`urlsplit()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlsplit) и [`urlparse()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlparse) не выполняют **валидацию** входных данных. Они могут не вызывать ошибки на входных данных, которые другие приложения считают недопустимыми. Они также могут успешно обработать некоторые входные данные, которые в других местах не считаются URL. Их цель – практическая функциональность, а не чистота.263264Вместо того чтобы вызывать исключение для необычных входных данных, они могут возвращать некоторые составные части как пустые строки. Или компоненты могут содержать больше, чем, возможно, должны.265266Мы рекомендуем пользователям этих API, если значения могут использоваться где-либо с последствиями для безопасности, писать защитный код. Выполните некоторую проверку в своем коде, прежде чем доверять возвращенной составной части. Имеет ли `scheme` смысл? Разумен ли `path`? Нет ли чего-то странного в `hostname`? и т.д.267268Что составляет URL – не общепринятое определение. Разные приложения имеют разные потребности и желаемые ограничения. Например, живая [спецификация WHATWG](https://python-all.ru/3.12/library/urllib.parse.html) описывает, что требуется пользовательским веб-клиентам, таким как веб-браузер. В то время как [**RFC 3986**](https://python-all.ru/3.12/library/urllib.parse.html) является более общим. Эти функции включают некоторые аспекты обоих, но не могут считаться совместимыми ни с одним из них. API и существующий пользовательский код с ожиданиями определенного поведения предшествуют обоим стандартам, что заставляет нас быть очень осторожными с изменениями поведения API.269270## Разбор ASCII-кодированных байтов271272Функции разбора URL изначально были разработаны для работы только с символьными строками. На практике полезно иметь возможность манипулировать правильно экранированными и закодированными URL как последовательностями ASCII байтов. Соответственно, все функции разбора URL в этом модуле работают с объектами [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) и [`bytearray`](https://python-all.ru/3.12/library/stdtypes.html#bytearray) в дополнение к объектам [`str`](https://python-all.ru/3.12/library/stdtypes.html#str).273274Если передаются данные [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), результат также будет содержать только данные [`str`](https://python-all.ru/3.12/library/stdtypes.html#str). Если передаются данные [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.12/library/stdtypes.html#bytearray), результат будет содержать только данные [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes).275276Попытка смешать данные [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) с [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.12/library/stdtypes.html#bytearray) в одном вызове функции приведет к возникновению [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError), а попытка передать не-ASCII байтовые значения вызовет [`UnicodeDecodeError`](https://python-all.ru/3.12/library/exceptions.html#UnicodeDecodeError).277278Чтобы упростить преобразование объектов результатов между [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) и [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes), все возвращаемые значения функций разбора URL предоставляют либо метод `encode()` (если результат содержит данные [`str`](https://python-all.ru/3.12/library/stdtypes.html#str)), либо метод `decode()` (если результат содержит данные [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes)). Сигнатуры этих методов соответствуют сигнатурам соответствующих методов [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) и [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) (за исключением того, что кодировка по умолчанию – `'ascii'` вместо `'utf-8'`). Каждый из них создает значение соответствующего типа, содержащее либо данные [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) (для методов `encode()`), либо данные [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) (для методов `decode()`).279280Приложениям, которым необходимо работать с потенциально неправильно экранированными URL, которые могут содержать не-ASCII данные, потребуется выполнить собственное декодирование из байтов в символы перед вызовом методов разбора URL.281282Поведение, описанное в этом разделе, применяется только к функциям разбора URL. Функции экранирования URL используют свои собственные правила при создании или потреблении последовательностей байтов, как подробно описано в документации отдельных функций экранирования URL.283284Изменено в версии 3.2: Функции разбора URL теперь принимают ASCII-кодированные последовательности байтов285286## Структурированные результаты разбора287288Объекты результатов функций [`urlparse()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlparse), [`urlsplit()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlsplit) и [`urldefrag()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urldefrag) являются подклассами типа [`tuple`](https://python-all.ru/3.12/library/stdtypes.html#tuple). Эти подклассы добавляют атрибуты, перечисленные в документации этих функций, поддержку кодирования и декодирования, описанную в предыдущем разделе, а также дополнительный метод:289290#### `urllib.parse.SplitResult.geturl()`291292Возвращает перекомбинированную версию исходного URL в виде строки. Она может отличаться от исходного URL тем, что схема может быть нормализована к нижнему регистру, а пустые компоненты могут быть отброшены. В частности, пустые параметры, запросы и идентификаторы фрагментов будут удалены.293294Для результатов [`urldefrag()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urldefrag) будут удалены только пустые идентификаторы фрагментов. Для результатов [`urlsplit()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlsplit) и [`urlparse()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlparse) все отмеченные изменения будут применены к URL, возвращаемому этим методом.295296Результат этого метода остается неизменным, если его снова передать через исходную функцию разбора:297298```python299>>> from urllib.parse import urlsplit300>>> url = 'HTTP://www.Python.org/doc/#'301>>> r1 = urlsplit(url)302>>> r1.geturl()303'http://www.Python.org/doc/'304>>> r2 = urlsplit(r1.geturl())305>>> r2.geturl()306'http://www.Python.org/doc/'307```308309Следующие классы предоставляют реализации структурированных результатов разбора при работе с объектами [`str`](https://python-all.ru/3.12/library/stdtypes.html#str):310311#### `class urllib.parse.DefragResult(url, fragment)`312313Конкретный класс для результатов [`urldefrag()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urldefrag), содержащих данные [`str`](https://python-all.ru/3.12/library/stdtypes.html#str). Метод `encode()` возвращает экземпляр [`DefragResultBytes`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.DefragResultBytes).314315Добавлено в версии 3.2.316317#### `class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)`318319Конкретный класс для результатов [`urlparse()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlparse), содержащих данные [`str`](https://python-all.ru/3.12/library/stdtypes.html#str). Метод `encode()` возвращает экземпляр [`ParseResultBytes`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.ParseResultBytes).320321#### `class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)`322323Конкретный класс для результатов [`urlsplit()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlsplit), содержащих данные [`str`](https://python-all.ru/3.12/library/stdtypes.html#str). Метод `encode()` возвращает экземпляр [`SplitResultBytes`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.SplitResultBytes).324325Следующие классы предоставляют реализации результатов разбора при работе с объектами [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.12/library/stdtypes.html#bytearray):326327#### `class urllib.parse.DefragResultBytes(url, fragment)`328329Конкретный класс для результатов [`urldefrag()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urldefrag), содержащих данные [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes). Метод `decode()` возвращает экземпляр [`DefragResult`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.DefragResult).330331Добавлено в версии 3.2.332333#### `class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)`334335Конкретный класс для результатов [`urlparse()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlparse), содержащих данные [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes). Метод `decode()` возвращает экземпляр [`ParseResult`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.ParseResult).336337Добавлено в версии 3.2.338339#### `class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)`340341Конкретный класс для результатов [`urlsplit()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlsplit), содержащих данные [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes). Метод `decode()` возвращает экземпляр [`SplitResult`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.SplitResult).342343Добавлено в версии 3.2.344345## Экранирование URL346347Функции экранирования URL предназначены для преобразования программных данных в безопасный формат для использования в компонентах URL: они экранируют специальные символы и кодируют не-ASCII текст. Они также поддерживают обратные операции для восстановления исходных данных из содержимого компонента URL, если эта задача ещё не решается описанными выше функциями разбора URL.348349#### `urllib.parse.quote(string, safe='/', encoding=None, errors=None)`350351Заменяет специальные символы в *string* с помощью экранирования `%xx`. Буквы, цифры и символы `'_.-~'` никогда не экранируются. По умолчанию эта функция предназначена для экранирования части пути URL. Необязательный параметр *safe* задаёт дополнительные ASCII-символы, которые не следует экранировать – его значение по умолчанию: `'/'`.352353*string* может быть либо объектом [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), либо объектом [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes).354355Изменено в версии 3.7: Перенесено из [**RFC 2396**](https://python-all.ru/3.12/library/urllib.parse.html) в [**RFC 3986**](https://python-all.ru/3.12/library/urllib.parse.html) для экранирования строк URL. Символ "~" теперь включён в набор незарезервированных символов.356357Необязательные параметры *encoding* и *errors* задают способ обработки не-ASCII символов, как это принимается методом [`str.encode()`](https://python-all.ru/3.12/library/stdtypes.html#str.encode). Параметр *encoding* по умолчанию равен `'utf-8'`. Параметр *errors* по умолчанию равен `'strict'`, что означает, что неподдерживаемые символы вызывают исключение [`UnicodeEncodeError`](https://python-all.ru/3.12/library/exceptions.html#UnicodeEncodeError). Параметры *encoding* и *errors* не должны передаваться, если *string* является объектом [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes), иначе будет вызвано исключение [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError).358359Обратите внимание, что `quote(string, safe, encoding, errors)` эквивалентно `quote_from_bytes(string.encode(encoding, errors), safe)`.360361Пример: `quote('/El Niño/')` даёт `'/El%20Ni%C3%B1o/'`.362363#### `urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)`364365Как [`quote()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.quote), но также заменяет пробелы на знаки плюс, что требуется для экранирования значений HTML-форм при формировании строки запроса для URL. Знаки плюс в исходной строке экранируются, если они не включены в *safe*. Кроме того, значение по умолчанию для *safe* не равно `'/'`.366367Пример: `quote_plus('/El Niño/')` даёт `'%2FEl+Ni%C3%B1o%2F'`.368369#### `urllib.parse.quote_from_bytes(bytes, safe='/')`370371Как [`quote()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.quote), но принимает объект [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes) вместо [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) и не выполняет кодирование строки в байты.372373Пример: `quote_from_bytes(b'a&\xef')` даёт `'a%26%EF'`.374375#### `urllib.parse.unquote(string, encoding='utf-8', errors='replace')`376377Заменяет управляющие последовательности `%xx` на соответствующий одиночный символ. Необязательные параметры *encoding* и *errors* задают способ декодирования процентно-кодированных последовательностей в символы Unicode, как это принимается методом [`bytes.decode()`](https://python-all.ru/3.12/library/stdtypes.html#bytes.decode).378379*string* может быть либо объектом [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), либо объектом [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes).380381Значение *encoding* по умолчанию – `'utf-8'`. Значение *errors* по умолчанию – `'replace'`, что означает, что недопустимые последовательности заменяются символом-заполнителем.382383Пример: `unquote('/El%20Ni%C3%B1o/')` даёт `'/El Niño/'`.384385Изменено в версии 3.9: Параметр *string* теперь поддерживает объекты bytes и str (ранее только str).386387#### `urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')`388389Как [`unquote()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.unquote), но также заменяет знаки плюс на пробелы, что требуется для восстановления значений HTML-форм.390391*string* должен быть строкой [`str`](https://python-all.ru/3.12/library/stdtypes.html#str).392393Пример: `unquote_plus('/El+Ni%C3%B1o/')` даёт `'/El Niño/'`.394395#### `urllib.parse.unquote_to_bytes(string)`396397Заменяет управляющие последовательности `%xx` на соответствующий одиночный октет и возвращает объект [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes).398399*string* может быть либо объектом [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), либо объектом [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes).400401Если это строка [`str`](https://python-all.ru/3.12/library/stdtypes.html#str), то неэкранированные не-ASCII символы в *string* кодируются в UTF-8 байты.402403Пример: `unquote_to_bytes('a%26%EF')` даёт `b'a&\xef'`.404405#### `urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)`406407Преобразует объект отображения (mapping) или последовательность кортежей из двух элементов, которые могут содержать объекты [`str`](https://python-all.ru/3.12/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.12/library/stdtypes.html#bytes), в процентно-кодированную ASCII-строку. Если результирующая строка должна использоваться как данные *data* для операции POST с функцией [`urlopen()`](https://python-all.ru/3.12/library/urllib.request.html#urllib.request.urlopen), то её следует закодировать в байты; в противном случае это приведёт к ошибке [`TypeError`](https://python-all.ru/3.12/library/exceptions.html#TypeError).408409Результирующая строка состоит из последовательности пар `key=value`, разделённых символами `'&'`, при этом и *ключ*, и *значение* экранируются с помощью функции *quote\_via*. По умолчанию для экранирования значений используется [`quote_plus()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.quote_plus), то есть пробелы заменяются на символ `'+'`, а символы '/' кодируются как `%2F`, что соответствует стандарту для GET-запросов (`application/x-www-form-urlencoded`). Альтернативная функция, которую можно передать как *quote\_via* – это [`quote()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.quote), которая кодирует пробелы как `%20` и не кодирует символы '/'. Для максимального контроля над тем, что экранируется, используйте `quote` и задайте значение для *safe*.410411Когда в качестве аргумента *query* используется последовательность кортежей из двух элементов, первый элемент каждого кортежа – это ключ, а второй – значение. Само значение тоже может быть последовательностью, и в этом случае, если необязательный параметр *doseq* принимает значение `True`, для каждого элемента последовательности значений по данному ключу генерируются отдельные пары `key=value`, разделённые `'&'`. Порядок параметров в закодированной строке будет соответствовать порядку кортежей параметров в последовательности.412413Параметры *safe*, *encoding* и *errors* передаются в функцию *quote\_via* (параметры *encoding* и *errors* передаются только когда элемент запроса является [`str`](https://python-all.ru/3.12/library/stdtypes.html#str)).414415Для обращения этого процесса кодирования в модуле предусмотрены [`parse_qs()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.parse_qs) и [`parse_qsl()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.parse_qsl), которые преобразуют строки запроса в структуры данных Python.416417Обратитесь к [примерам urllib](https://python-all.ru/3.12/library/urllib.request.html#urllib-examples), чтобы узнать, как метод [`urllib.parse.urlencode()`](https://python-all.ru/3.12/library/urllib.parse.html#urllib.parse.urlencode) может использоваться для формирования строки запроса URL или данных для POST-запроса.418419Изменено в версии 3.2: параметр *query* теперь поддерживает объекты bytes и string.420421Изменено в версии 3.5: добавлен параметр *quote\_via*.422423> **См. также**424>425> **[WHATWG](https://python-all.ru/3.12/library/urllib.parse.html) – URL Living Standard**426>427> Рабочая группа по стандарту URL, которая определяет URL, домены, IP-адреса, формат application/x-www-form-urlencoded и их API.428>429> **[**RFC 3986**](https://python-all.ru/3.12/library/urllib.parse.html) – Uniform Resource Identifiers**430>431> Это текущий стандарт (STD66). Любые изменения в модуле urllib.parse должны ему соответствовать. Могут наблюдаться некоторые отклонения, которые в основном обусловлены обратной совместимостью и некоторыми фактическими требованиями парсинга, обычно встречающимися в основных браузерах.432>433> **[**RFC 2732**](https://python-all.ru/3.12/library/urllib.parse.html) – Формат литеральных IPv6-адресов в URL.**434>435> В нём описываются требования к парсингу IPv6 URL.436>437> **[**RFC 2396**](https://python-all.ru/3.12/library/urllib.parse.html) – Uniform Resource Identifiers (URI): Generic Syntax**438>439> Документ, описывающий общие синтаксические требования как для Uniform Resource Names (URN), так и для Uniform Resource Locators (URL).440>441> **[**RFC 2368**](https://python-all.ru/3.12/library/urllib.parse.html) – Схема URL mailto.**442>443> Требования к парсингу схем URL mailto.444>445> **[**RFC 1808**](https://python-all.ru/3.12/library/urllib.parse.html) – Relative Uniform Resource Locators**446>447> Этот документ (RFC) включает правила объединения абсолютного и относительного URL, включая значительное количество «Аномальных примеров», которые определяют обработку граничных случаев.448>449> **[**RFC 1738**](https://python-all.ru/3.12/library/urllib.parse.html) – Uniform Resource Locators (URL)**450>451> В нём описывается формальный синтаксис и семантика абсолютных URL.452