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='', allow_fragments=True)

Розберіть URL-адресу на шість компонентів, повертаючи 6-елементний named tuple. Це відповідає загальній структурі URL: scheme://netloc/path;parameters?query#fragment. Кожен елемент кортежу є рядком, можливо порожнім. Компоненти не розбиваються на більш дрібні частини (наприклад, мережеве розташування є одним рядком), а % екранування не розгортається. Роздільники, як показано вище, не є частиною результату, за винятком початкової скісної риски в компоненті path, яка зберігається, якщо є. Наприклад:

>>> 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'

Дотримуючись специфікації синтаксису в 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='')

Аргумент схема дає схему адресації за замовчуванням, яка використовується, лише якщо її не вказано в URL-адресі. Він має бути того самого типу (текст або байти), що й urlstring, за винятком того, що значення за замовчуванням '' завжди допускається та автоматично перетворюється на b'', якщо це необхідно.

Якщо аргумент allow_fragments має значення false, ідентифікатори фрагментів не розпізнаються. Натомість вони аналізуються як частина шляху, параметрів або компонента запиту, а fragment встановлюється як порожній рядок у поверненому значенні.

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

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

Читання атрибута 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: Номери портів поза діапазоном тепер викликають ValueError замість повернення None.

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

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, дозволяли використовувати як ;, так і & як роздільник параметрів запиту. Це було змінено, щоб дозволити лише один роздільний ключ із & як роздільником за умовчанням.

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)

Створіть URL-адресу з кортежу, який повертає urlparse(). Аргумент parts може бути будь-яким ітерованим із шести елементів. Це може призвести до дещо іншої, але еквівалентної URL-адреси, якщо спочатку проаналізована URL-адреса мала непотрібні розділювачі (наприклад, ? із порожнім запитом; у RFC зазначено, що вони еквівалентні).

urllib.parse.urlsplit(urlstring, scheme='', allow_fragments=True)

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

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

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

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

Читання атрибута 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: Номери портів поза діапазоном тепер викликають ValueError замість повернення None.

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

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

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

urllib.parse.urlunsplit(parts)

Об’єднайте елементи кортежу, які повертає urlsplit(), у повну URL-адресу як рядок. Аргументом parts може бути будь-який ітерований з п’яти елементів. Це може призвести до дещо іншої, але еквівалентної URL-адреси, якщо спочатку проаналізована URL-адреса мала непотрібні розділювачі (наприклад, ? із порожнім запитом; у RFC зазначено, що вони еквівалентні).

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)

Якщо url містить ідентифікатор фрагмента, поверніть модифіковану версію url без ідентифікатора фрагмента та ідентифікатор фрагмента як окремий рядок. Якщо в url немає ідентифікатора фрагмента, поверніть url без змін і порожній рядок.

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

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

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

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

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

Повертає повторно об’єднану версію вихідної URL-адреси у вигляді рядка. Це може відрізнятися від вихідної URL-адреси тим, що схема може бути нормалізована до нижнього регістру, а порожні компоненти можуть бути видалені. Зокрема, порожні параметри, запити та ідентифікатори фрагментів буде видалено.

Для результатів 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/'

Наступні класи забезпечують реалізацію результатів структурованого аналізу під час роботи з об’єктами 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.

Дивись також

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-адрес.