urllib.parse — Parse URLs into components

Вихідний код: Lib/urllib/parse.py

---

Цей модуль визначає стандартний інтерфейс для розбиття рядків Uniform Resource Locator (URL) на компоненти (схема адресації, мережеве розташування, шлях тощо), щоб об’єднати компоненти назад у рядок URL-адреси та перетворити «відносну URL-адресу» на абсолютна URL-адреса з «базовою URL-адресою».

The module has been designed to match the internet RFC on Relative Uniform Resource Locators. It supports the following URL schemes: file, ftp, gopher, hdl, http, https, imap, itms-services, mailto, mms, news, nntp, prospero, rsync, rtsp, rtsps, rtspu, sftp, shttp, sip, sips, snews, svn, svn+ssh, telnet, wais, ws, wss.

Деталі реалізації CPython: The inclusion of the itms-services URL scheme can prevent an app from passing Apple’s App Store review process for the macOS and iOS App Stores. Handling for the itms-services scheme is always removed on iOS; on macOS, it may be removed if CPython has been built with the --with-app-store-compliance option.

Модуль urllib.parse визначає функції, які поділяються на дві широкі категорії: аналіз URL-адреси та цитування URL-адреси. Вони детально описані в наступних розділах.

This module’s functions use the deprecated term netloc (or net_loc), which was introduced in RFC 1808. However, this term has been obsoleted by RFC 3986, which introduced the term authority as its replacement. The use of netloc is continued for backward compatibility.

Розбір URL-адрес

Функції аналізу URL-адреси зосереджені на розділенні рядка URL-адреси на його компоненти або на об’єднанні компонентів URL-адреси в рядок URL-адреси.

urllib.parse.urlparse(urlstring, scheme=None, allow_fragments=True, *, missing_as_none=False)

Parse a URL into six components, returning a 6-item named tuple. This corresponds to the general structure of a URL: scheme://netloc/path;parameters?query#fragment. Each tuple item is a string, possibly empty, or None if missing_as_none is true. Not defined component are represented an empty string (by default) or None if missing_as_none is true. The components are not broken up into smaller parts (for example, the network location is a single string), and % escapes are not expanded. The delimiters as shown above are not part of the result, except for a leading slash in the path component, which is retained if present. For example:

>>> from urllib.parse import urlparse
>>> urlparse("scheme://netloc/path;parameters?query#fragment")
ParseResult(scheme='scheme', netloc='netloc', path='/path;parameters', params='',
            query='query', fragment='fragment')
>>> o = urlparse("http://docs.python.org:80/3/library/urllib.parse.html?"
...              "highlight=params#url-parsing")
>>> o
ParseResult(scheme='http', netloc='docs.python.org:80',
            path='/3/library/urllib.parse.html', params='',
            query='highlight=params', fragment='url-parsing')
>>> o.scheme
'http'
>>> o.netloc
'docs.python.org:80'
>>> o.hostname
'docs.python.org'
>>> o.port
80
>>> o._replace(fragment="").geturl()
'http://docs.python.org:80/3/library/urllib.parse.html?highlight=params'
>>> urlparse("http://docs.python.org?")
ParseResult(scheme='http', netloc='docs.python.org',
            path='', params='', query='', fragment='')
>>> urlparse("http://docs.python.org?", missing_as_none=True)
ParseResult(scheme='http', netloc='docs.python.org',
            path='', params=None, query='', fragment=None)

Дотримуючись специфікації синтаксису в RFC 1808, urlparse розпізнає netloc, лише якщо його правильно введено „//“. Інакше введення вважається відносною URL-адресою і, таким чином, починається з компонента шляху.

>>> from urllib.parse 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='')
>>> urlparse('help/Python.html', missing_as_none=True)
ParseResult(scheme=None, netloc=None, path='help/Python.html',
            params=None, query=None, fragment=None)

The scheme argument gives the default addressing scheme, to be used only if the URL does not specify one. It should be the same type (text or bytes) as urlstring or None, except that the '' is always allowed, and is automatically converted to b'' if appropriate.

If the allow_fragments argument is false, fragment identifiers are not recognized. Instead, they are parsed as part of the path, parameters or query component, and fragment is set to None or the empty string (depending on the value of missing_as_none) in the return value.

Поверненим значенням є named tuple, що означає, що до його елементів можна отримати доступ за індексом або як іменовані атрибути, які:

Атрибут	Індекс	Значення	Значення, якщо його немає
scheme	0	Специфікатор схеми URL	scheme parameter or empty string [1]
netloc	1	Розташування мережі	None or empty string [1]
path	2	Ієрархічний шлях	порожній рядок
params	3	Parameters for last path element	None or empty string [1]
query	4	Компонент запиту	None or empty string [1]
fragment	5	Ідентифікатор фрагмента	None or empty string [1]
ім’я користувача		Ім’я користувача	None
password		Пароль	None
ім'я хоста		Ім’я хоста (нижній регістр)	None
port		Номер порту як ціле число, якщо є	None

[1] (1,2,3,4,5,6)

Depending on the value of the missing_as_none argument.

Читання атрибута port викличе ValueError, якщо в URL-адресі вказано недійсний порт. Перегляньте розділ Структуровані результати аналізу для отримання додаткової інформації про об’єкт результату.

Невідповідні квадратні дужки в атрибуті netloc викличуть ValueError.

Символи в атрибуті netloc, які розкладаються за нормалізацією NFKC (як використовується кодуванням IDNA) на будь-який із /, ?, #, @, або : викличе ValueError. Якщо перед синтаксичним аналізом URL-адресу розкладають, помилка не виникне.

Як і у випадку з усіма іменованими кортежами, підклас має кілька додаткових методів і атрибутів, які є особливо корисними. Одним із таких методів є _replace(). Метод _replace() поверне новий об’єкт ParseResult, замінюючи вказані поля новими значеннями.

>>> from urllib.parse import urlparse
>>> u = urlparse('//www.cwi.nl:80/%7Eguido/Python.html')
>>> u
ParseResult(scheme='', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')
>>> u._replace(scheme='http')
ParseResult(scheme='http', netloc='www.cwi.nl:80', path='/%7Eguido/Python.html',
            params='', query='', fragment='')

Попередження

urlparse() does not perform validation. See URL parsing security for details.

Змінено в версії 3.2: Додано можливості розбору URL-адрес IPv6.

Змінено в версії 3.3: The fragment is now parsed for all URL schemes (unless allow_fragments is false), in accordance with RFC 3986. Previously, an allowlist of schemes that support fragments existed.

Змінено в версії 3.6: Out-of-range port numbers now raise ValueError, instead of returning None.

Змінено в версії 3.8: Символи, які впливають на аналіз netloc під час нормалізації NFKC, тепер викликатимуть ValueError.

Змінено в версії 3.15.0a5 (unreleased): Added the missing_as_none parameter.

urllib.parse.parse_qs(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

Проаналізуйте рядок запиту, заданий як аргумент рядка (дані типу application/x-www-form-urlencoded). Дані повертаються як словник. Ключі словника — це унікальні імена змінних запиту, а значення — це списки значень для кожного імені.

Необов’язковий аргумент keep_blank_values — це позначка, яка вказує, чи слід порожні значення в запитах із відсотковим кодуванням розглядати як порожні рядки. Справжнє значення вказує на те, що пробіли слід зберігати як порожні рядки. Значення false за замовчуванням вказує на те, що порожні значення слід ігнорувати та розглядати їх так, ніби їх не було включено.

Необов’язковий аргумент strict_parsing — це позначка, яка вказує, що робити з помилками аналізу. Якщо false (за замовчуванням), помилки мовчки ігноруються. Якщо true, помилки викликають виняток ValueError.

Необов’язкові параметри encoding і errors визначають, як декодувати послідовності, закодовані у відсотках, у символи Юнікоду, як це прийнято методом bytes.decode().

Необов’язковий аргумент max_num_fields — це максимальна кількість полів для читання. Якщо встановлено, викидає ValueError, якщо прочитано більше ніж max_num_fields полів.

Необов’язковий аргумент роздільник — це символ, який використовується для розділення аргументів запиту. За замовчуванням &.

Використовуйте функцію urllib.parse.urlencode() (з параметром doseq, встановленим на True), щоб конвертувати такі словники в рядки запиту.

Змінено в версії 3.2: Додайте параметри encoding і errors.

Змінено в версії 3.8: Додано параметр max_num_fields.

Змінено в версії 3.10: Додано параметр роздільник зі значенням за замовчуванням &. Версії Python, раніші за Python 3.10, дозволяли використовувати як ;, так і & як роздільник параметрів запиту. Це було змінено, щоб дозволити лише один роздільний ключ із & як роздільником за умовчанням.

Застаріло починаючи з версії 3.14: Accepting objects with false values (like 0 and []) except empty strings and byte-like objects and None is now deprecated.

urllib.parse.parse_qsl(qs, keep_blank_values=False, strict_parsing=False, encoding='utf-8', errors='replace', max_num_fields=None, separator='&')

Проаналізуйте рядок запиту, заданий як аргумент рядка (дані типу application/x-www-form-urlencoded). Дані повертаються у вигляді списку пар імені та значення.

Необов’язковий аргумент keep_blank_values — це позначка, яка вказує, чи слід порожні значення в запитах із відсотковим кодуванням розглядати як порожні рядки. Справжнє значення вказує на те, що пробіли слід зберігати як порожні рядки. Значення false за замовчуванням вказує на те, що порожні значення слід ігнорувати та розглядати їх так, ніби їх не було включено.

Необов’язковий аргумент strict_parsing — це позначка, яка вказує, що робити з помилками аналізу. Якщо false (за замовчуванням), помилки мовчки ігноруються. Якщо true, помилки викликають виняток ValueError.

Необов’язкові параметри encoding і errors визначають, як декодувати послідовності, закодовані у відсотках, у символи Юнікоду, як це прийнято методом bytes.decode().

Необов’язковий аргумент max_num_fields — це максимальна кількість полів для читання. Якщо встановлено, викидає ValueError, якщо прочитано більше ніж max_num_fields полів.

Необов’язковий аргумент роздільник — це символ, який використовується для розділення аргументів запиту. За замовчуванням &.

Використовуйте функцію urllib.parse.urlencode(), щоб перетворити такі списки пар у рядки запиту.

Змінено в версії 3.2: Додайте параметри encoding і errors.

Змінено в версії 3.8: Додано параметр max_num_fields.

Змінено в версії 3.10: Додано параметр роздільник зі значенням за замовчуванням &. Версії Python, раніші за Python 3.10, дозволяли використовувати як ;, так і & як роздільник параметрів запиту. Це було змінено, щоб дозволити лише один роздільний ключ із & як роздільником за умовчанням.

urllib.parse.urlunparse(parts)

urllib.parse.urlunparse(parts, *, keep_empty)

Construct a URL from a tuple as returned by urlparse(). The parts argument can be any six-item iterable.

This may result in a slightly different, but equivalent URL, if the URL that was parsed originally had unnecessary delimiters (for example, a ? with an empty query; the RFC states that these are equivalent).

If keep_empty is true, empty strings are kept in the result (for example, a ? for an empty query), only None components are omitted. This allows rebuilding a URL that was parsed with option missing_as_none=True. By default, keep_empty is true if parts is the result of the urlparse() call with missing_as_none=True.

Змінено в версії 3.15.0a5 (unreleased): Added the keep_empty parameter.

urllib.parse.urlsplit(urlstring, scheme=None, allow_fragments=True, *, missing_as_none=False)

Це схоже на urlparse(), але не відокремлює параметри від URL-адреси. Загалом це слід використовувати замість urlparse(), якщо потрібний новіший синтаксис URL-адреси, який дозволяє застосовувати параметри до кожного сегменту частини path URL-адреси (див. RFC 2396). Для розділення сегментів шляху та параметрів потрібна окрема функція. Ця функція повертає 5-елементний named tuple:

(addressing scheme, network location, path, query, fragment identifier).

Поверненим значенням є named tuple, до його елементів можна отримати доступ за індексом або як іменовані атрибути:

Атрибут	Індекс	Значення	Значення, якщо його немає
scheme	0	Специфікатор схеми URL	scheme parameter or empty string [1]
netloc	1	Розташування мережі	None or empty string [2]
path	2	Ієрархічний шлях	порожній рядок
query	3	Компонент запиту	None or empty string [2]
fragment	4	Ідентифікатор фрагмента	None or empty string [2]
ім’я користувача		Ім’я користувача	None
password		Пароль	None
ім'я хоста		Ім’я хоста (нижній регістр)	None
port		Номер порту як ціле число, якщо є	None

[2] (1,2,3)

Depending on the value of the missing_as_none argument.

Читання атрибута port викличе ValueError, якщо в URL-адресі вказано недійсний порт. Перегляньте розділ Структуровані результати аналізу для отримання додаткової інформації про об’єкт результату.

Невідповідні квадратні дужки в атрибуті netloc викличуть ValueError.

Символи в атрибуті netloc, які розкладаються за нормалізацією NFKC (як використовується кодуванням IDNA) на будь-який із /, ?, #, @, або : викличе ValueError. Якщо перед синтаксичним аналізом URL-адресу розкладають, помилка не виникне.

Following some of the WHATWG spec that updates RFC 3986, leading C0 control and space characters are stripped from the URL. \n, \r and tab \t characters are removed from the URL at any position.

Попередження

urlsplit() does not perform validation. See URL parsing security for details.

Змінено в версії 3.6: Out-of-range port numbers now raise ValueError, instead of returning None.

Змінено в версії 3.8: Символи, які впливають на аналіз netloc під час нормалізації NFKC, тепер викликатимуть ValueError.

Змінено в версії 3.10: Символи нового рядка та табуляції ASCII видаляються з URL-адреси.

Змінено в версії 3.12: Leading WHATWG C0 control and space characters are stripped from the URL.

Змінено в версії 3.15.0a5 (unreleased): Added the missing_as_none parameter.

urllib.parse.urlunsplit(parts)

urllib.parse.urlunsplit(parts, *, keep_empty)

Combine the elements of a tuple as returned by urlsplit() into a complete URL as a string. The parts argument can be any five-item iterable.

This may result in a slightly different, but equivalent URL, if the URL that was parsed originally had unnecessary delimiters (for example, a ? with an empty query; the RFC states that these are equivalent).

If keep_empty is true, empty strings are kept in the result (for example, a ? for an empty query), only None components are omitted. This allows rebuilding a URL that was parsed with option missing_as_none=True. By default, keep_empty is true if parts is the result of the urlsplit() call with missing_as_none=True.

Змінено в версії 3.15.0a5 (unreleased): Added the keep_empty parameter.

urllib.parse.urljoin(base, url, allow_fragments=True)

Створіть повну («абсолютну») URL-адресу, об’єднавши «базову URL-адресу» (base) з іншою URL-адресою (url). Неофіційно тут використовуються компоненти базової URL-адреси, зокрема схема адресації, мережеве розташування та (частина) шляху, щоб забезпечити відсутні компоненти у відносній URL-адресі. Наприклад:

>>> 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().

Примітка

Якщо url є абсолютною URL-адресою (тобто вона починається з // або scheme://), ім’я хосту url та/або схема будуть присутні в результаті. Наприклад:

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

Якщо ви не хочете такої поведінки, попередньо обробіть url за допомогою urlsplit() і urlunsplit(), видаливши можливі частини scheme і netloc.

Попередження

Because an absolute URL may be passed as the url parameter, it is generally not secure to use urljoin with an attacker-controlled url. For example in, urljoin("https://website.com/users/", username), if username can contain an absolute URL, the result of urljoin will be the absolute URL.

Змінено в версії 3.5: Поведінку оновлено відповідно до семантики, визначеної в RFC 3986.

urllib.parse.urldefrag(url, *, missing_as_none=False)

If url contains a fragment identifier, return a modified version of url with no fragment identifier, and the fragment identifier as a separate string. If there is no fragment identifier in url, return url unmodified and an empty string (by default) or None if missing_as_none is true.

Поверненим значенням є named tuple, до його елементів можна отримати доступ за індексом або як іменовані атрибути:

Атрибут	Індекс	Значення	Значення, якщо його немає
url	0	URL без фрагмента	порожній рядок
fragment	1	Ідентифікатор фрагмента	None or empty string [3]

[3]

Depending on the value of the missing_as_none argument.

Перегляньте розділ Структуровані результати аналізу для отримання додаткової інформації про об’єкт результату.

Змінено в версії 3.2: Результат – це структурований об’єкт, а не простий 2-кортеж.

Змінено в версії 3.15.0a5 (unreleased): Added the missing_as_none parameter.

urllib.parse.unwrap(url)

Витягніть URL-адресу з упакованої URL-адреси (тобто рядка у форматі <URL:scheme://host/path>, <scheme://host/path>, URL:scheme://host/path або scheme://host/path). Якщо url не є загорнутою URL-адресою, вона повертається без змін.

URL parsing security

The urlsplit() and urlparse() APIs do not perform validation of inputs. They may not raise errors on inputs that other applications consider invalid. They may also succeed on some inputs that might not be considered URLs elsewhere. Their purpose is for practical functionality rather than purity.

Instead of raising an exception on unusual input, they may instead return some component parts as empty strings or None (depending on the value of the missing_as_none argument). Or components may contain more than perhaps they should.

We recommend that users of these APIs where the values may be used anywhere with security implications code defensively. Do some verification within your code before trusting a returned component part. Does that scheme make sense? Is that a sensible path? Is there anything strange about that hostname? etc.

What constitutes a URL is not universally well defined. Different applications have different needs and desired constraints. For instance the living WHATWG spec describes what user facing web clients such as a web browser require. While RFC 3986 is more general. These functions incorporate some aspects of both, but cannot be claimed compliant with either. The APIs and existing user code with expectations on specific behaviors predate both standards leading us to be very cautious about making API behavior changes.

Розбір байтів, закодованих ASCII

Функції аналізу URL спочатку були розроблені для роботи лише з рядками символів. На практиці корисно мати можливість маніпулювати правильно цитованими та закодованими URL-адресами як послідовностями байтів ASCII. Відповідно, усі функції аналізу URL-адрес у цьому модулі працюють з об’єктами bytes і bytearray на додаток до об’єктів str.

Якщо передано дані str, результат також міститиме лише дані str. Якщо передано дані bytes або bytearray, результат міститиме лише дані bytes.

Спроба змішати дані str із bytes або bytearray в одному виклику функції призведе до появи TypeError під час спроби передати не-ASCII значення байтів викликатимуть UnicodeDecodeError.

Для підтримки легшого перетворення об’єктів результату між str і bytes, усі значення, що повертаються функціями парсингу URL-адреси, надають або метод encode() (якщо результат містить str data) або метод decode() (якщо результат містить дані bytes). Сигнатури цих методів збігаються з сигнатурами відповідних методів str і bytes (за винятком того, що стандартним кодуванням є 'ascii', а не 'utf-8') . Кожен створює значення відповідного типу, яке містить або дані bytes (для методів encode()), або дані str (для методів decode()).

Програми, яким потрібно працювати з потенційно неправильно цитованими URL-адресами, які можуть містити дані, відмінні від ASCII, повинні будуть виконати власне декодування з байтів на символи перед тим, як викликати методи аналізу URL-адрес.

Поведінка, описана в цьому розділі, стосується лише функцій аналізу URL-адреси. Функції цитування URL-адрес використовують власні правила під час створення або споживання послідовностей байтів, як описано в документації окремих функцій цитування URL-адрес.

Змінено в версії 3.2: Функції аналізу URL-адрес тепер приймають послідовності байтів у кодуванні ASCII

Структуровані результати аналізу

Об’єкти результатів функцій urlparse(), urlsplit() і urldefrag() є підкласами типу tuple. Ці підкласи додають атрибути, перелічені в документації для цих функцій, підтримку кодування та декодування, описану в попередньому розділі, а також додатковий метод:

urllib.parse.SplitResult.geturl()

Return the re-combined version of the original URL as a string. This may differ from the original URL in that the scheme may be normalized to lower case and empty components may be dropped. Specifically, empty parameters, queries, and fragment identifiers will be removed unless the URL was parsed with missing_as_none=True.

Для результатів urldefrag() буде видалено лише порожні ідентифікатори фрагментів. Для результатів urlsplit() і urlparse() усі зазначені зміни буде внесено до URL-адреси, яку повертає цей метод.

Результат цього методу залишається незмінним, якщо передати його через вихідну функцію аналізу:

>>> from urllib.parse import urlsplit
>>> url = 'HTTP://www.Python.org/doc/#'
>>> r1 = urlsplit(url)
>>> r1.geturl()
'http://www.Python.org/doc/'
>>> r2 = urlsplit(r1.geturl())
>>> r2.geturl()
'http://www.Python.org/doc/'
>>> r3 = urlsplit(url, missing_as_none=True)
>>> r3.geturl()
'http://www.Python.org/doc/#'

Наступні класи забезпечують реалізацію результатів структурованого аналізу під час роботи з об’єктами str:

class urllib.parse.DefragResult(url, fragment)

Конкретний клас для результатів urldefrag(), що містять дані str. Метод encode() повертає екземпляр DefragResultBytes.

Added in version 3.2.

class urllib.parse.ParseResult(scheme, netloc, path, params, query, fragment)

Конкретний клас для результатів urlparse(), що містять дані str. Метод encode() повертає екземпляр ParseResultBytes.

class urllib.parse.SplitResult(scheme, netloc, path, query, fragment)

Конкретний клас для результатів urlsplit(), що містять дані str. Метод encode() повертає екземпляр SplitResultBytes.

Наступні класи забезпечують реалізацію результатів аналізу під час роботи з об’єктами bytes або bytearray:

class urllib.parse.DefragResultBytes(url, fragment)

Конкретний клас для результатів urldefrag(), що містять дані bytes. Метод decode() повертає екземпляр DefragResult.

Added in version 3.2.

class urllib.parse.ParseResultBytes(scheme, netloc, path, params, query, fragment)

Конкретний клас для результатів urlparse(), що містять дані bytes. Метод decode() повертає екземпляр ParseResult.

Added in version 3.2.

class urllib.parse.SplitResultBytes(scheme, netloc, path, query, fragment)

Конкретний клас для результатів urlsplit(), що містять дані bytes. Метод decode() повертає екземпляр SplitResult.

Added in version 3.2.

Цитування URL

Функції цитування URL-адреси зосереджені на тому, щоб отримати програмні дані та зробити їх безпечними для використання як компонентів URL-адреси шляхом цитування спеціальних символів і відповідного кодування тексту, відмінного від ASCII. Вони також підтримують реверсування цих операцій, щоб відтворити вихідні дані з вмісту компонента URL-адреси, якщо це завдання ще не охоплено функціями аналізу URL-адреси вище.

urllib.parse.quote(string, safe='/', encoding=None, errors=None)

Replace special characters in string using the %xx escape. Letters, digits, and the characters '_.-~' are never quoted. By default, this function is intended for quoting the path section of a URL. The optional safe parameter specifies additional ASCII characters that should not be quoted — its default value is '/'.

string може бути об’єктом str або bytes.

Змінено в версії 3.7: Переміщено з RFC 2396 до RFC 3986 для цитування рядків URL. «~» тепер включено до набору незарезервованих символів.

Необов’язкові параметри encoding і errors вказують, як працювати з символами, відмінними від ASCII, як прийнято методом str.encode(). кодування за замовчуванням 'utf-8'. errors за умовчанням має значення 'strict', тобто непідтримувані символи викликають UnicodeEncodeError. кодування та помилки не повинні надаватися, якщо рядок є 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(string, safe='', encoding=None, errors=None)

Подібно до quote(), але також замініть пробіли знаками плюса, як це потрібно для цитування значень HTML-форми під час створення рядка запиту для переходу до URL-адреси. Знаки «плюс» у вихідному рядку екрануються, якщо вони не включені в safe. Він також не має safe типового значення '/'.

Приклад: quote_plus('/El Niño/') дає '%2FEl+Ni%C3%B1o%2F''.

urllib.parse.quote_from_bytes(bytes, safe='/')

Подібно до quote(), але приймає об’єкт bytes, а не str, і не виконує кодування рядок-байт.

Приклад: quote_from_bytes(b'a&\xef') дає 'a%26%EF''.

urllib.parse.unquote(string, encoding='utf-8', errors='replace')

Replace %xx escapes with their single-character equivalent. The optional encoding and errors parameters specify how to decode percent-encoded sequences into Unicode characters, as accepted by the bytes.decode() method.

string може бути об’єктом str або bytes.

кодування за замовчуванням 'utf-8'. errors за умовчанням має значення 'replace', тобто недійсні послідовності замінюються символом-заповнювачем.

Приклад: unquote('/El%20Ni%C3%B1o/') дає '/El Niño/''.

Змінено в версії 3.9: Параметр string підтримує об’єкти bytes і str (раніше лише str).

urllib.parse.unquote_plus(string, encoding='utf-8', errors='replace')

Подібно до unquote(), але також замініть знаки «плюс» пробілами, як це потрібно для зняття лапок значень форми HTML.

рядок має бути str.

Приклад: unquote_plus('/El+Ni%C3%B1o/') дає '/El Niño/''.

urllib.parse.unquote_to_bytes(string)

Replace %xx escapes with their single-octet equivalent, and return a bytes object.

string може бути об’єктом str або bytes.

Якщо це str, неекрановані не-ASCII символи в string кодуються в UTF-8 байтах.

Приклад: unquote_to_bytes('a%26%EF') дає b'a&\xef'.

urllib.parse.urlencode(query, doseq=False, safe='', encoding=None, errors=None, quote_via=quote_plus)

Перетворіть об’єкт зіставлення або послідовність двоелементних кортежів, які можуть містити об’єкти str або bytes, у текстовий рядок ASCII у відсотковому кодуванні. Якщо результуючий рядок має використовуватись як дані для операції POST із функцією urlopen(), тоді його слід закодувати в байти, інакше це призведе до TypeError.

Отриманий рядок є серією пар ключ=значення, розділених символами '&'', де ключ і значення взяті в лапки за допомогою функції quote_via. За замовчуванням quote_plus() використовується для взяття значень у лапки, що означає, що пробіли беруться в лапки як символ '+', а символи „/“ кодуються як %2F, що відповідає стандарту для Запити GET (application/x-www-form-urlencoded). Альтернативною функцією, яку можна передати як quote_via, є quote(), яка кодуватиме пробіли як %20 і не кодуватиме символи „/“. Для максимального контролю над тим, що цитується, використовуйте quote і вкажіть значення для safe.

Коли послідовність двоелементних кортежів використовується як аргумент запиту, перший елемент кожного кортежу є ключем, а другий — значенням. Елемент значення сам по собі може бути послідовністю, і в такому випадку, якщо необов’язковий параметр doseq оцінюється як True, окремі пари ключ=значення генеруються для кожен елемент послідовності значень для ключа. Порядок параметрів у закодованому рядку відповідатиме порядку кортежів параметрів у послідовності.

Параметри safe, encoding і errors передаються до quote_via (параметри encoding і errors передаються лише тоді, коли елемент запиту є str).

Щоб змінити цей процес кодування, у цьому модулі передбачено parse_qs() і parse_qsl() для аналізу рядків запиту в структурах даних Python.

Зверніться до urllib examples, щоб дізнатися, як метод urllib.parse.urlencode() можна використовувати для генерації рядка запиту URL-адреси або даних для запиту POST.

Змінено в версії 3.2: query підтримує байти та рядкові об’єкти.

Змінено в версії 3.5: Added the quote_via parameter.

Застаріло починаючи з версії 3.14: Accepting objects with false values (like 0 and []) except empty strings and byte-like objects and None is now deprecated.

Дивись також

WHATWG - URL Життєвий рівень

Робоча група для стандарту URL-адрес, яка визначає URL-адреси, домени, IP-адреси, формат application/x-www-form-urlencoded та їх API.

RFC 3986 - Уніфіковані ідентифікатори ресурсів

Це поточний стандарт (STD66). Будь-які зміни в модулі urllib.parse мають відповідати цьому. Можуть спостерігатися певні відхилення, які здебільшого пов’язані з цілями зворотної сумісності та певними де-факто вимогами до аналізу, які зазвичай спостерігаються в основних браузерах.

RFC 2732 - Формат буквальних IPv6-адрес в URL-адресах.

Це визначає вимоги до аналізу URL-адрес IPv6.

RFC 2396 - Уніфіковані ідентифікатори ресурсів (URI): загальний синтаксис

Документ, що описує загальні синтаксичні вимоги як для уніфікованих імен ресурсів (URN), так і для уніфікованих покажчиків ресурсів (URL).

RFC 2368 - Схема URL-адреси електронної пошти.

Вимоги до розбору URL-схем mailto.

RFC 1808 - Відносні уніфіковані локатори ресурсів

Цей Запит на коментарі містить правила об’єднання абсолютної та відносної URL-адрес, включаючи чималу кількість «ненормальних прикладів», які регулюють обробку прикордонних випадків.

RFC 1738 - Уніфіковані покажчики ресурсів (URL)

Це визначає формальний синтаксис і семантику абсолютних URL-адрес.