`urllib.parse.md`

362 строк · 27.0 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.0/library/urllib.parse.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `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]urllib.parse.urlparse(, urlstring[, default_scheme[, allow_fragments]])`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Если указан аргумент *default\_scheme*, он задаёт схему адресации по умолчанию, которая используется только если URL не указывает свою. Значение по умолчанию для этого аргумента – пустая строка.3435Если аргумент *allow\_fragments* равен false, идентификаторы фрагментов не допускаются, даже если схема адресации URL обычно их поддерживает. Значением по умолчанию для этого аргумента является [`True`](https://python-all.ru/3.0/library/constants.html#True).3637Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/3.0/library/functions.html#tuple). Этот класс имеет следующие дополнительные атрибуты только для чтения, предоставляющие удобный доступ:3839| Атрибут | Индекс | Значение | Значение, если отсутствует |40| --- | --- | --- | --- |41| `scheme` | 0 | Спецификатор схемы URL | пустая строка |42| `netloc` | 1 | Сетевое расположение | пустая строка |43| `path` | 2 | Иерархический путь | пустая строка |44| `params` | 3 | Параметры последнего элемента пути | пустая строка |45| `query` | 4 | Компонент запроса | пустая строка |46| `fragment` | 5 | Идентификатор фрагмента | пустая строка |47| `username` |  | Имя пользователя | [`None`](https://python-all.ru/3.0/library/constants.html#None) |48| `password` |  | Пароль | [`None`](https://python-all.ru/3.0/library/constants.html#None) |49| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/3.0/library/constants.html#None) |50| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/3.0/library/constants.html#None) |5152См. раздел [*Результаты urlparse() и urlsplit()*](https://python-all.ru/3.0/library/urllib.parse.html#urlparse-result-object) для получения дополнительной информации о результирующем объекте.5354#### `[urllib.parse.parse_qs]urllib.parse.parse_qs(qs[, keep_blank_values[, strict_parsing]])`5556Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде словаря. Ключами словаря являются уникальные имена переменных запроса, а значениями – списки значений для каждого имени.5758Необязательный аргумент *keep\_blank\_values* – флаг, указывающий, следует ли рассматривать пустые значения в URL-кодированных запросах как пустые строки. Значение true означает, что пустые значения сохраняются как пустые строки. Значение по умолчанию false означает, что пустые значения игнорируются и считаются не включёнными.5960Необязательный аргумент *strict\_parsing* – флаг, указывающий, что делать с ошибками разбора. Если false (по умолчанию), ошибки игнорируются. Если true, ошибки вызывают исключение [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError).6162Используйте функцию [`urllib.parse.urlencode()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlencode) для преобразования таких словарей в строки запроса.6364#### `[urllib.parse.parse_qsl]urllib.parse.parse_qsl(qs[, keep_blank_values[, strict_parsing]])`6566Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде списка пар имя, значение.6768Необязательный аргумент *keep\_blank\_values* – флаг, указывающий, следует ли рассматривать пустые значения в URL-кодированных запросах как пустые строки. Значение true означает, что пустые значения сохраняются как пустые строки. Значение по умолчанию false означает, что пустые значения игнорируются и считаются не включёнными.6970Необязательный аргумент *strict\_parsing* – флаг, указывающий, что делать с ошибками разбора. Если false (по умолчанию), ошибки игнорируются. Если true, ошибки вызывают исключение [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError).7172Используйте функцию [`urllib.parse.urlencode()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlencode) для преобразования таких списков пар в строки запроса.7374#### `[urllib.parse.urlunparse]urllib.parse.urlunparse(parts)`7576Создаёт URL из кортежа, возвращаемого функцией7778`urlparse()`7980. Аргумент8182*parts*8384может быть любым итерируемым объектом из шести элементов. Результат может немного отличаться от исходного, но быть эквивалентным URL, если исходный URL содержал лишние разделители (например,8586`?`8788с пустым запросом; RFC утверждает, что они эквивалентны).8990#### `[urllib.parse.urlsplit]urllib.parse.urlsplit(urlstring[, default_scheme[, allow_fragments]])`9192Эта функция похожа на [`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-кортеж: (схема адресации, сетевое расположение, путь, запрос, идентификатор фрагмента).9394Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/3.0/library/functions.html#tuple). Этот класс имеет следующие дополнительные атрибуты только для чтения, предоставляющие удобный доступ:9596| Атрибут | Индекс | Значение | Значение, если отсутствует |97| --- | --- | --- | --- |98| `scheme` | 0 | Спецификатор схемы URL | пустая строка |99| `netloc` | 1 | Сетевое расположение | пустая строка |100| `path` | 2 | Иерархический путь | пустая строка |101| `query` | 3 | Компонент запроса | пустая строка |102| `fragment` | 4 | Идентификатор фрагмента | пустая строка |103| `username` |  | Имя пользователя | [`None`](https://python-all.ru/3.0/library/constants.html#None) |104| `password` |  | Пароль | [`None`](https://python-all.ru/3.0/library/constants.html#None) |105| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/3.0/library/constants.html#None) |106| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/3.0/library/constants.html#None) |107108См. раздел [*Результаты urlparse() и urlsplit()*](https://python-all.ru/3.0/library/urllib.parse.html#urlparse-result-object) для получения дополнительной информации о результирующем объекте.109110#### `[urllib.parse.urlunsplit]urllib.parse.urlunsplit(parts)`111112Объединяет элементы кортежа, возвращаемого функцией113114[`urlsplit()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlsplit)115116, в полный URL в виде строки. Аргумент117118*parts*119120может быть любым итерируемым объектом из пяти элементов. Результат может немного отличаться, но быть эквивалентным, если исходный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны).121122#### `[urllib.parse.urljoin]urllib.parse.urljoin(base, url[, allow_fragments])`123124Строит полный («абсолютный») URL путём объединения «базового URL» (*base*) с другим URL (*url*). Неформально: используются компоненты базового URL, в частности схема адресации, сетевое расположение и (часть) пути, чтобы предоставить недостающие компоненты в относительном URL. Например:125126```python127>>> from urllib.parse import urljoin128>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')129'http://www.cwi.nl/%7Eguido/FAQ.html'130```131132Аргумент *allow\_fragments* имеет тот же смысл и значение по умолчанию, что и для [`urlparse()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlparse).133134> **Примечание**135>136> Если *url* является абсолютным URL (то есть начинается с `//` или `scheme://`), то имя хоста и/или схема *url* будут присутствовать в результате. Например:137138```python139>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',140...         '//www.python.org/%7Eguido')141'http://www.python.org/%7Eguido'142```143144Если такое поведение нежелательно, предварительно обработайте *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*.145146#### `[urllib.parse.urldefrag]urllib.parse.urldefrag(url)`147148Если149150*url*151152содержит идентификатор фрагмента, возвращает изменённую версию153154*url*155156без идентификатора фрагмента и сам идентификатор фрагмента в виде отдельной строки. Если в157158*url*159160нет идентификатора фрагмента, возвращает161162*url*163164без изменений и пустую строку.165166#### `[urllib.parse.quote]urllib.parse.quote(string[, safe[, encoding[, errors]]])`167168Заменяет специальные символы в строке *string* с помощью экранирования `%xx`. Буквы, цифры и символ `'_.-'` не квотируются. Необязательный параметр *safe* задаёт дополнительные ASCII-символы, которые не должны квотироваться – его значение по умолчанию – `'/'`.169170*string* может быть как строкой [`str`](https://python-all.ru/3.0/library/functions.html#str), так и объектом [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes).171172Необязательные параметры *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`.173174Обратите внимание, что `quote(string, safe, encoding, errors)` эквивалентно `quote_from_bytes(string.encode(encoding, errors), safe)`.175176Пример: `quote('/El Niño/')` возвращает `'/El%20Ni%C3%B1o/'`.177178#### `[urllib.parse.quote_plus]urllib.parse.quote_plus(string[, safe[, encoding[, errors]]])`179180Действует как [`quote()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.quote), но также заменяет пробелы на знаки плюс, как требуется для квотирования значений HTML-форм. Знаки плюс в исходной строке экранируются, если они не включены в *safe*. Кроме того, значение по умолчанию *safe* не равно `'/'`.181182Пример: `quote_plus('/El Niño/')` возвращает `'%2FEl+Ni%C3%B1o%2F'`.183184#### `[urllib.parse.quote_from_bytes]urllib.parse.quote_from_bytes(bytes[, safe])`185186Аналогична [`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) и не выполняет преобразование строки в байты.187188Пример: `quote_from_bytes(b'a&\xef')` возвращает `'a%26%EF'`.189190#### `[urllib.parse.unquote]urllib.parse.unquote(string[, encoding[, errors]])`191192Заменяет экранированные последовательности `%xx` на соответствующие им одиночные символы. Необязательные параметры *encoding* и *errors* задают способ декодирования процентно-кодированных последовательностей в символы Unicode, как это принято в методе `bytes.decode()`.193194*string* должен иметь тип [`str`](https://python-all.ru/3.0/library/functions.html#str).195196По умолчанию *encoding* равен `'utf-8'`. *errors* по умолчанию равен `'replace'`, то есть недопустимые последовательности заменяются на символ-заменитель.197198Пример: `unquote('/El%20Ni%C3%B1o/')` возвращает `'/El Niño/'`.199200#### `[urllib.parse.unquote_plus]urllib.parse.unquote_plus(string[, encoding[, errors]])`201202Аналогично [`unquote()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.unquote), но дополнительно заменяет знаки плюс пробелами, что требуется для декодирования значений HTML-форм.203204*string* должен иметь тип [`str`](https://python-all.ru/3.0/library/functions.html#str).205206Пример: `unquote_plus('/El+Ni%C3%B1o/')` возвращает `'/El Niño/'`.207208#### `[urllib.parse.unquote_to_bytes]urllib.parse.unquote_to_bytes(string)`209210Заменяет последовательности `%xx` на эквивалентный одиночный октет и возвращает объект [`байтов`](https://python-all.ru/3.0/library/functions.html#bytes).211212*string* может быть как строкой [`str`](https://python-all.ru/3.0/library/functions.html#str), так и объектом [`bytes`](https://python-all.ru/3.0/library/functions.html#bytes).213214Если это строка [`str`](https://python-all.ru/3.0/library/functions.html#str), то неэкранированные не-ASCII символы в *string* кодируются в байты UTF-8.215216Пример: `unquote_to_bytes('a%26%EF')` возвращает `b'a&\xef'`.217218#### `[urllib.parse.urlencode]urllib.parse.urlencode(query[, doseq])`219220Преобразует объект отображения (mapping) или последовательность кортежей из двух элементов в строку, закодированную в формате URL, подходящую для передачи в качестве необязательного аргумента221222*data*223224функции225226`urlopen()`227228выше. Это полезно для передачи словаря полей формы в запросе229230`POST`231232. Результирующая строка представляет собой серию пар233234`key=value`235236, разделённых символами237238`'&'`239240, причём как241242*key*243244, так и245246*value*247248квотируются с помощью249250[`quote_plus()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.quote_plus)251252выше. Если необязательный параметр253254*doseq*255256присутствует и принимает значение true, для каждого элемента последовательности генерируются отдельные пары257258`key=value`259260. Когда в качестве аргумента261262*query*263264используется последовательность кортежей из двух элементов, первый элемент каждого кортежа – это ключ, а второй – значение. Порядок параметров в закодированной строке будет соответствовать порядку кортежей параметров в последовательности. Этот модуль содержит функции265266[`parse_qs()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.parse_qs)267268и269270[`parse_qsl()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.parse_qsl)271272, которые используются для разбора строк запроса в структуры данных Python.273274> **См. также**275>276> **[**RFC 1738**](https://python-all.ru/3.0/library/urllib.parse.html) – Uniform Resource Locators (URL)**277>278> В нём описывается формальный синтаксис и семантика абсолютных URL.279>280> **[**RFC 1808**](https://python-all.ru/3.0/library/urllib.parse.html) – Relative Uniform Resource Locators**281>282> Этот документ (RFC) включает правила объединения абсолютного и относительного URL, включая значительное количество «Аномальных примеров», которые определяют обработку граничных случаев.283>284> **[**RFC 2396**](https://python-all.ru/3.0/library/urllib.parse.html) – Uniform Resource Identifiers (URI): Generic Syntax**285>286> Документ, описывающий общие синтаксические требования как для Uniform Resource Names (URN), так и для Uniform Resource Locators (URL).287288## Результаты [`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)289290Объекты-результаты функций [`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). Эти подклассы добавляют атрибуты, описанные в этих функциях, а также предоставляют дополнительный метод:291292#### `[urllib.parse.ParseResult.geturl]ParseResult.geturl()`293294Возвращает заново собранную версию исходного URL в виде строки. Она может отличаться от исходного URL тем, что схема всегда будет нормализована к нижнему регистру, а пустые компоненты могут быть отброшены. В частности, будут удалены пустые параметры, запросы и идентификаторы фрагментов.295296Результат этого метода является неподвижной точкой (fixpoint), если передать его обратно в исходную функцию разбора:297298> ```python299> >>> import urllib.parse300> >>> url = 'HTTP://www.Python.org/doc/#'301> ```302>303> ```python304> >>> r1 = urllib.parse.urlsplit(url)305> >>> r1.geturl()306> 'http://www.Python.org/doc/'307> ```308>309> ```python310> >>> r2 = urllib.parse.urlsplit(r1.geturl())311> >>> r2.geturl()312> 'http://www.Python.org/doc/'313> ```314315Следующие классы предоставляют реализацию результатов разбора:316317#### `[urllib.parse.BaseResult]class urllib.parse.BaseResult`318319Базовый класс для конкретных классов результатов. Он предоставляет большинство определений атрибутов. Он не предоставляет метод320321`geturl()`322323. Он является производным от324325[`tuple`](https://python-all.ru/3.0/library/functions.html#tuple)326327, но не переопределяет методы328329[`__init__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__init__)330331или332333[`__new__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__new__)334335.336337#### `[urllib.parse.ParseResult]class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)`338339Конкретный класс для результатов340341[`urlparse()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlparse)342343. Метод344345[`__new__()`](https://python-all.ru/3.0/reference/datamodel.html#object.__new__)346347переопределён для проверки правильности количества переданных аргументов.348349#### `[urllib.parse.SplitResult]class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)`350351Конкретный класс для результатов352353[`urlsplit()`](https://python-all.ru/3.0/library/urllib.parse.html#urllib.parse.urlsplit)354355. Метод356357[``](https://python-all.ru/3.0/reference/datamodel.html#object.__new__)358359\_\_new\_\_()360361переопределён для проверки правильности количества переданных аргументов.362