> **Источник:** https://python-all.ru/3.0/library/urllib.parse.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

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

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

Модуль разработан в соответствии с 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`.

Модуль `urllib.parse` определяет следующие функции:

#### `[urllib.parse.urlparse]urllib.parse.urlparse(, urlstring[, default_scheme[, allow_fragments]])`

Разбирает URL на шесть компонентов и возвращает кортеж из шести элементов. Это соответствует общей структуре URL: `scheme://netloc/path;parameters?query#fragment`. Каждый элемент кортежа – строка, возможно пустая. Компоненты не разбиваются на более мелкие части (например, сетевое расположение – это одна строка), а %-последовательности не раскрываются. Разделители, показанные выше, не входят в результат, за исключением начальной косой черты в компоненте *path*, которая сохраняется, если присутствует. Например:

```python
>>> from urllib.parse import urlparse
>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')
>>> o   # doctest: +NORMALIZE_WHITESPACE
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> o.scheme
'http'
>>> o.port
80
>>> o.geturl()
'http://www.cwi.nl:80/%7Eguido/Python.html'
```

Если указан аргумент *default\_scheme*, он задаёт схему адресации по умолчанию, которая используется только если URL не указывает свою. Значение по умолчанию для этого аргумента – пустая строка.

Если аргумент *allow\_fragments* равен false, идентификаторы фрагментов не допускаются, даже если схема адресации URL обычно их поддерживает. Значением по умолчанию для этого аргумента является [`True`](https://python-all.ru/3.0/library/constants.html#True).

Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/3.0/library/functions.html#tuple). Этот класс имеет следующие дополнительные атрибуты только для чтения, предоставляющие удобный доступ:

| Атрибут | Индекс | Значение | Значение, если отсутствует |
| --- | --- | --- | --- |
| `scheme` | 0 | Спецификатор схемы URL | пустая строка |
| `netloc` | 1 | Сетевое расположение | пустая строка |
| `path` | 2 | Иерархический путь | пустая строка |
| `params` | 3 | Параметры последнего элемента пути | пустая строка |
| `query` | 4 | Компонент запроса | пустая строка |
| `fragment` | 5 | Идентификатор фрагмента | пустая строка |
| `username` |  | Имя пользователя | [`None`](https://python-all.ru/3.0/library/constants.html#None) |
| `password` |  | Пароль | [`None`](https://python-all.ru/3.0/library/constants.html#None) |
| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/3.0/library/constants.html#None) |
| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/3.0/library/constants.html#None) |

См. раздел [*Результаты urlparse() и urlsplit()*](https://python-all.ru/3.0/library/urllib.parse.html#urlparse-result-object) для получения дополнительной информации о результирующем объекте.

#### `[urllib.parse.parse_qs]urllib.parse.parse_qs(qs[, keep_blank_values[, strict_parsing]])`

Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде словаря. Ключами словаря являются уникальные имена переменных запроса, а значениями – списки значений для каждого имени.

Необязательный аргумент *keep\_blank\_values* – флаг, указывающий, следует ли рассматривать пустые значения в URL-кодированных запросах как пустые строки. Значение true означает, что пустые значения сохраняются как пустые строки. Значение по умолчанию false означает, что пустые значения игнорируются и считаются не включёнными.

Необязательный аргумент *strict\_parsing* – флаг, указывающий, что делать с ошибками разбора. Если false (по умолчанию), ошибки игнорируются. Если true, ошибки вызывают исключение [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError).

Используйте функцию [`urllib.parse.urlencode()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlencode) для преобразования таких словарей в строки запроса.

#### `[urllib.parse.parse_qsl]urllib.parse.parse_qsl(qs[, keep_blank_values[, strict_parsing]])`

Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде списка пар имя, значение.

Необязательный аргумент *keep\_blank\_values* – флаг, указывающий, следует ли рассматривать пустые значения в URL-кодированных запросах как пустые строки. Значение true означает, что пустые значения сохраняются как пустые строки. Значение по умолчанию false означает, что пустые значения игнорируются и считаются не включёнными.

Необязательный аргумент *strict\_parsing* – флаг, указывающий, что делать с ошибками разбора. Если false (по умолчанию), ошибки игнорируются. Если true, ошибки вызывают исключение [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError).

Используйте функцию [`urllib.parse.urlencode()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlencode) для преобразования таких списков пар в строки запроса.

#### `[urllib.parse.urlunparse]urllib.parse.urlunparse(parts)`

Создаёт URL из кортежа, возвращаемого функцией

`urlparse()`

. Аргумент

*parts*

может быть любым итерируемым объектом из шести элементов. Результат может немного отличаться от исходного, но быть эквивалентным URL, если исходный URL содержал лишние разделители (например,

`?`

с пустым запросом; RFC утверждает, что они эквивалентны).

#### `[urllib.parse.urlsplit]urllib.parse.urlsplit(urlstring[, default_scheme[, allow_fragments]])`

Эта функция похожа на [`urlparse()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlparse), но не отделяет параметры от URL. Как правило, её следует использовать вместо [`urlparse()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlparse), если требуется более новый синтаксис URL, допускающий применение параметров к каждому сегменту части *path* (см. [**RFC 2396**](https://python-all.ru/3.0/library/urllib.parse.html)). Для разделения сегментов пути и параметров нужна отдельная функция. Эта функция возвращает 5-кортеж: (схема адресации, сетевое расположение, путь, запрос, идентификатор фрагмента).

Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/3.0/library/functions.html#tuple). Этот класс имеет следующие дополнительные атрибуты только для чтения, предоставляющие удобный доступ:

| Атрибут | Индекс | Значение | Значение, если отсутствует |
| --- | --- | --- | --- |
| `scheme` | 0 | Спецификатор схемы URL | пустая строка |
| `netloc` | 1 | Сетевое расположение | пустая строка |
| `path` | 2 | Иерархический путь | пустая строка |
| `query` | 3 | Компонент запроса | пустая строка |
| `fragment` | 4 | Идентификатор фрагмента | пустая строка |
| `username` |  | Имя пользователя | [`None`](https://python-all.ru/3.0/library/constants.html#None) |
| `password` |  | Пароль | [`None`](https://python-all.ru/3.0/library/constants.html#None) |
| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/3.0/library/constants.html#None) |
| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/3.0/library/constants.html#None) |

См. раздел [*Результаты urlparse() и urlsplit()*](https://python-all.ru/3.0/library/urllib.parse.html#urlparse-result-object) для получения дополнительной информации о результирующем объекте.

#### `[urllib.parse.urlunsplit]urllib.parse.urlunsplit(parts)`

Объединяет элементы кортежа, возвращаемого функцией

[`urlsplit()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlsplit)

, в полный URL в виде строки. Аргумент

*parts*

может быть любым итерируемым объектом из пяти элементов. Результат может немного отличаться, но быть эквивалентным, если исходный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны).

#### `[urllib.parse.urljoin]urllib.parse.urljoin(base, url[, allow_fragments])`

Строит полный («абсолютный») URL путём объединения «базового URL» (*base*) с другим URL (*url*). Неформально: используются компоненты базового URL, в частности схема адресации, сетевое расположение и (часть) пути, чтобы предоставить недостающие компоненты в относительном URL. Например:

```python
>>> from urllib.parse import urljoin
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')
'http://www.cwi.nl/%7Eguido/FAQ.html'
```

Аргумент *allow\_fragments* имеет тот же смысл и значение по умолчанию, что и для [`urlparse()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlparse).

> **Примечание**
>
> Если *url* является абсолютным URL (то есть начинается с `//` или `scheme://`), то имя хоста и/или схема *url* будут присутствовать в результате. Например:

```python
>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',
...         '//www.python.org/%7Eguido')
'http://www.python.org/%7Eguido'
```

Если такое поведение нежелательно, предварительно обработайте *url* с помощью [`urlsplit()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlsplit) и [`urlunsplit()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlunsplit), удалив возможные части *scheme* и *netloc*.

#### `[urllib.parse.urldefrag]urllib.parse.urldefrag(url)`

Если

*url*

содержит идентификатор фрагмента, возвращает изменённую версию

*url*

без идентификатора фрагмента и сам идентификатор фрагмента в виде отдельной строки. Если в

*url*

нет идентификатора фрагмента, возвращает

*url*

без изменений и пустую строку.

#### `[urllib.parse.quote]urllib.parse.quote(string[, safe[, encoding[, errors]]])`

Заменяет специальные символы в строке *string* с помощью экранирования `%xx`. Буквы, цифры и символ `'_.-'` не квотируются. Необязательный параметр *safe* задаёт дополнительные ASCII-символы, которые не должны квотироваться – его значение по умолчанию – `'/'`.

*string* может быть как строкой [`str`](https://python-all.ru/3.0/library/functions.html#str), так и объектом [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes).

Необязательные параметры *encoding* и *errors* задают способ обработки не-ASCII символов, как это принято в методе [`str.encode()`](https://python-all.ru/3.0/library/stdtypes.html#str.encode). *encoding* по умолчанию равен `'utf-8'`. *errors* по умолчанию равен `'strict'`, то есть неподдерживаемые символы вызывают исключение `UnicodeEncodeError`. *encoding* и *errors* не должны указываться, если *string* является [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes), иначе будет вызвано `TypeError`.

Обратите внимание, что `quote(string, safe, encoding, errors)` эквивалентно `quote_from_bytes(string.encode(encoding, errors), safe)`.

Пример: `quote('/El Niño/')` возвращает `'/El%20Ni%C3%B1o/'`.

#### `[urllib.parse.quote_plus]urllib.parse.quote_plus(string[, safe[, encoding[, errors]]])`

Действует как [`quote()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.quote), но также заменяет пробелы на знаки плюс, как требуется для квотирования значений HTML-форм. Знаки плюс в исходной строке экранируются, если они не включены в *safe*. Кроме того, значение по умолчанию *safe* не равно `'/'`.

Пример: `quote_plus('/El Niño/')` возвращает `'%2FEl+Ni%C3%B1o%2F'`.

#### `[urllib.parse.quote_from_bytes]urllib.parse.quote_from_bytes(bytes[, safe])`

Аналогична [`quote()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.quote), но принимает объект [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes) вместо [`str`](https://python-all.ru/3.0/library/functions.html#str) и не выполняет преобразование строки в байты.

Пример: `quote_from_bytes(b'a&\xef')` возвращает `'a%26%EF'`.

#### `[urllib.parse.unquote]urllib.parse.unquote(string[, encoding[, errors]])`

Заменяет экранированные последовательности `%xx` на соответствующие им одиночные символы. Необязательные параметры *encoding* и *errors* задают способ декодирования процентно-кодированных последовательностей в символы Unicode, как это принято в методе `bytes.decode()`.

*string* должен иметь тип [`str`](https://python-all.ru/3.0/library/functions.html#str).

По умолчанию *encoding* равен `'utf-8'`. *errors* по умолчанию равен `'replace'`, то есть недопустимые последовательности заменяются на символ-заменитель.

Пример: `unquote('/El%20Ni%C3%B1o/')` возвращает `'/El Niño/'`.

#### `[urllib.parse.unquote_plus]urllib.parse.unquote_plus(string[, encoding[, errors]])`

Аналогично [`unquote()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.unquote), но дополнительно заменяет знаки плюс пробелами, что требуется для декодирования значений HTML-форм.

*string* должен иметь тип [`str`](https://python-all.ru/3.0/library/functions.html#str).

Пример: `unquote_plus('/El+Ni%C3%B1o/')` возвращает `'/El Niño/'`.

#### `[urllib.parse.unquote_to_bytes]urllib.parse.unquote_to_bytes(string)`

Заменяет последовательности `%xx` на эквивалентный одиночный октет и возвращает объект [`байтов`](https://python-all.ru/3.0/library/functions.html#bytes).

*string* может быть как строкой [`str`](https://python-all.ru/3.0/library/functions.html#str), так и объектом [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes).

Если это строка [`str`](https://python-all.ru/3.0/library/functions.html#str), то неэкранированные не-ASCII символы в *string* кодируются в байты UTF-8.

Пример: `unquote_to_bytes('a%26%EF')` возвращает `b'a&\xef'`.

#### `[urllib.parse.urlencode]urllib.parse.urlencode(query[, doseq])`

Преобразует объект отображения (mapping) или последовательность кортежей из двух элементов в строку, закодированную в формате URL, подходящую для передачи в качестве необязательного аргумента

*data*

функции

`urlopen()`

выше. Это полезно для передачи словаря полей формы в запросе

`POST`

. Результирующая строка представляет собой серию пар

`key=value`

, разделённых символами

`'&'`

, причём как

*key*

, так и

*value*

квотируются с помощью

[`quote_plus()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.quote_plus)

выше. Если необязательный параметр

*doseq*

присутствует и принимает значение true, для каждого элемента последовательности генерируются отдельные пары

`key=value`

. Когда в качестве аргумента

*query*

используется последовательность кортежей из двух элементов, первый элемент каждого кортежа – это ключ, а второй – значение. Порядок параметров в закодированной строке будет соответствовать порядку кортежей параметров в последовательности. Этот модуль содержит функции

[`parse_qs()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.parse_qs)

и

[`parse_qsl()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.parse_qsl)

, которые используются для разбора строк запроса в структуры данных Python.

> **См. также**
>
> **[**RFC 1738**](https://python-all.ru/3.0/library/urllib.parse.html) – Uniform Resource Locators (URL)**
>
> В нём описывается формальный синтаксис и семантика абсолютных URL.
>
> **[**RFC 1808**](https://python-all.ru/3.0/library/urllib.parse.html) – Relative Uniform Resource Locators**
>
> Этот документ (RFC) включает правила объединения абсолютного и относительного URL, включая значительное количество «Аномальных примеров», которые определяют обработку граничных случаев.
>
> **[**RFC 2396**](https://python-all.ru/3.0/library/urllib.parse.html) – Uniform Resource Identifiers (URI): Generic Syntax**
>
> Документ, описывающий общие синтаксические требования как для Uniform Resource Names (URN), так и для Uniform Resource Locators (URL).

## Результаты [`urlparse()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlparse) и [`urlsplit()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlsplit)

Объекты-результаты функций [`urlparse()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlparse) и [`urlsplit()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlsplit) являются подклассами типа [`tuple`](https://python-all.ru/3.0/library/functions.html#tuple). Эти подклассы добавляют атрибуты, описанные в этих функциях, а также предоставляют дополнительный метод:

#### `[urllib.parse.ParseResult.geturl]ParseResult.geturl()`

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

Результат этого метода является неподвижной точкой (fixpoint), если передать его обратно в исходную функцию разбора:

> ```python
> >>> import urllib.parse
> >>> url = 'HTTP://www.Python.org/doc/#'
> ```
>
> ```python
> >>> r1 = urllib.parse.urlsplit(url)
> >>> r1.geturl()
> 'http://www.Python.org/doc/'
> ```
>
> ```python
> >>> r2 = urllib.parse.urlsplit(r1.geturl())
> >>> r2.geturl()
> 'http://www.Python.org/doc/'
> ```

Следующие классы предоставляют реализацию результатов разбора:

#### `[urllib.parse.BaseResult]class urllib.parse.BaseResult`

Базовый класс для конкретных классов результатов. Он предоставляет большинство определений атрибутов. Он не предоставляет метод

`geturl()`

. Он является производным от

[`tuple`](https://python-all.ru/3.0/library/functions.html#tuple)

, но не переопределяет методы

[`__init__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__init__)

или

[`__new__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__new__)

.

#### `[urllib.parse.ParseResult]class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)`

Конкретный класс для результатов

[`urlparse()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlparse)

. Метод

[`__new__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__new__)

переопределён для проверки правильности количества переданных аргументов.

#### `[urllib.parse.SplitResult]class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)`

Конкретный класс для результатов

[`urlsplit()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlsplit)

. Метод

[``](https://python-all.ru/3.0/reference/datamodel.html#object.__new__)

\_\_new\_\_()

переопределён для проверки правильности количества переданных аргументов.