urllib.parse.md

1> **Источник:** https://python-all.ru/3.1/library/urllib.parse.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 20.7. `urllib.parse` – Разбор URL на компоненты89Этот модуль предоставляет стандартный интерфейс для разбора строки URL на компоненты (схема адресации, сетевое расположение, путь и т.д.), обратной сборки компонентов в строку URL, а также для преобразования «относительного URL» в абсолютный по заданному «базовому URL».1011Модуль разработан в соответствии с 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`.1213Модуль `urllib.parse` определяет следующие функции:1415#### `urllib.parse.urlparse(urlstring, scheme='', allow_fragments=True)`1617Разбирает URL на шесть компонентов и возвращает кортеж из шести элементов. Это соответствует общей структуре URL: `scheme://netloc/path;parameters?query#fragment`. Каждый элемент кортежа – строка, возможно пустая. Компоненты не разбиваются на более мелкие части (например, сетевое расположение – это одна строка), а %-последовательности не раскрываются. Разделители, показанные выше, не входят в результат, за исключением начальной косой черты в компоненте *path*, которая сохраняется, если присутствует. Например:1819```python20>>> from urllib.parse import urlparse21>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')22>>> o   # doctest: +NORMALIZE_WHITESPACE23ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',24            params='', query='', fragment='')25>>> o.scheme26'http'27>>> o.port288029>>> o.geturl()30'http://www.cwi.nl:80/%7Eguido/Python.html'31```3233Следуя синтаксическим спецификациям [**RFC 1808**](https://python-all.ru/3.1/library/urllib.parse.html), urlparse распознаёт netloc только в том случае, если она правильно введена символами '//'. В противном случае считается, что входные данные – это относительный URL, и, следовательно, они начинаются с компонента пути.3435```python36>>> from urllib.parse import urlparse37>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')38ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',39           params='', query='', fragment='')40>>> urlparse('www.cwi.nl:80/%7Eguido/Python.html')41ParseResult(scheme='', netloc='', path='www.cwi.nl:80/%7Eguido/Python.html',42           params='', query='', fragment='')43>>> urlparse('help/Python.html')44ParseResult(scheme='', netloc='', path='help/Python.html', params='',45           query='', fragment='')46```4748Если аргумент *scheme* указан, он задаёт схему адресации по умолчанию, которая используется только в том случае, если URL сам её не указывает. Значение по умолчанию для этого аргумента – пустая строка.4950Если аргумент *allow\_fragments* равен false, идентификаторы фрагментов не допускаются, даже если схема адресации URL обычно их поддерживает. Значением по умолчанию для этого аргумента является [`True`](https://python-all.ru/3.1/library/constants.html#True).5152Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/3.1/library/functions.html#tuple). Этот класс имеет следующие дополнительные атрибуты только для чтения, предоставляющие удобный доступ:5354| Атрибут | Индекс | Значение | Значение, если отсутствует |55| --- | --- | --- | --- |56| `scheme` | 0 | Спецификатор схемы URL | пустая строка |57| `netloc` | 1 | Сетевое расположение | пустая строка |58| `path` | 2 | Иерархический путь | пустая строка |59| `params` | 3 | Параметры последнего элемента пути | пустая строка |60| `query` | 4 | Компонент запроса | пустая строка |61| `fragment` | 5 | Идентификатор фрагмента | пустая строка |62| `username` |  | Имя пользователя | [`None`](https://python-all.ru/3.1/library/constants.html#None) |63| `password` |  | Пароль | [`None`](https://python-all.ru/3.1/library/constants.html#None) |64| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/3.1/library/constants.html#None) |65| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/3.1/library/constants.html#None) |6667Смотрите раздел [*Результаты urlparse() и urlsplit()*](https://python-all.ru/3.1/library/urllib.parse.html#urlparse-result-object) для получения дополнительной информации об объекте результата.6869#### `urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False)`7071Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде словаря. Ключами словаря являются уникальные имена переменных запроса, а значениями – списки значений для каждого имени.7273Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение True означает, что пустые значения должны сохраняться как пустые строки. Значение False по умолчанию означает, что пустые значения игнорируются и считаются отсутствующими.7475Необязательный аргумент *strict\_parsing* – флаг, указывающий, что делать с ошибками разбора. Если false (по умолчанию), ошибки игнорируются. Если true, ошибки вызывают исключение [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError).7677Используйте функцию [`urllib.parse.urlencode()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlencode) для преобразования таких словарей в строки запроса.7879#### `urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False)`8081Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде списка пар имя, значение.8283Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение True означает, что пустые значения должны сохраняться как пустые строки. Значение False по умолчанию означает, что пустые значения игнорируются и считаются отсутствующими.8485Необязательный аргумент *strict\_parsing* – флаг, указывающий, что делать с ошибками разбора. Если false (по умолчанию), ошибки игнорируются. Если true, ошибки вызывают исключение [`ValueError`](https://python-all.ru/3.1/library/exceptions.html#ValueError).8687Используйте функцию [`urllib.parse.urlencode()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlencode) для преобразования таких списков пар в строки запроса.8889#### `urllib.parse.urlunparse(parts)`9091Создаёт URL из кортежа, возвращаемого функцией9293`urlparse()`9495. Аргумент9697*parts*9899может быть любым итерируемым объектом из шести элементов. Результат может немного отличаться от исходного, но быть эквивалентным URL, если исходный URL содержал лишние разделители (например,100101`?`102103с пустым запросом; RFC утверждает, что они эквивалентны).104105#### `urllib.parse.urlsplit(urlstring, scheme='', allow_fragments=True)`106107Эта функция похожа на [`urlparse()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlparse), но не отделяет параметры от URL. Как правило, её следует использовать вместо [`urlparse()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlparse), если требуется более новый синтаксис URL, допускающий применение параметров к каждому сегменту части *path* (см. [**RFC 2396**](https://python-all.ru/3.1/library/urllib.parse.html)). Для разделения сегментов пути и параметров нужна отдельная функция. Эта функция возвращает 5-кортеж: (схема адресации, сетевое расположение, путь, запрос, идентификатор фрагмента).108109Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/3.1/library/functions.html#tuple). Этот класс имеет следующие дополнительные атрибуты только для чтения, предоставляющие удобный доступ:110111| Атрибут | Индекс | Значение | Значение, если отсутствует |112| --- | --- | --- | --- |113| `scheme` | 0 | Спецификатор схемы URL | пустая строка |114| `netloc` | 1 | Сетевое расположение | пустая строка |115| `path` | 2 | Иерархический путь | пустая строка |116| `query` | 3 | Компонент запроса | пустая строка |117| `fragment` | 4 | Идентификатор фрагмента | пустая строка |118| `username` |  | Имя пользователя | [`None`](https://python-all.ru/3.1/library/constants.html#None) |119| `password` |  | Пароль | [`None`](https://python-all.ru/3.1/library/constants.html#None) |120| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/3.1/library/constants.html#None) |121| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/3.1/library/constants.html#None) |122123См. раздел [*Результаты urlparse() и urlsplit()*](https://python-all.ru/3.1/library/urllib.parse.html#urlparse-result-object) для получения дополнительной информации о результирующем объекте.124125#### `urllib.parse.urlunsplit(parts)`126127Объединяет элементы кортежа, возвращаемого функцией128129[`urlsplit()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlsplit)130131, в полный URL в виде строки. Аргумент132133*parts*134135может быть любым итерируемым объектом из пяти элементов. Результат может немного отличаться, но быть эквивалентным, если исходный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны).136137#### `urllib.parse.urljoin(base, url, allow_fragments=True)`138139Строит полный («абсолютный») URL путём объединения «базового URL» (*base*) с другим URL (*url*). Неформально: используются компоненты базового URL, в частности схема адресации, сетевое расположение и (часть) пути, чтобы предоставить недостающие компоненты в относительном URL. Например:140141```python142>>> from urllib.parse import urljoin143>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')144'http://www.cwi.nl/%7Eguido/FAQ.html'145```146147Аргумент *allow\_fragments* имеет тот же смысл и значение по умолчанию, что и для [`urlparse()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlparse).148149> **Примечание**150>151> Если *url* является абсолютным URL (то есть начинается с `//` или `scheme://`), то имя хоста и/или схема *url* будут присутствовать в результате. Например:152153```python154>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',155...         '//www.python.org/%7Eguido')156'http://www.python.org/%7Eguido'157```158159Если такое поведение нежелательно, предварительно обработайте *url* с помощью [`urlsplit()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlsplit) и [`urlunsplit()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlunsplit), удалив возможные части *scheme* и *netloc*.160161#### `urllib.parse.urldefrag(url)`162163Если164165*url*166167содержит идентификатор фрагмента, возвращает изменённую версию168169*url*170171без идентификатора фрагмента и сам идентификатор фрагмента в виде отдельной строки. Если в172173*url*174175нет идентификатора фрагмента, возвращает176177*url*178179без изменений и пустую строку.180181#### `urllib.parse.quote(string, safe='/', encoding=None, errors=None)`182183Заменяет специальные символы в *string* с помощью экранирования `%xx`. Буквы, цифры и символы `'_.-'` никогда не экранируются. По умолчанию эта функция предназначена для экранирования компонента пути URL. Необязательный параметр *safe* задаёт дополнительные символы ASCII, которые не должны экранироваться – его значение по умолчанию равно `'/'`.184185*string* может быть как строкой [`str`](https://python-all.ru/3.1/library/functions.html#str), так и объектом [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes).186187Необязательные параметры *encoding* и *errors* определяют, как обрабатывать не-ASCII символы; они принимаются методом [`str.encode()`](https://python-all.ru/3.1/library/stdtypes.html#str.encode). *encoding* по умолчанию равен `'utf-8'`. *errors* по умолчанию равен `'strict'`, то есть неподдерживаемые символы вызывают [`UnicodeEncodeError`](https://python-all.ru/3.1/library/exceptions.html#UnicodeEncodeError). *encoding* и *errors* не должны указываться, если *string* является [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), иначе будет возбуждено [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError).188189Обратите внимание, что `quote(string, safe, encoding, errors)` эквивалентно `quote_from_bytes(string.encode(encoding, errors), safe)`.190191Пример: `quote('/El Niño/')` возвращает `'/El%20Ni%C3%B1o/'`.192193#### `urllib.parse.quote_plus(string, safe='', encoding=None, errors=None)`194195Аналогична [`quote()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.quote), но также заменяет пробелы знаками плюс, как требуется для экранирования значений HTML-форм при составлении строки запроса для URL. Знаки плюс в исходной строке экранируются, если они не включены в *safe*. Кроме того, значение по умолчанию *safe* не равно `'/'`.196197Пример: `quote_plus('/El Niño/')` возвращает `'%2FEl+Ni%C3%B1o%2F'`.198199#### `urllib.parse.quote_from_bytes(bytes, safe='/')`200201Аналогична [`quote()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.quote), но принимает объект [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes) вместо [`str`](https://python-all.ru/3.1/library/functions.html#str) и не выполняет преобразование строки в байты.202203Пример: `quote_from_bytes(b'a&\xef')` возвращает `'a%26%EF'`.204205#### `urllib.parse.unquote(string, encoding='utf-8', errors='replace')`206207Заменяет последовательности `%xx` на соответствующий им одиночный символ. Необязательные параметры *encoding* и *errors* задают, как декодировать процентно-кодированные последовательности в символы Юникода, как это делается в методе [`bytes.decode()`](https://python-all.ru/3.1/library/stdtypes.html#bytes.decode).208209*string* должен иметь тип [`str`](https://python-all.ru/3.1/library/functions.html#str).210211По умолчанию *encoding* равен `'utf-8'`. *errors* по умолчанию равен `'replace'`, то есть недопустимые последовательности заменяются на символ-заменитель.212213Пример: `unquote('/El%20Ni%C3%B1o/')` возвращает `'/El Niño/'`.214215#### `urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')`216217Аналогично [`unquote()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.unquote), но дополнительно заменяет знаки плюс пробелами, что требуется для декодирования значений HTML-форм.218219*string* должен иметь тип [`str`](https://python-all.ru/3.1/library/functions.html#str).220221Пример: `unquote_plus('/El+Ni%C3%B1o/')` возвращает `'/El Niño/'`.222223#### `urllib.parse.unquote_to_bytes(string)`224225Заменяет последовательности `%xx` на эквивалентный одиночный октет и возвращает объект [`байтов`](https://python-all.ru/3.1/library/functions.html#bytes).226227*string* может быть как строкой [`str`](https://python-all.ru/3.1/library/functions.html#str), так и объектом [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes).228229Если это строка [`str`](https://python-all.ru/3.1/library/functions.html#str), то неэкранированные не-ASCII символы в *string* кодируются в байты UTF-8.230231Пример: `unquote_to_bytes('a%26%EF')` возвращает `b'a&\xef'`.232233#### `urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None)`234235Преобразует объект отображения или последовательность двухэлементных кортежей, каждый из которых может быть как [`str`](https://python-all.ru/3.1/library/functions.html#str), так и [`bytes`](https://python-all.ru/3.1/library/functions.html#bytes), в строку в «процентной» кодировке, пригодную для передачи в качестве необязательного аргумента *data* функции `urlopen()` (см. выше). Это удобно для передачи словаря полей формы в запросе `POST`. Результирующая строка представляет собой последовательность пар `key=value`, разделённых символами `'&'`, где и *key*, и *value* кодируются с помощью [`quote_plus()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.quote_plus) (см. выше). Если в качестве аргумента *query* передаётся последовательность двухэлементных кортежей, то первый элемент каждого кортежа – это ключ, а второй – значение. Само значение может быть последовательностью, и в этом случае, если необязательный параметр *doseq* принимает значение *True*, для каждого элемента последовательности значений данного ключа генерируются отдельные пары `key=value`, разделённые `'&'`. Порядок параметров в закодированной строке будет соответствовать порядку кортежей параметров в последовательности. Этот модуль предоставляет функции [`parse_qs()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.parse_qs) и [`parse_qsl()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.parse_qsl), которые используются для разбора строк запроса в структуры данных Python.236237Когда параметр *query* имеет тип [`str`](https://python-all.ru/3.1/library/functions.html#str), параметры *safe*, *encoding* и *error* передаются функции [`quote_plus()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.quote_plus) для кодирования.238239Изменено в версии 3.2: Параметр Query поддерживает объекты bytes и string.240241> **См. также**242>243> **[**RFC 3986**](https://python-all.ru/3.1/library/urllib.parse.html) – Uniform Resource Identifiers**244>245> Это текущий стандарт (STD66). Любые изменения в модуле urllib.parse должны ему соответствовать. Могут наблюдаться некоторые отклонения, которые в основном обусловлены обратной совместимостью и некоторыми фактическими требованиями парсинга, обычно встречающимися в основных браузерах.246>247> **[**RFC 2396**](https://python-all.ru/3.1/library/urllib.parse.html) – Uniform Resource Identifiers (URI): Generic Syntax**248>249> Документ, описывающий общие синтаксические требования как для Uniform Resource Names (URN), так и для Uniform Resource Locators (URL).250>251> **[**RFC 2368**](https://python-all.ru/3.1/library/urllib.parse.html) – Схема URL mailto.**252>253> Требования к разбору URL-схем ⟦mailto⟧.254>255> **[**RFC 1808**](https://python-all.ru/3.1/library/urllib.parse.html) – Relative Uniform Resource Locators**256>257> Этот документ (RFC) включает правила объединения абсолютного и относительного URL, включая значительное количество «Аномальных примеров», которые определяют обработку граничных случаев.258>259> **[**RFC 1738**](https://python-all.ru/3.1/library/urllib.parse.html) – Uniform Resource Locators (URL)**260>261> В нём описывается формальный синтаксис и семантика абсолютных URL.262263## 20.7.1. Результаты [`urlparse()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlparse) и [`urlsplit()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlsplit)264265Объекты-результаты функций [`urlparse()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlparse) и [`urlsplit()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlsplit) являются подклассами типа [`tuple`](https://python-all.ru/3.1/library/functions.html#tuple). Эти подклассы добавляют атрибуты, описанные в этих функциях, а также предоставляют дополнительный метод:266267#### `ParseResult.geturl()`268269Возвращает заново собранную версию исходного URL в виде строки. Она может отличаться от исходного URL тем, что схема всегда будет нормализована к нижнему регистру, а пустые компоненты могут быть отброшены. В частности, будут удалены пустые параметры, запросы и идентификаторы фрагментов.270271Результат этого метода является неподвижной точкой (fixpoint), если передать его обратно в исходную функцию разбора:272273> ```python274> >>> import urllib.parse275> >>> url = 'HTTP://www.Python.org/doc/#'276> ```277>278> ```python279> >>> r1 = urllib.parse.urlsplit(url)280> >>> r1.geturl()281> 'http://www.Python.org/doc/'282> ```283>284> ```python285> >>> r2 = urllib.parse.urlsplit(r1.geturl())286> >>> r2.geturl()287> 'http://www.Python.org/doc/'288> ```289290Следующие классы предоставляют реализацию результатов разбора:291292#### `class urllib.parse.BaseResult`293294Базовый класс для конкретных классов результатов. Он предоставляет большинство определений атрибутов. Он не предоставляет метод295296`geturl()`297298. Он является производным от299300[`tuple`](https://python-all.ru/3.1/library/functions.html#tuple)301302, но не переопределяет методы303304[`__init__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__init__)305306или307308[`__new__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__new__)309310.311312#### `class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)`313314Конкретный класс для результатов315316[`urlparse()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlparse)317318. Метод319320[`__new__()`](https://python-all.ru/3.1/reference/datamodel.html#object.__new__)321322переопределён для проверки правильности количества переданных аргументов.323324#### `class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)`325326Конкретный класс для результатов327328[`urlsplit()`](https://python-all.ru/3.1/library/urllib.parse.html#urllib.parse.urlsplit)329330. Метод331332[``](https://python-all.ru/3.1/reference/datamodel.html#object.__new__)333334\_\_new\_\_()335336переопределён для проверки правильности количества переданных аргументов.337