`urlparse.md`

249 строк · 23.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/2.7/library/urlparse.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 20.16. [`urlparse`](https://python-all.ru/2.7/library/urlparse.html#module-urlparse) – Разбор URL на составные части89> **Примечание**10>11> Модуль [`urlparse`](https://python-all.ru/2.7/library/urlparse.html#module-urlparse) переименован в `urllib.parse` в Python 3. Инструмент [2to3](https://python-all.ru/2.7/glossary.html#term-2to3) автоматически адаптирует импорты при преобразовании исходных кодов в Python 3.1213**Исходный код:** [Lib/urlparse.py](https://python-all.ru/src/2.7/Lib/urlparse.py)1415---1617Этот модуль предоставляет стандартный интерфейс для разбора строки URL на компоненты (схема адресации, сетевое расположение, путь и т.д.), обратной сборки компонентов в строку URL, а также для преобразования «относительного URL» в абсолютный по заданному «базовому URL».1819Модуль спроектирован в соответствии с RFC на относительные URL. Он поддерживает следующие схемы 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`.2021Новое в версии 2.5: Поддержка схем `sftp` и `sips`.2223Модуль [`urlparse`](https://python-all.ru/2.7/library/urlparse.html#module-urlparse) определяет следующие функции:2425#### `urlparse.urlparse(urlstring[, scheme[, allow_fragments]])`2627Разбирает URL на шесть компонентов и возвращает кортеж из шести элементов. Это соответствует общей структуре URL: `scheme://netloc/path;parameters?query#fragment`. Каждый элемент кортежа – строка, возможно пустая. Компоненты не разбиваются на более мелкие части (например, сетевое расположение – это одна строка), а процентные экранирования не раскрываются. Разделители, показанные выше, не являются частью результата, за исключением начального слеша в компоненте *path*, который сохраняется, если присутствует. Например:2829```python30>>> from urlparse import urlparse31>>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')32>>> o   33ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',34            params='', query='', fragment='')35>>> o.scheme36'http'37>>> o.port388039>>> o.geturl()40'http://www.cwi.nl:80/%7Eguido/Python.html'41```4243Следуя синтаксическим спецификациям [**RFC 1808**](https://python-all.ru/2.7/library/urlparse.html), urlparse распознаёт netloc только в том случае, если она правильно введена символами '//'. В противном случае считается, что входные данные – это относительный URL, и, следовательно, они начинаются с компонента пути.4445```python46>>> from urlparse import urlparse47>>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html')48ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',49           params='', query='', fragment='')50>>> urlparse('www.cwi.nl/%7Eguido/Python.html')51ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html',52           params='', query='', fragment='')53>>> urlparse('help/Python.html')54ParseResult(scheme='', netloc='', path='help/Python.html', params='',55           query='', fragment='')56```5758Если аргумент *scheme* указан, он задаёт схему адресации по умолчанию, которая используется только в том случае, если URL сам её не указывает. Значение по умолчанию для этого аргумента – пустая строка.5960Если аргумент *allow\_fragments* равен false, идентификаторы фрагментов не распознаются и разбираются как часть предыдущего компонента, даже если схема адресации URL обычно их поддерживает. Значение этого аргумента по умолчанию – [`True`](https://python-all.ru/2.7/library/constants.html#True).6162Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/2.7/library/functions.html#tuple). У этого класса есть следующие дополнительные атрибуты только для чтения:6364| Атрибут | Индекс | Значение | Значение, если отсутствует |65| --- | --- | --- | --- |66| `scheme` | 0 | Спецификатор схемы URL | Параметр *scheme* |67| `netloc` | 1 | Сетевое расположение | пустая строка |68| `path` | 2 | Иерархический путь | пустая строка |69| `params` | 3 | Параметры последнего элемента пути | пустая строка |70| `query` | 4 | Компонент запроса | пустая строка |71| `fragment` | 5 | Идентификатор фрагмента | пустая строка |72| `username` |  | Имя пользователя | [`None`](https://python-all.ru/2.7/library/constants.html#None) |73| `password` |  | Пароль | [`None`](https://python-all.ru/2.7/library/constants.html#None) |74| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/2.7/library/constants.html#None) |75| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/2.7/library/constants.html#None) |7677См. раздел [Результаты urlparse() и urlsplit()](https://python-all.ru/2.7/library/urlparse.html#urlparse-result-object) для получения дополнительной информации о результирующем объекте.7879Символы в атрибуте `netloc`, которые при NFKC-нормализации (используемой в кодировке IDNA) разлагаются на любые из `/`, `?`, `#`, `@` или `:`, вызовут исключение [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). Если URL был разложен до разбора или не является строкой Unicode, ошибка не возникнет.8081Изменено в версии 2.5: Добавлены атрибуты возвращаемого значения.8283Изменено в версии 2.7: Добавлена возможность разбора URL с IPv6.8485Изменено в версии 2.7.17: Символы, влияющие на разбор netloc при NFKC-нормализации, теперь вызывают [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).8687#### `urlparse.parse_qs(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])`8889Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде словаря. Ключами словаря являются уникальные имена переменных запроса, а значениями – списки значений для каждого имени.9091Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение true означает, что пустые значения должны сохраняться как пустые строки. Значение false по умолчанию означает, что пустые значения игнорируются и считаются не включёнными.9293Необязательный аргумент *strict\_parsing* – это флаг, указывающий, что делать с ошибками разбора. Если False (по умолчанию), ошибки молча игнорируются. Если True, ошибки возбуждают исключение [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).9495Необязательный аргумент *max\_num\_fields* – это максимальное количество полей для чтения. Если он задан, то при чтении более *max\_num\_fields* полей возбуждается [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).9697Используйте функцию [`urllib.urlencode()`](https://python-all.ru/2.7/library/urllib.html#urllib.urlencode) для преобразования таких словарей в строки запроса.9899Новое в версии 2.6: Скопировано из модуля [`cgi`](https://python-all.ru/2.7/library/cgi.html#module-cgi).100101Изменено в версии 2.7.16: Добавлен параметр *max\_num\_fields*.102103#### `urlparse.parse_qsl(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])`104105Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде списка пар имя, значение.106107Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение true означает, что пустые значения должны сохраняться как пустые строки. Значение false по умолчанию означает, что пустые значения игнорируются и считаются не включёнными.108109Необязательный аргумент *strict\_parsing* – это флаг, указывающий, что делать с ошибками разбора. Если False (по умолчанию), ошибки молча игнорируются. Если True, ошибки возбуждают исключение [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).110111Необязательный аргумент *max\_num\_fields* – это максимальное количество полей для чтения. Если он задан, то при чтении более *max\_num\_fields* полей возбуждается [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).112113Используйте функцию [`urllib.urlencode()`](https://python-all.ru/2.7/library/urllib.html#urllib.urlencode) для преобразования таких списков пар в строки запроса.114115Новое в версии 2.6: Скопировано из модуля [`cgi`](https://python-all.ru/2.7/library/cgi.html#module-cgi).116117Изменено в версии 2.7.16: Добавлен параметр *max\_num\_fields*.118119#### `urlparse.urlunparse(parts)`120121Собирает URL из кортежа, возвращаемого `urlparse()`. Аргумент *parts* может быть любым итерируемым объектом из шести элементов. Это может привести к незначительно отличающемуся, но эквивалентному URL, если исходный разобранный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны).122123#### `urlparse.urlsplit(urlstring[, scheme[, allow_fragments]])`124125Эта функция похожа на [`urlparse()`](https://python-all.ru/2.7/library/urlparse.html#module-urlparse), но не отделяет параметры от URL. Её следует использовать вместо [`urlparse()`](https://python-all.ru/2.7/library/urlparse.html#module-urlparse), если требуется более современный синтаксис URL, позволяющий применять параметры к каждому сегменту части *path* URL (см. [**RFC 2396**](https://python-all.ru/2.7/library/urlparse.html)). Для разделения сегментов пути и параметров нужна отдельная функция. Эта функция возвращает кортеж из пяти элементов: (схема адресации, сетевое расположение, путь, запрос, идентификатор фрагмента).126127Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/2.7/library/functions.html#tuple). У этого класса есть следующие дополнительные атрибуты только для чтения:128129| Атрибут | Индекс | Значение | Значение, если отсутствует |130| --- | --- | --- | --- |131| `scheme` | 0 | Спецификатор схемы URL | Параметр *scheme* |132| `netloc` | 1 | Сетевое расположение | пустая строка |133| `path` | 2 | Иерархический путь | пустая строка |134| `query` | 3 | Компонент запроса | пустая строка |135| `fragment` | 4 | Идентификатор фрагмента | пустая строка |136| `username` |  | Имя пользователя | [`None`](https://python-all.ru/2.7/library/constants.html#None) |137| `password` |  | Пароль | [`None`](https://python-all.ru/2.7/library/constants.html#None) |138| `hostname` |  | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/2.7/library/constants.html#None) |139| `port` |  | Номер порта как целое число, если указан | [`None`](https://python-all.ru/2.7/library/constants.html#None) |140141См. раздел [Результаты urlparse() и urlsplit()](https://python-all.ru/2.7/library/urlparse.html#urlparse-result-object) для получения дополнительной информации о результирующем объекте.142143Символы в атрибуте `netloc`, которые при NFKC-нормализации (используемой в кодировке IDNA) разлагаются на любые из `/`, `?`, `#`, `@` или `:`, вызовут исключение [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). Если URL был разложен до разбора или не является строкой Unicode, ошибка не возникнет.144145Новое в версии 2.2.146147Изменено в версии 2.5: Добавлены атрибуты возвращаемого значения.148149Изменено в версии 2.7.17: Символы, влияющие на разбор netloc при NFKC-нормализации, теперь вызывают [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError).150151#### `urlparse.urlunsplit(parts)`152153Объединяет элементы кортежа, возвращаемого [`urlsplit()`](https://python-all.ru/2.7/library/urlparse.html#urlparse.urlsplit), в полный URL в виде строки. Аргумент *parts* может быть любым итерируемым объектом из пяти элементов. Это может привести к незначительно отличающемуся, но эквивалентному URL, если исходный разобранный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны).154155Новое в версии 2.2.156157#### `urlparse.urljoin(base, url[, allow_fragments])`158159Собирает полный («абсолютный») URL, объединяя «базовый URL» (*base*) с другим URL (*url*). Неформально говоря, используются компоненты базового URL, в частности схема адресации, сетевое расположение и (часть) пути, чтобы заполнить отсутствующие компоненты в относительном URL. Например:160161```python162>>> from urlparse import urljoin163>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')164'http://www.cwi.nl/%7Eguido/FAQ.html'165```166167Аргумент *allow\_fragments* имеет то же значение и значение по умолчанию, что и для [`urlparse()`](https://python-all.ru/2.7/library/urlparse.html#module-urlparse).168169> **Примечание**170>171> Если *url* – абсолютный URL (то есть начинается с `//` или `scheme://`), то имя хоста и/или схема *url* будут присутствовать в результате. Например:172173```pycon174>>> urljoin('http://www.cwi.nl/%7Eguido/Python.html',175...         '//www.python.org/%7Eguido')176'http://www.python.org/%7Eguido'177```178179Если такое поведение нежелательно, предварительно обработайте *url* с помощью [`urlsplit()`](https://python-all.ru/2.7/library/urlparse.html#urlparse.urlsplit) и [`urlunsplit()`](https://python-all.ru/2.7/library/urlparse.html#urlparse.urlunsplit), удалив возможные части *scheme* и *netloc*.180181#### `urlparse.urldefrag(url)`182183Если *url* содержит идентификатор фрагмента, возвращает изменённую версию *url* без идентификатора фрагмента, а сам идентификатор фрагмента – как отдельную строку. Если *url* не содержит идентификатора фрагмента, возвращает *url* без изменений и пустую строку.184185> **См. также**186>187> **[**RFC 3986**](https://python-all.ru/2.7/library/urlparse.html) – Uniform Resource Identifiers**188>189> Это текущий стандарт (STD66). Любые изменения модуля urlparse должны ему соответствовать. Могут наблюдаться некоторые отклонения, которые в основном обусловлены обратной совместимостью и определёнными фактическими требованиями к разбору, как это обычно принято в основных браузерах.190>191> **[**RFC 2732**](https://python-all.ru/2.7/library/urlparse.html) – Формат литеральных IPv6-адресов в URL.**192>193> В нём описываются требования к парсингу IPv6 URL.194>195> **[**RFC 2396**](https://python-all.ru/2.7/library/urlparse.html) – Uniform Resource Identifiers (URI): Generic Syntax**196>197> Документ, описывающий общие синтаксические требования как для Uniform Resource Names (URN), так и для Uniform Resource Locators (URL).198>199> **[**RFC 2368**](https://python-all.ru/2.7/library/urlparse.html) – Схема URL mailto.**200>201> Требования к парсингу схем URL mailto.202>203> **[**RFC 1808**](https://python-all.ru/2.7/library/urlparse.html) – Relative Uniform Resource Locators**204>205> Этот документ (RFC) включает правила объединения абсолютного и относительного URL, включая значительное количество «Аномальных примеров», которые определяют обработку граничных случаев.206>207> **[**RFC 1738**](https://python-all.ru/2.7/library/urlparse.html) – Uniform Resource Locators (URL)**208>209> В нём описывается формальный синтаксис и семантика абсолютных URL.210211## 20.16.1. Результаты [`urlparse()`](https://python-all.ru/2.7/library/urlparse.html#module-urlparse) и [`urlsplit()`](https://python-all.ru/2.7/library/urlparse.html#urlparse.urlsplit)212213Объекты-результаты функций [`urlparse()`](https://python-all.ru/2.7/library/urlparse.html#module-urlparse) и [`urlsplit()`](https://python-all.ru/2.7/library/urlparse.html#urlparse.urlsplit) являются подклассами типа [`tuple`](https://python-all.ru/2.7/library/functions.html#tuple). Эти подклассы добавляют атрибуты, описанные в этих функциях, а также предоставляют дополнительный метод:214215#### `ParseResult.geturl()`216217Возвращает заново собранную версию исходного URL в виде строки. Она может отличаться от исходного URL тем, что схема всегда будет нормализована к нижнему регистру, а пустые компоненты могут быть отброшены. В частности, будут удалены пустые параметры, запросы и идентификаторы фрагментов.218219Результат этого метода является неподвижной точкой (fixpoint), если передать его обратно в исходную функцию разбора:220221```python222>>> import urlparse223>>> url = 'HTTP://www.Python.org/doc/#'224```225226```python227>>> r1 = urlparse.urlsplit(url)228>>> r1.geturl()229'http://www.Python.org/doc/'230```231232```python233>>> r2 = urlparse.urlsplit(r1.geturl())234>>> r2.geturl()235'http://www.Python.org/doc/'236```237238Новое в версии 2.5.239240Следующие классы предоставляют реализацию результатов разбора:241242#### `class urlparse.ParseResult(scheme, netloc, path, params, query, fragment)`243244Конкретный класс для результатов [`urlparse()`](https://python-all.ru/2.7/library/urlparse.html#module-urlparse).245246#### `class urlparse.SplitResult(scheme, netloc, path, query, fragment)`247248Конкретный класс для результатов [`urlsplit()`](https://python-all.ru/2.7/library/urlparse.html#urlparse.urlsplit).249