> **Источник:** https://python-all.ru/2.7/library/urlparse.html > > «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor. --- # 20.16. [`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) переименован в `urllib.parse` в Python 3. Инструмент [2to3](https://python-all.ru/2.7/glossary.html#term-2to3) автоматически адаптирует импорты при преобразовании исходных кодов в Python 3. **Исходный код:** [Lib/urlparse.py](https://python-all.ru/src/2.7/Lib/urlparse.py) --- Этот модуль предоставляет стандартный интерфейс для разбора строки URL на компоненты (схема адресации, сетевое расположение, путь и т.д.), обратной сборки компонентов в строку URL, а также для преобразования «относительного URL» в абсолютный по заданному «базовому URL». Модуль спроектирован в соответствии с 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`. Новое в версии 2.5: Поддержка схем `sftp` и `sips`. Модуль [`urlparse`](https://python-all.ru/2.7/library/urlparse.html#module-urlparse) определяет следующие функции: #### `urlparse.urlparse(urlstring[, scheme[, allow_fragments]])` Разбирает URL на шесть компонентов и возвращает кортеж из шести элементов. Это соответствует общей структуре URL: `scheme://netloc/path;parameters?query#fragment`. Каждый элемент кортежа – строка, возможно пустая. Компоненты не разбиваются на более мелкие части (например, сетевое расположение – это одна строка), а процентные экранирования не раскрываются. Разделители, показанные выше, не являются частью результата, за исключением начального слеша в компоненте *path*, который сохраняется, если присутствует. Например: ```python >>> from urlparse import urlparse >>> o = urlparse('http://www.cwi.nl:80/%7Eguido/Python.html') >>> o 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' ``` Следуя синтаксическим спецификациям [**RFC 1808**](https://python-all.ru/2.7/library/urlparse.html), urlparse распознаёт netloc только в том случае, если она правильно введена символами '//'. В противном случае считается, что входные данные – это относительный URL, и, следовательно, они начинаются с компонента пути. ```python >>> from urlparse import urlparse >>> urlparse('//www.cwi.nl:80/%7Eguido/Python.html') ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html', params='', query='', fragment='') >>> urlparse('www.cwi.nl/%7Eguido/Python.html') ParseResult(scheme='', netloc='', path='www.cwi.nl/%7Eguido/Python.html', params='', query='', fragment='') >>> urlparse('help/Python.html') ParseResult(scheme='', netloc='', path='help/Python.html', params='', query='', fragment='') ``` Если аргумент *scheme* указан, он задаёт схему адресации по умолчанию, которая используется только в том случае, если URL сам её не указывает. Значение по умолчанию для этого аргумента – пустая строка. Если аргумент *allow\_fragments* равен false, идентификаторы фрагментов не распознаются и разбираются как часть предыдущего компонента, даже если схема адресации URL обычно их поддерживает. Значение этого аргумента по умолчанию – [`True`](https://python-all.ru/2.7/library/constants.html#True). Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/2.7/library/functions.html#tuple). У этого класса есть следующие дополнительные атрибуты только для чтения: | Атрибут | Индекс | Значение | Значение, если отсутствует | | --- | --- | --- | --- | | `scheme` | 0 | Спецификатор схемы URL | Параметр *scheme* | | `netloc` | 1 | Сетевое расположение | пустая строка | | `path` | 2 | Иерархический путь | пустая строка | | `params` | 3 | Параметры последнего элемента пути | пустая строка | | `query` | 4 | Компонент запроса | пустая строка | | `fragment` | 5 | Идентификатор фрагмента | пустая строка | | `username` | | Имя пользователя | [`None`](https://python-all.ru/2.7/library/constants.html#None) | | `password` | | Пароль | [`None`](https://python-all.ru/2.7/library/constants.html#None) | | `hostname` | | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/2.7/library/constants.html#None) | | `port` | | Номер порта как целое число, если указан | [`None`](https://python-all.ru/2.7/library/constants.html#None) | См. раздел [Результаты urlparse() и urlsplit()](https://python-all.ru/2.7/library/urlparse.html#urlparse-result-object) для получения дополнительной информации о результирующем объекте. Символы в атрибуте `netloc`, которые при NFKC-нормализации (используемой в кодировке IDNA) разлагаются на любые из `/`, `?`, `#`, `@` или `:`, вызовут исключение [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). Если URL был разложен до разбора или не является строкой Unicode, ошибка не возникнет. Изменено в версии 2.5: Добавлены атрибуты возвращаемого значения. Изменено в версии 2.7: Добавлена возможность разбора URL с IPv6. Изменено в версии 2.7.17: Символы, влияющие на разбор netloc при NFKC-нормализации, теперь вызывают [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). #### `urlparse.parse_qs(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])` Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде словаря. Ключами словаря являются уникальные имена переменных запроса, а значениями – списки значений для каждого имени. Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение true означает, что пустые значения должны сохраняться как пустые строки. Значение false по умолчанию означает, что пустые значения игнорируются и считаются не включёнными. Необязательный аргумент *strict\_parsing* – это флаг, указывающий, что делать с ошибками разбора. Если False (по умолчанию), ошибки молча игнорируются. Если True, ошибки возбуждают исключение [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). Необязательный аргумент *max\_num\_fields* – это максимальное количество полей для чтения. Если он задан, то при чтении более *max\_num\_fields* полей возбуждается [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). Используйте функцию [`urllib.urlencode()`](https://python-all.ru/2.7/library/urllib.html#urllib.urlencode) для преобразования таких словарей в строки запроса. Новое в версии 2.6: Скопировано из модуля [`cgi`](https://python-all.ru/2.7/library/cgi.html#module-cgi). Изменено в версии 2.7.16: Добавлен параметр *max\_num\_fields*. #### `urlparse.parse_qsl(qs[, keep_blank_values[, strict_parsing[, max_num_fields]]])` Разбирает строку запроса, переданную в качестве строкового аргумента (данные типа *application/x-www-form-urlencoded*). Данные возвращаются в виде списка пар имя, значение. Необязательный аргумент *keep\_blank\_values* – это флаг, указывающий, следует ли обрабатывать пустые значения в процентно-кодированных запросах как пустые строки. Значение true означает, что пустые значения должны сохраняться как пустые строки. Значение false по умолчанию означает, что пустые значения игнорируются и считаются не включёнными. Необязательный аргумент *strict\_parsing* – это флаг, указывающий, что делать с ошибками разбора. Если False (по умолчанию), ошибки молча игнорируются. Если True, ошибки возбуждают исключение [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). Необязательный аргумент *max\_num\_fields* – это максимальное количество полей для чтения. Если он задан, то при чтении более *max\_num\_fields* полей возбуждается [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). Используйте функцию [`urllib.urlencode()`](https://python-all.ru/2.7/library/urllib.html#urllib.urlencode) для преобразования таких списков пар в строки запроса. Новое в версии 2.6: Скопировано из модуля [`cgi`](https://python-all.ru/2.7/library/cgi.html#module-cgi). Изменено в версии 2.7.16: Добавлен параметр *max\_num\_fields*. #### `urlparse.urlunparse(parts)` Собирает URL из кортежа, возвращаемого `urlparse()`. Аргумент *parts* может быть любым итерируемым объектом из шести элементов. Это может привести к незначительно отличающемуся, но эквивалентному URL, если исходный разобранный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны). #### `urlparse.urlsplit(urlstring[, scheme[, allow_fragments]])` Эта функция похожа на [`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)). Для разделения сегментов пути и параметров нужна отдельная функция. Эта функция возвращает кортеж из пяти элементов: (схема адресации, сетевое расположение, путь, запрос, идентификатор фрагмента). Возвращаемое значение на самом деле является экземпляром подкласса [`tuple`](https://python-all.ru/2.7/library/functions.html#tuple). У этого класса есть следующие дополнительные атрибуты только для чтения: | Атрибут | Индекс | Значение | Значение, если отсутствует | | --- | --- | --- | --- | | `scheme` | 0 | Спецификатор схемы URL | Параметр *scheme* | | `netloc` | 1 | Сетевое расположение | пустая строка | | `path` | 2 | Иерархический путь | пустая строка | | `query` | 3 | Компонент запроса | пустая строка | | `fragment` | 4 | Идентификатор фрагмента | пустая строка | | `username` | | Имя пользователя | [`None`](https://python-all.ru/2.7/library/constants.html#None) | | `password` | | Пароль | [`None`](https://python-all.ru/2.7/library/constants.html#None) | | `hostname` | | Имя хоста (в нижнем регистре) | [`None`](https://python-all.ru/2.7/library/constants.html#None) | | `port` | | Номер порта как целое число, если указан | [`None`](https://python-all.ru/2.7/library/constants.html#None) | См. раздел [Результаты urlparse() и urlsplit()](https://python-all.ru/2.7/library/urlparse.html#urlparse-result-object) для получения дополнительной информации о результирующем объекте. Символы в атрибуте `netloc`, которые при NFKC-нормализации (используемой в кодировке IDNA) разлагаются на любые из `/`, `?`, `#`, `@` или `:`, вызовут исключение [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). Если URL был разложен до разбора или не является строкой Unicode, ошибка не возникнет. Новое в версии 2.2. Изменено в версии 2.5: Добавлены атрибуты возвращаемого значения. Изменено в версии 2.7.17: Символы, влияющие на разбор netloc при NFKC-нормализации, теперь вызывают [`ValueError`](https://python-all.ru/2.7/library/exceptions.html#exceptions.ValueError). #### `urlparse.urlunsplit(parts)` Объединяет элементы кортежа, возвращаемого [`urlsplit()`](https://python-all.ru/2.7/library/urlparse.html#urlparse.urlsplit), в полный URL в виде строки. Аргумент *parts* может быть любым итерируемым объектом из пяти элементов. Это может привести к незначительно отличающемуся, но эквивалентному URL, если исходный разобранный URL содержал лишние разделители (например, ? с пустым запросом; RFC утверждает, что они эквивалентны). Новое в версии 2.2. #### `urlparse.urljoin(base, url[, allow_fragments])` Собирает полный («абсолютный») URL, объединяя «базовый URL» (*base*) с другим URL (*url*). Неформально говоря, используются компоненты базового URL, в частности схема адресации, сетевое расположение и (часть) пути, чтобы заполнить отсутствующие компоненты в относительном URL. Например: ```python >>> from urlparse 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/2.7/library/urlparse.html#module-urlparse). > **Примечание** > > Если *url* – абсолютный URL (то есть начинается с `//` или `scheme://`), то имя хоста и/или схема *url* будут присутствовать в результате. Например: ```pycon >>> urljoin('http://www.cwi.nl/%7Eguido/Python.html', ... '//www.python.org/%7Eguido') 'http://www.python.org/%7Eguido' ``` Если такое поведение нежелательно, предварительно обработайте *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*. #### `urlparse.urldefrag(url)` Если *url* содержит идентификатор фрагмента, возвращает изменённую версию *url* без идентификатора фрагмента, а сам идентификатор фрагмента – как отдельную строку. Если *url* не содержит идентификатора фрагмента, возвращает *url* без изменений и пустую строку. > **См. также** > > **[**RFC 3986**](https://python-all.ru/2.7/library/urlparse.html) – Uniform Resource Identifiers** > > Это текущий стандарт (STD66). Любые изменения модуля urlparse должны ему соответствовать. Могут наблюдаться некоторые отклонения, которые в основном обусловлены обратной совместимостью и определёнными фактическими требованиями к разбору, как это обычно принято в основных браузерах. > > **[**RFC 2732**](https://python-all.ru/2.7/library/urlparse.html) – Формат литеральных IPv6-адресов в URL.** > > В нём описываются требования к парсингу IPv6 URL. > > **[**RFC 2396**](https://python-all.ru/2.7/library/urlparse.html) – Uniform Resource Identifiers (URI): Generic Syntax** > > Документ, описывающий общие синтаксические требования как для Uniform Resource Names (URN), так и для Uniform Resource Locators (URL). > > **[**RFC 2368**](https://python-all.ru/2.7/library/urlparse.html) – Схема URL mailto.** > > Требования к парсингу схем URL mailto. > > **[**RFC 1808**](https://python-all.ru/2.7/library/urlparse.html) – Relative Uniform Resource Locators** > > Этот документ (RFC) включает правила объединения абсолютного и относительного URL, включая значительное количество «Аномальных примеров», которые определяют обработку граничных случаев. > > **[**RFC 1738**](https://python-all.ru/2.7/library/urlparse.html) – Uniform Resource Locators (URL)** > > В нём описывается формальный синтаксис и семантика абсолютных URL. ## 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) Объекты-результаты функций [`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). Эти подклассы добавляют атрибуты, описанные в этих функциях, а также предоставляют дополнительный метод: #### `ParseResult.geturl()` Возвращает заново собранную версию исходного URL в виде строки. Она может отличаться от исходного URL тем, что схема всегда будет нормализована к нижнему регистру, а пустые компоненты могут быть отброшены. В частности, будут удалены пустые параметры, запросы и идентификаторы фрагментов. Результат этого метода является неподвижной точкой (fixpoint), если передать его обратно в исходную функцию разбора: ```python >>> import urlparse >>> url = 'HTTP://www.Python.org/doc/#' ``` ```python >>> r1 = urlparse.urlsplit(url) >>> r1.geturl() 'http://www.Python.org/doc/' ``` ```python >>> r2 = urlparse.urlsplit(r1.geturl()) >>> r2.geturl() 'http://www.Python.org/doc/' ``` Новое в версии 2.5. Следующие классы предоставляют реализацию результатов разбора: #### `class urlparse.ParseResult(scheme, netloc, path, params, query, fragment)` Конкретный класс для результатов [`urlparse()`](https://python-all.ru/2.7/library/urlparse.html#module-urlparse). #### `class urlparse.SplitResult(scheme, netloc, path, query, fragment)` Конкретный класс для результатов [`urlsplit()`](https://python-all.ru/2.7/library/urlparse.html#urlparse.urlsplit).