`urllib.parse.md`

431 строк · 52.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.13/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.13/Lib/urllib/parse.py)1011---1213Этот модуль предоставляет стандартный интерфейс для разбора строки URL на компоненты (схема адресации, сетевое расположение, путь и т.д.), обратной сборки компонентов в строку URL, а также для преобразования «относительного URL» в абсолютный по заданному «базовому URL».1415Модуль разработан в соответствии с интернет-стандартом RFC на относительные унифицированные указатели ресурсов. Он поддерживает следующие схемы URL: `file`, `ftp`, `gopher`, `hdl`, `http`, `https`, `imap`, `itms-services`, `mailto`, `mms`, `news`, `nntp`, `prospero`, `rsync`, `rtsp`, `rtsps`, `rtspu`, `sftp`, `shttp`, `sip`, `sips`, `snews`, `svn`, `svn+ssh`, `telnet`, `wais`, `ws`, `wss`.1617**Особенность реализации CPython:** Включение схемы URL `itms-services` может помешать приложению пройти проверку Apple App Store для macOS и iOS. Обработка схемы `itms-services` всегда удаляется на iOS; на macOS она *может* быть удалена, если CPython был собран с опцией [`--with-app-store-compliance`](https://python-all.ru/3.13/using/configure.html#cmdoption-with-app-store-compliance).1819Модуль `urllib.parse` определяет функции, которые делятся на две большие категории: разбор URL и квотирование URL. Они подробно рассматриваются в следующих разделах.2021Функции этого модуля используют устаревший термин `netloc` (или `net_loc`), который был введён в [**RFC 1808**](https://python-all.ru/3.13/library/urllib.parse.html). Однако этот термин был заменён [**RFC 3986**](https://python-all.ru/3.13/library/urllib.parse.html), который ввёл термин `authority`. Использование `netloc` сохранено для обратной совместимости.2223## Разбор URL2425Функции разбора URL предназначены для разделения строки URL на компоненты или для объединения компонентов URL в строку URL.2627#### `urllib.parse.urlsplit(urlstring, scheme=None, allow_fragments=True)`2829Разбирает URL на пять компонентов и возвращает [именованный кортеж](https://python-all.ru/3.13/glossary.html#term-named-tuple) из пяти элементов [`SplitResult`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.SplitResult) или [`SplitResultBytes`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.SplitResultBytes). Это соответствует общей структуре URL: `scheme://netloc/path?query#fragment`. Каждый элемент кортежа – строка, возможно пустая.3031Разделители, показанные выше, не входят в результат, за исключением начального слеша в компоненте *path*, который сохраняется, если присутствует.3233Кроме того, свойство netloc разбивается на следующие дополнительные атрибуты, добавляемые к возвращаемому объекту: username, password, hostname и port.3435Процентно-кодированные последовательности не декодируются.3637Например:3839```pycon40>>> from urllib.parse import urlsplit41>>> urlsplit("scheme://netloc/path?query#fragment")42SplitResult(scheme='scheme', netloc='netloc', path='/path',43            query='query', fragment='fragment')44>>> o = urlsplit("http://docs.python.org:80/3/library/urllib.parse.html?"45...              "highlight=params#url-parsing")46>>> o47SplitResult(scheme='http', netloc='docs.python.org:80',48            path='/3/library/urllib.parse.html',49            query='highlight=params', fragment='url-parsing')50>>> o.scheme51'http'52>>> o.netloc53'docs.python.org:80'54>>> o.hostname55'docs.python.org'56>>> o.port578058>>> o._replace(fragment="").geturl()59'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'60```6162Следуя спецификациям синтаксиса в [**RFC 1808**](https://python-all.ru/3.13/library/urllib.parse.html), `urlsplit()` распознает netloc только если он правильно обозначен через ‘//’. В противном случае считается, что входные данные являются относительным URL и, следовательно, начинаются с компонента пути.6364```pycon65>>> from urllib.parse import urlsplit66>>> urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')67SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',68            query='', fragment='')69>>> urlsplit('www.cwi.nl/%7Eguido/Python.html')70SplitResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',71            query='', fragment='')72>>> urlsplit('help/Python.html')73SplitResult(scheme='', netloc='', path='help/Python.html',74            query='', fragment='')75```7677Аргумент *scheme* задаёт схему адресации по умолчанию, которая используется только если URL её не указывает. Он должен быть того же типа (текст или байты), что и *urlstring*, за исключением того, что значение по умолчанию `''` всегда разрешено и автоматически преобразуется в `b''` при необходимости.7879Если аргумент *allow\_fragments* равен false, идентификаторы фрагментов не распознаются. Вместо этого они анализируются как часть пути, параметров или компонента запроса, а `fragment` в возвращаемом значении устанавливается в пустую строку.8081Возвращаемое значение – это [именованный кортеж](https://python-all.ru/3.13/glossary.html#term-named-tuple), что означает, что к его элементам можно обращаться по индексу или по именованным атрибутам, которые:8283| Атрибут | Индекс | Значение | Значение, если отсутствует |84| --- | --- | --- | --- |85| `scheme` | 0 | Спецификатор схемы URL | Параметр *scheme* |86| `netloc` | 1 | Сетевое расположение | пустая строка |87| `path` | 2 | Иерархический путь | пустая строка |88| `query` | 3 | Компонент запроса | пустая строка |89| `fragment` | 4 | Идентификатор фрагмента | пустая строка |90| `username` |  | Имя пользователя | [`None`](https://python-all.ru/3.13/library/constants.html#None) |91| `password` |  | Пароль | [`None`](https://python-all.ru/3.13/library/constants.html#None) |92| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/3.13/library/constants.html#None) |93| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/3.13/library/constants.html#None) |9495Чтение атрибута `port` возбуждает [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError), если в URL указан недопустимый порт. Дополнительную информацию об объекте результата см. в разделе [Результаты структурированного разбора](https://python-all.ru/3.13/library/urllib.parse.html#urlparse-result-object).9697Непарные квадратные скобки в атрибуте `netloc` возбуждают [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).9899Символы в атрибуте `netloc`, которые при NFKC-нормализации (используемой в кодировке IDNA) раскладываются в любой из `/`, `?`, `#`, `@` или `:`, возбуждают [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError). Если URL разложен до разбора, ошибка не возникнет.100101В соответствии с некоторыми положениями [спецификации WHATWG](https://python-all.ru/3.13/library/urllib.parse.html), которая обновляет [**RFC 3986**](https://python-all.ru/3.13/library/urllib.parse.html), начальные управляющие символы C0 и пробелы удаляются из URL. Символы `\n`, `\r` и табуляции `\t` удаляются из URL на любой позиции.102103Как и все именованные кортежи, подкласс имеет несколько дополнительных методов и атрибутов, которые особенно полезны. Один из таких методов – `_replace()`. Метод `_replace()` возвращает новый объект [`SplitResult`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.SplitResult), заменяя указанные поля новыми значениями.104105```pycon106>>> from urllib.parse import urlsplit107>>> u = urlsplit('//www.cwi.nl:80/%7Eguido/Python.html')108>>> u109SplitResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',110            query='', fragment='')111>>> u._replace(scheme='http')112SplitResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',113            query='', fragment='')114```115116> **Предупреждение**117>118> `urlsplit()` не выполняет проверку. Подробнее см. [безопасность разбора URL](https://python-all.ru/3.13/library/urllib.parse.html#url-parsing-security).119120Изменено в версии 3.2: Добавлена возможность разбора URL с IPv6.121122Изменено в версии 3.3: Фрагмент теперь разбирается для всех схем URL (если *allow\_fragments* не равен false), в соответствии с [**RFC 3986**](https://python-all.ru/3.13/library/urllib.parse.html). Ранее существовал список разрешённых схем, поддерживающих фрагменты.123124Изменено в версии 3.6: Номера портов вне диапазона теперь возбуждают [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError) вместо возврата [`None`](https://python-all.ru/3.13/library/constants.html#None).125126Изменено в версии 3.8: Символы, влияющие на разбор netloc при NFKC-нормализации, теперь возбуждают [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).127128Изменено в версии 3.10: Символы ASCII перевода строки и табуляции удаляются из URL.129130Изменено в версии 3.12: Начальные управляющие символы C0 и пробелы (по WHATWG) удаляются из URL.131132#### `urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')`133134Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде словаря. Ключами словаря являются уникальные имена переменных запроса, а значениями – списки значений для каждого имени.135136Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение True означает, что пустые значения должны сохраняться как пустые строки. Значение False по умолчанию означает, что пустые значения игнорируются и считаются отсутствующими.137138Необязательный аргумент *strict\_parsing* – это флаг, указывающий, что делать с ошибками разбора. Если False (по умолчанию), ошибки молча игнорируются. Если True, ошибки возбуждают исключение [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).139140Необязательные параметры *encoding* и *errors* определяют, как декодировать процентно-кодированные последовательности в символы Unicode, как это принимается методом [`bytes.decode()`](https://python-all.ru/3.13/library/stdtypes.html#bytes.decode).141142Необязательный аргумент *max\_num\_fields* – это максимальное количество полей для чтения. Если он задан, то при чтении более *max\_num\_fields* полей возбуждается [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).143144Необязательный аргумент *separator* – это символ, используемый для разделения аргументов запроса. По умолчанию он равен `&`.145146Для преобразования таких словарей в строки запроса используется функция [`urllib.parse.urlencode()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlencode) (с параметром `doseq`, установленным в `True`).147148Изменено в версии 3.2: Добавлены параметры *encoding* и *errors*.149150Изменено в версии 3.8: Добавлен параметр *max\_num\_fields*.151152Изменено в версии 3.10: Добавлен параметр *separator* со значением по умолчанию `&`. В версиях Python до 3.10 допускалось использование как `;`, так и `&` в качестве разделителя параметров запроса. Теперь разрешён только один ключ-разделитель, и по умолчанию используется `&`.153154#### `urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')`155156Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде списка пар имя, значение.157158Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение True означает, что пустые значения должны сохраняться как пустые строки. Значение False по умолчанию означает, что пустые значения игнорируются и считаются отсутствующими.159160Необязательный аргумент *strict\_parsing* – это флаг, указывающий, что делать с ошибками разбора. Если False (по умолчанию), ошибки молча игнорируются. Если True, ошибки возбуждают исключение [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).161162Необязательные параметры *encoding* и *errors* определяют, как декодировать процентно-кодированные последовательности в символы Unicode, как это принимается методом [`bytes.decode()`](https://python-all.ru/3.13/library/stdtypes.html#bytes.decode).163164Необязательный аргумент *max\_num\_fields* – это максимальное количество полей для чтения. Если он задан, то при чтении более *max\_num\_fields* полей возбуждается [`ValueError`](https://python-all.ru/3.13/library/exceptions.html#ValueError).165166Необязательный аргумент *separator* – это символ, используемый для разделения аргументов запроса. По умолчанию он равен `&`.167168Используйте функцию [`urllib.parse.urlencode()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlencode) для преобразования таких списков пар в строки запроса.169170Изменено в версии 3.2: Добавлены параметры *encoding* и *errors*.171172Изменено в версии 3.8: Добавлен параметр *max\_num\_fields*.173174Изменено в версии 3.10: Добавлен параметр *separator* со значением по умолчанию `&`. В версиях Python до 3.10 допускалось использование как `;`, так и `&` в качестве разделителя параметров запроса. Теперь разрешён только один ключ-разделитель, и по умолчанию используется `&`.175176#### `urllib.parse.urlunsplit(parts)`177178Строит URL из кортежа, возвращаемого `urlsplit()`. Аргумент *parts* может быть любым итерируемым объектом из пяти элементов. Это может привести к немного отличающемуся, но эквивалентному URL, если исходный разобранный URL содержал лишние разделители (например, `?` с пустым запросом; RFC утверждает, что они эквивалентны).179180#### `urllib.parse.urlparse(urlstring, scheme=None, allow_fragments=True)`181182Это похоже на [`urlsplit()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlsplit), но дополнительно разделяет компонент *path* на *path* и *params*. Эта функция возвращает [именованный кортеж](https://python-all.ru/3.13/glossary.html#term-named-tuple) из 6 элементов [`ParseResult`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.ParseResult) или [`ParseResultBytes`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.ParseResultBytes). Его элементы те же, что и в результате `urlsplit()`, за исключением того, что *params* вставляется на индекс 3 между *path* и *query*.183184Эта функция основана на устаревших [**RFC 1738**](https://python-all.ru/3.13/library/urllib.parse.html) и [**RFC 1808**](https://python-all.ru/3.13/library/urllib.parse.html), в которых *params* указывался как основной компонент URL. В более современном синтаксисе URL параметры могут применяться к каждому сегменту части *path* (см. [**RFC 3986**](https://python-all.ru/3.13/library/urllib.parse.html)). Вместо `urlparse()` обычно следует использовать [`urlsplit()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlsplit). Для разделения сегментов пути и параметров требуется отдельная функция.185186#### `urllib.parse.urlunparse(parts)`187188Объединяет элементы кортежа, возвращаемого функцией [`urlparse()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlparse), в полный URL в виде строки. Аргумент *parts* может быть любым итерируемым объектом из шести элементов. Это может привести к немного отличающемуся, но эквивалентному URL, если исходный разобранный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны).189190#### `urllib.parse.urljoin(base, url, allow_fragments=True)`191192Строит полный («абсолютный») URL путём объединения «базового URL» (*base*) с другим URL (*url*). Неформально: используются компоненты базового URL, в частности схема адресации, сетевое расположение и (часть) пути, чтобы предоставить недостающие компоненты в относительном URL. Например:193194```python195>>> from urllib.parse import urljoin196>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')197'http://www.cwi.nl/%7Eguido/FAQ.html'198```199200Аргумент *allow\_fragments* имеет то же значение и значение по умолчанию, что и для [`urlsplit()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlsplit).201202> **Примечание**203>204> Если *url* является абсолютным URL (то есть начинается с `//` или `scheme://`), то имя хоста и/или схема из *url* будут присутствовать в результате. Например:205>206> ```pycon207> >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',208> ...         '//www.python.org/%7Eguido')209> 'http://www.python.org/%7Eguido'210> ```211>212> Если такое поведение нежелательно, предварительно обработайте *url* с помощью [`urlsplit()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlsplit) и [`urlunsplit()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlunsplit), удалив возможные части *scheme* и *netloc*.213214> **Предупреждение**215>216> Поскольку абсолютный URL может быть передан в качестве параметра `url`, в целом **небезопасно** использовать `urljoin` с контролируемым злоумышленником `url`. Например, в `urljoin("https://website.com/users/", username)`, если `username` может содержать абсолютный URL, результатом `urljoin` будет этот абсолютный URL.217218Изменено в версии 3.5: Поведение обновлено в соответствии с семантикой, определённой в [**RFC 3986**](https://python-all.ru/3.13/library/urllib.parse.html).219220#### `urllib.parse.urldefrag(url)`221222Если *url* содержит идентификатор фрагмента, возвращает изменённую версию *url* без идентификатора фрагмента и сам идентификатор фрагмента в виде отдельной строки. Если в *url* нет идентификатора фрагмента, возвращает *url* без изменений и пустую строку.223224Возвращаемое значение – [именованный кортеж](https://python-all.ru/3.13/glossary.html#term-named-tuple), его элементы доступны по индексу или как именованные атрибуты:225226| Атрибут | Индекс | Значение | Значение, если отсутствует |227| --- | --- | --- | --- |228| `url` | 0 | URL без фрагмента | пустая строка |229| `fragment` | 1 | Идентификатор фрагмента | пустая строка |230231См. раздел [Структурированные результаты разбора](https://python-all.ru/3.13/library/urllib.parse.html#urlparse-result-object) для получения дополнительной информации об объекте результата.232233Изменено в версии 3.2: Результат – структурированный объект, а не простой кортеж из двух элементов.234235#### `urllib.parse.unwrap(url)`236237Извлекает URL из обёрнутого URL (то есть строки, отформатированной как `<URL:scheme://host/path>`, `<scheme://host/path>`, `URL:scheme://host/path` или `scheme://host/path`). Если *url* не является обёрнутым URL, он возвращается без изменений.238239## Безопасность разбора URL240241API [`urlsplit()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlsplit) и [`urlparse()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlparse) не выполняют **валидацию** входных данных. Они могут не вызывать ошибки на входных данных, которые другие приложения считают недопустимыми. Они также могут успешно обработать некоторые входные данные, которые в других местах не считаются URL. Их цель – практическая функциональность, а не чистота.242243Вместо того чтобы вызывать исключение для необычных входных данных, они могут возвращать некоторые составные части как пустые строки. Или компоненты могут содержать больше, чем, возможно, должны.244245Мы рекомендуем пользователям этих API, если значения могут использоваться где-либо с последствиями для безопасности, писать защитный код. Выполните некоторую проверку в своем коде, прежде чем доверять возвращенной составной части. Имеет ли `scheme` смысл? Разумен ли `path`? Нет ли чего-то странного в `hostname`? и т.д.246247Что составляет URL – не общепринятое определение. Разные приложения имеют разные потребности и желаемые ограничения. Например, живая [спецификация WHATWG](https://python-all.ru/3.13/library/urllib.parse.html) описывает, что требуется пользовательским веб-клиентам, таким как веб-браузер. В то время как [**RFC 3986**](https://python-all.ru/3.13/library/urllib.parse.html) является более общим. Эти функции включают некоторые аспекты обоих, но не могут считаться совместимыми ни с одним из них. API и существующий пользовательский код с ожиданиями определенного поведения предшествуют обоим стандартам, что заставляет нас быть очень осторожными с изменениями поведения API.248249## Разбор ASCII-кодированных байтов250251Функции разбора URL изначально были разработаны для работы только с символьными строками. На практике полезно иметь возможность манипулировать правильно экранированными и закодированными URL как последовательностями ASCII байтов. Соответственно, все функции разбора URL в этом модуле работают с объектами [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) и [`bytearray`](https://python-all.ru/3.13/library/stdtypes.html#bytearray) в дополнение к объектам [`str`](https://python-all.ru/3.13/library/stdtypes.html#str).252253Если передаются данные [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), результат также будет содержать только данные `str`. Если передаются данные [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.13/library/stdtypes.html#bytearray), результат будет содержать только данные `bytes`.254255Попытка смешать данные [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) с [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.13/library/stdtypes.html#bytearray) в одном вызове функции приведет к возникновению [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError), а попытка передать не-ASCII байтовые значения вызовет [`UnicodeDecodeError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeDecodeError).256257Чтобы упростить преобразование объектов результатов между [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) и [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes), все возвращаемые значения функций разбора URL предоставляют либо метод `encode()` (если результат содержит данные `str`), либо метод `decode()` (если результат содержит данные `bytes`). Сигнатуры этих методов соответствуют сигнатурам соответствующих методов `str` и `bytes` (за исключением того, что кодировка по умолчанию – `'ascii'` вместо `'utf-8'`). Каждый из них создает значение соответствующего типа, содержащее либо данные `bytes` (для методов `encode()`), либо данные `str` (для методов `decode()`).258259Приложениям, которым необходимо работать с потенциально неправильно экранированными URL, которые могут содержать не-ASCII данные, потребуется выполнить собственное декодирование из байтов в символы перед вызовом методов разбора URL.260261Поведение, описанное в этом разделе, применяется только к функциям разбора URL. Функции экранирования URL используют свои собственные правила при создании или потреблении последовательностей байтов, как подробно описано в документации отдельных функций экранирования URL.262263Изменено в версии 3.2: Функции разбора URL теперь принимают ASCII-кодированные последовательности байтов264265## Структурированные результаты разбора266267Объекты результатов функций [`urlsplit()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlsplit), [`urlparse()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlparse) и [`urldefrag()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urldefrag) являются подклассами типа [`tuple`](https://python-all.ru/3.13/library/stdtypes.html#tuple). Эти подклассы добавляют атрибуты, перечисленные в документации этих функций, поддержку кодирования и декодирования, описанную в предыдущем разделе, а также дополнительный метод:268269#### `urllib.parse.SplitResult.geturl()`270271Возвращает перекомбинированную версию исходного URL в виде строки. Она может отличаться от исходного URL тем, что схема может быть нормализована к нижнему регистру, а пустые компоненты могут быть отброшены. В частности, пустые параметры, запросы и идентификаторы фрагментов будут удалены.272273Для результатов [`urldefrag()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urldefrag) будут удалены только пустые идентификаторы фрагментов. Для результатов [`urlsplit()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlsplit) и [`urlparse()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlparse) все отмеченные изменения будут применены к URL, возвращаемому этим методом.274275Результат этого метода остается неизменным, если его снова передать через исходную функцию разбора:276277```python278>>> from urllib.parse import urlsplit279>>> url = 'HTTP://www.Python.org/doc/#'280>>> r1 = urlsplit(url)281>>> r1.geturl()282'http://www.Python.org/doc/'283>>> r2 = urlsplit(r1.geturl())284>>> r2.geturl()285'http://www.Python.org/doc/'286```287288Следующие классы предоставляют реализации структурированных результатов разбора при работе с объектами [`str`](https://python-all.ru/3.13/library/stdtypes.html#str):289290#### `class urllib.parse.DefragResult(url, fragment)`291292Конкретный класс для результатов [`urldefrag()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urldefrag), содержащих данные [`str`](https://python-all.ru/3.13/library/stdtypes.html#str). Метод `encode()` возвращает экземпляр [`DefragResultBytes`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.DefragResultBytes).293294Добавлено в версии 3.2.295296#### `class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)`297298Конкретный класс для результатов [`urlparse()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlparse), содержащих данные [`str`](https://python-all.ru/3.13/library/stdtypes.html#str). Метод `encode()` возвращает экземпляр [`ParseResultBytes`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.ParseResultBytes).299300#### `class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)`301302Конкретный класс для результатов [`urlsplit()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlsplit), содержащих данные [`str`](https://python-all.ru/3.13/library/stdtypes.html#str). Метод `encode()` возвращает экземпляр [`SplitResultBytes`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.SplitResultBytes).303304Следующие классы предоставляют реализации результатов разбора при работе с объектами [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) или [`bytearray`](https://python-all.ru/3.13/library/stdtypes.html#bytearray):305306#### `class urllib.parse.DefragResultBytes(url, fragment)`307308Конкретный класс для результатов [`urldefrag()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urldefrag), содержащих данные [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes). Метод `decode()` возвращает экземпляр [`DefragResult`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.DefragResult).309310Добавлено в версии 3.2.311312#### `class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)`313314Конкретный класс для результатов [`urlparse()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlparse), содержащих данные [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes). Метод `decode()` возвращает экземпляр [`ParseResult`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.ParseResult).315316Добавлено в версии 3.2.317318#### `class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)`319320Конкретный класс для результатов [`urlsplit()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.urlsplit), содержащих данные [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes). Метод `decode()` возвращает экземпляр [`SplitResult`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.SplitResult).321322Добавлено в версии 3.2.323324## Экранирование URL325326Функции экранирования URL предназначены для преобразования программных данных в безопасный формат для использования в компонентах URL: они экранируют специальные символы и кодируют не-ASCII текст. Они также поддерживают обратные операции для восстановления исходных данных из содержимого компонента URL, если эта задача ещё не решается описанными выше функциями разбора URL.327328#### `urllib.parse.quote(string, safe='/', encoding=None, errors=None)`329330Заменяет специальные символы в *string* с помощью экранирования `%xx`. Буквы, цифры и символы `'_.-~'` никогда не экранируются. По умолчанию эта функция предназначена для экранирования части пути URL. Необязательный параметр *safe* задаёт дополнительные ASCII-символы, которые не следует экранировать – его значение по умолчанию: `'/'`.331332*string* может быть либо объектом [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), либо объектом [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes).333334Изменено в версии 3.7: Перенесено из [**RFC 2396**](https://python-all.ru/3.13/library/urllib.parse.html) в [**RFC 3986**](https://python-all.ru/3.13/library/urllib.parse.html) для экранирования строк URL. Символ "~" теперь включён в набор незарезервированных символов.335336Необязательные параметры *encoding* и *errors* задают способ обработки не-ASCII символов, как это принимается методом [`str.encode()`](https://python-all.ru/3.13/library/stdtypes.html#str.encode). Параметр *encoding* по умолчанию равен `'utf-8'`. Параметр *errors* по умолчанию равен `'strict'`, что означает, что неподдерживаемые символы вызывают исключение [`UnicodeEncodeError`](https://python-all.ru/3.13/library/exceptions.html#UnicodeEncodeError). Параметры *encoding* и *errors* не должны передаваться, если *string* является объектом [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes), иначе будет вызвано исключение [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError).337338Обратите внимание, что `quote(string, safe, encoding, errors)` эквивалентно `quote_from_bytes(string.encode(encoding, errors), safe)`.339340Пример: `quote('/El Niño/')` даёт `'/El%20Ni%C3%B1o/'`.341342#### `urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)`343344Как [`quote()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.quote), но также заменяет пробелы на знаки плюс, что требуется для экранирования значений HTML-форм при формировании строки запроса для URL. Знаки плюс в исходной строке экранируются, если они не включены в *safe*. Кроме того, значение по умолчанию для *safe* не равно `'/'`.345346Пример: `quote_plus('/El Niño/')` даёт `'%2FEl+Ni%C3%B1o%2F'`.347348#### `urllib.parse.quote_from_bytes(bytes, safe='/')`349350Как [`quote()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.quote), но принимает объект [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes) вместо [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) и не выполняет кодирование строки в байты.351352Пример: `quote_from_bytes(b'a&\xef')` даёт `'a%26%EF'`.353354#### `urllib.parse.unquote(string, encoding='utf-8', errors='replace')`355356Заменяет управляющие последовательности `%xx` на соответствующий одиночный символ. Необязательные параметры *encoding* и *errors* задают способ декодирования процентно-кодированных последовательностей в символы Unicode, как это принимается методом [`bytes.decode()`](https://python-all.ru/3.13/library/stdtypes.html#bytes.decode).357358*string* может быть либо объектом [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), либо объектом [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes).359360Значение *encoding* по умолчанию – `'utf-8'`. Значение *errors* по умолчанию – `'replace'`, что означает, что недопустимые последовательности заменяются символом-заполнителем.361362Пример: `unquote('/El%20Ni%C3%B1o/')` даёт `'/El Niño/'`.363364Изменено в версии 3.9: Параметр *string* теперь поддерживает объекты bytes и str (ранее только str).365366#### `urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')`367368Как [`unquote()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.unquote), но также заменяет знаки плюс на пробелы, что требуется для восстановления значений HTML-форм.369370*string* должен быть строкой [`str`](https://python-all.ru/3.13/library/stdtypes.html#str).371372Пример: `unquote_plus('/El+Ni%C3%B1o/')` даёт `'/El Niño/'`.373374#### `urllib.parse.unquote_to_bytes(string)`375376Заменяет управляющие последовательности `%xx` на соответствующий одиночный октет и возвращает объект [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes).377378*string* может быть либо объектом [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), либо объектом [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes).379380Если это строка [`str`](https://python-all.ru/3.13/library/stdtypes.html#str), то неэкранированные не-ASCII символы в *string* кодируются в UTF-8 байты.381382Пример: `unquote_to_bytes('a%26%EF')` даёт `b'a&\xef'`.383384#### `urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)`385386Преобразует объект отображения (mapping) или последовательность кортежей из двух элементов, которые могут содержать объекты [`str`](https://python-all.ru/3.13/library/stdtypes.html#str) или [`bytes`](https://python-all.ru/3.13/library/stdtypes.html#bytes), в процентно-кодированную ASCII-строку. Если результирующая строка должна использоваться как данные *data* для операции POST с функцией [`urlopen()`](https://python-all.ru/3.13/library/urllib.request.html#urllib.request.urlopen), то её следует закодировать в байты; в противном случае это приведёт к ошибке [`TypeError`](https://python-all.ru/3.13/library/exceptions.html#TypeError).387388Результирующая строка состоит из последовательности пар `key=value`, разделённых символами `'&'`, при этом и *ключ*, и *значение* экранируются с помощью функции *quote\_via*. По умолчанию для экранирования значений используется [`quote_plus()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.quote_plus), то есть пробелы заменяются на символ `'+'`, а символы '/' кодируются как `%2F`, что соответствует стандарту для GET-запросов (`application/x-www-form-urlencoded`). Альтернативная функция, которую можно передать как *quote\_via* – это [`quote()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.quote), которая кодирует пробелы как `%20` и не кодирует символы '/'. Для максимального контроля над тем, что экранируется, используйте `quote` и задайте значение для *safe*.389390Когда в качестве аргумента *query* используется последовательность кортежей из двух элементов, первый элемент каждого кортежа – это ключ, а второй – значение. Само значение тоже может быть последовательностью, и в этом случае, если необязательный параметр *doseq* принимает значение `True`, для каждого элемента последовательности значений по данному ключу генерируются отдельные пары `key=value`, разделённые `'&'`. Порядок параметров в закодированной строке будет соответствовать порядку кортежей параметров в последовательности.391392Параметры *safe*, *encoding* и *errors* передаются в функцию *quote\_via* (параметры *encoding* и *errors* передаются только когда элемент запроса является [`str`](https://python-all.ru/3.13/library/stdtypes.html#str)).393394Для обращения этого процесса кодирования в модуле предусмотрены [`parse_qs()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.parse_qs) и [`parse_qsl()`](https://python-all.ru/3.13/library/urllib.parse.html#urllib.parse.parse_qsl), которые преобразуют строки запроса в структуры данных Python.395396Обратитесь к [примерам urllib](https://python-all.ru/3.13/library/urllib.request.html#urllib-examples), чтобы узнать, как метод `urllib.parse.urlencode()` может использоваться для формирования строки запроса URL или данных для POST-запроса.397398Изменено в версии 3.2: параметр *query* теперь поддерживает объекты bytes и string.399400Изменено в версии 3.5: добавлен параметр *quote\_via*.401402> **См. также**403>404> **[WHATWG](https://python-all.ru/3.13/library/urllib.parse.html) – URL Living Standard**405>406> Рабочая группа по стандарту URL, которая определяет URL, домены, IP-адреса, формат application/x-www-form-urlencoded и их API.407>408> **[**RFC 3986**](https://python-all.ru/3.13/library/urllib.parse.html) – Uniform Resource Identifiers**409>410> Это текущий стандарт (STD66). Любые изменения в модуле urllib.parse должны ему соответствовать. Могут наблюдаться некоторые отклонения, которые в основном обусловлены обратной совместимостью и некоторыми фактическими требованиями парсинга, обычно встречающимися в основных браузерах.411>412> **[**RFC 2732**](https://python-all.ru/3.13/library/urllib.parse.html) – Формат литеральных IPv6-адресов в URL.**413>414> В нём описываются требования к парсингу IPv6 URL.415>416> **[**RFC 2396**](https://python-all.ru/3.13/library/urllib.parse.html) – Uniform Resource Identifiers (URI): Generic Syntax**417>418> Документ, описывающий общие синтаксические требования как для Uniform Resource Names (URN), так и для Uniform Resource Locators (URL).419>420> **[**RFC 2368**](https://python-all.ru/3.13/library/urllib.parse.html) – Схема URL mailto.**421>422> Требования к парсингу схем URL mailto.423>424> **[**RFC 1808**](https://python-all.ru/3.13/library/urllib.parse.html) – Relative Uniform Resource Locators**425>426> Этот документ (RFC) включает правила объединения абсолютного и относительного URL, включая значительное количество «Аномальных примеров», которые определяют обработку граничных случаев.427>428> **[**RFC 1738**](https://python-all.ru/3.13/library/urllib.parse.html) – Uniform Resource Locators (URL)**429>430> В нём описывается формальный синтаксис и семантика абсолютных URL.431