Справочник по URL

Функции для работы с URL.

Содержит реализации функций из urllib.parse, которые обрабатывают байты и строки.

class werkzeug.urls.BaseURL(*args, **kwargs)

Предок класса URL и BytesURL.

Устаревшее с версии 2.3: Будет удалено в Werkzeug 3.0. Используйте библиотеку urllib.parse вместо неё.

Создать новый экземпляр _URLTuple(схема, доменное имя, путь, запрос, фрагмент)

Параметры:

args (t.Any) –
kwargs (t.Any) –

Тип возвращаемого значения:

BaseURL

property ascii_host: str | None: Работает точно так же, как host, но вернёт результат, ограниченный ASCII. Если найдёт доменное имя, не являющееся ASCII, то попытается выполнить декодирование IDNA. Это полезно для операций с сокетами, когда URL может содержать символы с национальными особенностями.

property auth: str | None: Часть аутентификации в URL, если она есть, None в противном случае.

decode_netloc()

Декодирует часть доменного имени в строку.

Тип возвращаемого значения:: str

decode_query(*args, **kwargs)

Декодирует часть запроса URL. Это сокращение вызова url_decode() для аргумента запроса. Аргументы и ключевые аргументы передаются в url_decode() без изменений.

Параметры:

args (t.Any) –
kwargs (t.Any) –

Тип возвращаемого значения:

ds.MultiDict[str, str]

encode_netloc()

Кодирует часть доменного имени в безопасный для URL ASCII формат в виде байтов.

Тип возвращаемого значения:: str

get_file_location(pathformat=None)

Возвращает кортеж с расположением файла в формате (server, location). Если доменное имя в URL пустое или указывает на localhost, оно представлено как None.

Формат pathformat по умолчанию — автоматическое определение, но нужно устанавливать при работе с URL конкретной системы. Поддерживаемые значения — 'windows' для Windows или DOS путей и 'posix' для POSIX путей.

Если URL не указывает на локальный файл, сервер и расположение представлены как None.

Параметры:: pathformat (str | None) – Ожидаемый формат компонента пути. В настоящее время поддерживаются 'windows' и 'posix'. По умолчанию None — автоматическое определение.
Тип возвращаемого значения:: tuple[str | None, str | None]

property host: str | None: Часть доменного имени URL, если она есть, иначе None. Доменное имя — это либо имя хоста, либо IP-адрес, указанный в URL. Порт не включается.

join(*args, **kwargs)

Объединяет этот URL с другим. Это просто функция для удобства вызова url_join() и последующего повторного разбора возвращаемого значения.

Параметры:

args (Any) –
kwargs (Any) –

Тип возвращаемого значения:

BaseURL

property password: str | None: Пароль, если он был частью URL, None в противном случае. Подвергается декодированию URL и всегда является строкой.

property port: int | None: Порт в URL как целое число, если он был указан, None в противном случае. Не заполняет порты по умолчанию.

property raw_password: str | None: Пароль, если он был частью URL, None в противном случае. В отличие от password, этот не декодируется.

property raw_username: str | None: Имя пользователя, если оно было частью URL, None в противном случае. В отличие от username, этот не декодируется.

replace(**kwargs)

Возвращает URL с теми же значениями, за исключением параметров, получивших новые значения благодаря заданным ключевым аргументам.

Параметры:: kwargs (Any) –
Тип возвращаемого значения:: BaseURL

to_iri_tuple()

Возвращает кортеж URL , содержащий IRI. Попробует декодировать как можно больше информации из URL, не теряя данных, подобно тому, как это делает веб-браузер для строки URL.

Обычно интереснее напрямую вызвать uri_to_iri(), который вернёт строку.

Тип возвращаемого значения:: BaseURL

to_uri_tuple()

Возвращает кортеж BytesURL , содержащий URI. Правильно закодирует всю информацию в URL в ASCII в соответствии с правилами, которым следует веб-браузер.

Обычно интереснее напрямую вызвать iri_to_uri(), который вернёт строку.

Тип возвращаемого значения:: BaseURL

to_url()

Возвращает строку URL или байты, в зависимости от типа хранящейся информации. Это просто функция для удобства вызова url_unparse() для этого URL.

Тип возвращаемого значения:: str

property username: str | None: Имя пользователя, если оно было частью URL, None в противном случае. Подвергается декодированию URL и всегда является строкой.

class werkzeug.urls.BytesURL(*args, **kwargs)

Представляет собой разобранный URL в байтах.

Устарело начиная с версии 2.3: Будет удалено в Werkzeug 3.0. Используйте библиотеку urllib.parse вместо неё.

Создаёт новый экземпляр _URLTuple(схема, доменное имя, путь, запрос, фрагмент)

Параметры:

args (t.Any) –
kwargs (t.Any) –

Тип возвращаемого значения:

BaseURL

decode(charset='utf-8', errors='replace')

Декодирует URL в кортеж, состоящий из строк. Кодировка символов используется только для пути, запроса и фрагмента.

Параметры:

charset (str) –
errors (str) –

Тип возвращаемого значения:

URL

encode_netloc()

Возвращает доменное имя без изменений в виде байтов.

Тип возвращаемого значения:: bytes

class werkzeug.urls.URL(*args, **kwargs)

Представляет собой разобранный URL. Он ведет себя как обычный кортеж, но также имеет дополнительные атрибуты, которые предоставляют дополнительную информацию о URL.

Устарело начиная с версии 2.3: Будет удалено в Werkzeug 3.0. Используйте библиотеку urllib.parse вместо неё.

Создаёт новый экземпляр _URLTuple(схема, доменное имя, путь, запрос, фрагмент)

Параметры:

args (t.Any) –
kwargs (t.Any) –

Тип возвращаемого значения:

BaseURL

encode(charset='utf-8', errors='replace')

Кодирует URL в кортеж, состоящий из байтов. Кодировка символов используется только для пути, запроса и фрагмента.

Параметры:

charset (str) –
errors (str) –

Тип возвращаемого значения:

BytesURL

werkzeug.urls.iri_to_uri(iri, charset=None, errors=None, safe_conversion=None)

Преобразует IRI в URI. Все символы, не являющиеся ASCII, и небезопасные символы, приводятся к виду с котировкой. Если в URL есть домен, он кодируется с помощью Punycode.

>>> iri_to_uri('http://\u2603.net/p\xe5th?q=\xe8ry%DF')
'http://xn--n3h.net/p%C3%A5th?q=%C3%A8ry%DF'

Параметры:

iri (str | tuple[str, str, str, str, str]) – Преобразуемый IRI.
charset (str | None) – Кодировка IRI.
errors (str | None) – Обработчик ошибок, используемый во время bytes.encode.
safe_conversion (bool | None) –

Тип возвращаемого значения:

str

Изменено в версии 2.3: Передача кортежа или байтов, а также параметров charset и errors, устарела и будет удалена в Werkzeug 3.0.

Изменено в версии 2.3: Какие символы остаются не закодированными, зависит от каждой части URL.

Изменено в версии 2.3: Параметр safe_conversion устарел и будет удалён в Werkzeug 2.4.

Изменения

Изменено в версии 0.15: Все зарезервированные символы остаются не закодированными. Раньше только некоторые зарезервированные символы оставались не закодированными.

Изменено в версии 0.9.6: Добавлен параметр safe_conversion.

Добавлено в версии 0.6.

werkzeug.urls.uri_to_iri(uri, charset=None, errors=None)

Преобразует URI в IRI. Все допустимые символы UTF-8 приводятся к виду без котировок, оставляя все зарезервированные и недопустимые символы закодированными. Если в URL есть домен, он декодируется из Punycode.

>>> uri_to_iri("http://xn--n3h.net/p%C3%A5th?q=%C3%A8ry%DF")
'http://\u2603.net/p\xe5th?q=\xe8ry%DF'

Параметры:

uri (str | tuple[str, str, str, str, str]) – Преобразуемый URI.
charset (str | None) – Кодировка для кодирования байтов без котировки.
errors (str | None) – Обработчик ошибок, используемый во время bytes.encode. По умолчанию недопустимые байты остаются с котировкой.

Тип возвращаемого значения:

str

Изменено в версии 2.3: Какие символы остаются с котировкой, зависит от каждой части URL.

Изменения

Изменено в версии 0.15: Все зарезервированные и недопустимые символы остаются с котировкой. Раньше только некоторые зарезервированные символы сохранялись, а недопустимые байты заменялись вместо того, чтобы оставаться с котировкой.

Добавлено в версии 0.6.

END_OF_DOCUMENT_MARKER ```

werkzeug.urls.url_decode(s, charset='utf-8', include_empty=True, errors='replace', separator='&', cls=None)

Разбор строки запроса и возврат результата в виде MultiDict.

Параметры:

s (t.AnyStr) – Строка запроса для разбора.
charset (str) – Кодировка для декодирования байтов в строку. Если не указано, байты возвращаются в неизменном виде.
include_empty (bool) – Включать ключи с пустыми значениями в словарь.
errors (str) – Обработка ошибок при декодировании байтов.
separator (str) – Разделитель между парами.
cls (type[ds.MultiDict] | None) – Контейнер для хранения результата вместо MultiDict.

Тип возвращаемого значения:

ds.MultiDict[str, str]

Устаревшая с версии 2.3: Будет удалена в Werkzeug 3.0. Используйте urllib.parse.parse_qs вместо этого.

Журнал изменений

Изменено в версии 2.1: Параметр decode_keys был удален.

Изменено в версии 0.5: В предыдущих версиях для URL-декодирования можно было использовать «;» и «&». Сейчас поддерживается только «&». Если вы хотите использовать «;», можно указать другой separator.

Изменено в версии 0.5: Добавлен параметр cls.

werkzeug.urls.url_decode_stream(stream, charset='utf-8', include_empty=True, errors='replace', separator=b'&', cls=None, limit=None)

Работает как url_decode(), но декодирует поток. Поведение потока и предела аналогично функциям, таким как make_line_iter(). Генератор пар напрямую передается в cls, так что вы можете использовать данные по мере их разбора.

Параметры:

stream (t.IO[bytes]) – поток с закодированной строкой запроса
charset (str) – кодировка строки запроса. Если установлено None декодирование не будет выполнено.
include_empty (bool) – Установлено в False если вы не хотите, чтобы пустые значения отображались в словаре.
errors (str) – поведение при ошибках декодирования.
separator (bytes) – разделитель пар, по умолчанию &
cls (type[ds.MultiDict] | None) – необязательный класс словаря для использования. Если это не указано или None используется по умолчанию MultiDict.
limit (int | None) – длина содержимого данных URL. Не требуется, если предоставлен ограниченный поток.

Тип возвращаемого значения:

ds.MultiDict[str, str]

Устаревшая с версии 2.3: Будет удалена в Werkzeug 2.4. Используйте urllib.parse.parse_qs вместо этого.

Журнал изменений

Изменено в версии 2.1: Параметры decode_keys и return_iterator были удалены.

Добавлена в версии 0.8.

werkzeug.urls.url_encode(obj, charset='utf-8', sort=False, key=None, separator='&')

URL-кодирование словаря/MultiDict. Если значение None оно не будет отображаться в строке результата. По умолчанию только значения кодируются в строки целевой кодировки.

Параметры:

obj (Mapping[str, str] | Iterable[tuple[str, str]]) – объект, который нужно закодировать в строку запроса.
charset (str) – кодировка строки запроса.
sort (bool) – установлено в True если вы хотите, чтобы параметры были отсортированы по key.
separator (str) – разделитель, который будет использоваться для пар.
key (Callable[[tuple[str, str]], Any] | None) – необязательная функция для сортировки. Более подробную информацию см. в документации по sorted().

Тип возвращаемого значения:

str

Устаревшая с версии 2.3: Будет удалена в Werkzeug 2.4. Используйте urllib.parse.urlencode вместо этого.

Журнал изменений

Изменено в версии 2.1: Параметр encode_keys был удален.

Изменено в версии 0.5: Добавлены параметры sort, key, и separator.

END_OF_DOCUMENT_MARKER

werkzeug.urls.url_encode_stream(obj, stream=None, charset='utf-8', sort=False, key=None, separator='&')

Подобно url_encode(), но записывает результаты в объект потока. Если поток — None — возвращается генератор всех закодированных пар.

Параметры:

obj (Mapping[str, str] | Iterable[tuple[str, str]]) – объект для кодирования в строку запроса.
stream (IO[str] | None) – поток для записи закодированного объекта или None , если должен быть возвращён итератор закодированных пар. В этом случае параметр separator игнорируется.
charset (str) – кодировка строки запроса.
sort (bool) – устанавливается в True , если вы хотите отсортировать параметры по key.
separator (str) – разделитель для пар.
key (Callable[[tuple[str, str]], Any] | None) – необязательная функция для сортировки. Более подробная информация находится в документации sorted().

Тип возвращаемого значения:

None

Устарело начиная с версии 2.3: Будет удалено в Werkzeug 2.4. Используйте urllib.parse.urlencode вместо этого.

Журнал изменений

Изменено в версии 2.1: Параметр encode_keys был удалён.

Добавлен в версии 0.8.

werkzeug.urls.url_fix(s, charset='utf-8')

Иногда вы получаете URL от пользователя, который не является реальным URL, поскольку он содержит небезопасные символы, такие как пробелы и т. д. Эта функция может исправить некоторые проблемы аналогично тому, как браузеры обрабатывают данные, введённые пользователем:

>>> url_fix('http://de.wikipedia.org/wiki/Elf (Begriffskl\xe4rung)')
'http://de.wikipedia.org/wiki/Elf%20(Begriffskl%C3%A4rung)'

Параметры:

s (str) – строка с URL для исправления.
charset (str) – целевая кодировка символов для URL, если URL был передан как строка.

Тип возвращаемого значения:

str

Устарело начиная с версии 2.3: Будет удалено в Werkzeug 3.0.

werkzeug.urls.url_join(base, url, allow_fragments=True)

Объединить базовый URL и, возможно, относительный URL, чтобы сформировать абсолютную интерпретацию последнего.

Параметры:

base (str | tuple[str, str, str, str, str]) – базовый URL для операции объединения.
url (str | tuple[str, str, str, str, str]) – URL для объединения.
allow_fragments (bool) – указывает, разрешены ли фрагменты.

Тип возвращаемого значения:

str

Устарело начиная с версии 2.3: Будет удалено в Werkzeug 2.4. Используйте urllib.parse.urljoin вместо этого.

werkzeug.urls.url_parse(url, scheme=None, allow_fragments=True)

Разбирает URL из строки в кортеж URL. Если URL не содержит схемы, она может быть предоставлена в качестве второго аргумента. В противном случае она игнорируется. Необязательно, фрагменты могут быть удалены из URL, установив allow_fragments в False.

Обратный этой функции — url_unparse().

Параметры:

url (str) – URL для разбора.
scheme (str | None) – схема по умолчанию для использования, если URL не имеет схемы.
allow_fragments (bool) – если установлено False , фрагмент будет удалён из URL.

Тип возвращаемого значения:

BaseURL

Устарело начиная с версии 2.3: Будет удалено в Werkzeug 3.0. Используйте urllib.parse.urlsplit вместо этого.

werkzeug.urls.url_quote(string, charset='utf-8', errors='strict', safe='/:', unsafe='')

Кодировка URL для одной строки с заданной кодировкой.

Параметры:

s – строка для кодирования.
charset (str) – кодировка.
safe (str | bytes) – необязательная последовательность безопасных символов.
unsafe (str | bytes) – необязательная последовательность небезопасных символов.
string (str | bytes) –
errors (str) –

Тип возвращаемого значения:

str

Устаревшая с версии 2.3: Будет удалена в Werkzeug 3.0. Используйте urllib.parse.quote вместо этого.

Журнал изменений

Новая в версии 0.9.2: Параметр unsafe был добавлен.

werkzeug.urls.url_quote_plus(string, charset='utf-8', errors='strict', safe='')

Кодировка URL для одной строки с заданной кодировкой и преобразованием пробелов в “+”.

Параметры:

s – Строка для кодирования.
charset (str) – Используемая кодировка.
safe (str) – Необязательная последовательность безопасных символов.
string (str) –
errors (str) –

Тип возвращаемого значения:

str

Устаревшая с версии 2.3: Будет удалена в Werkzeug 3.0. Используйте urllib.parse.quote_plus вместо этого.

werkzeug.urls.url_unparse(components)

Обратная операция к url_parse(). Принимает произвольные, а также кортежи URL и возвращает URL в виде строки.

Параметры:: components (tuple[str, str, str, str, str]) – Разбор URL как кортеж, который должен быть преобразован в строку URL.
Тип возвращаемого значения:: str

Устаревшая с версии 2.3: Будет удалена в Werkzeug 3.0. Используйте urllib.parse.urlunsplit вместо этого.

werkzeug.urls.url_unquote(s, charset='utf-8', errors='replace', unsafe='')

Декодирование URL для одной строки с заданной кодировкой. Если кодировка установлена в None, декодирование не выполняется, и возвращаются исходные байты.

Параметры:

s (str | bytes) – строка для декодирования.
charset (str) – кодировка строки запроса. Если установлено в None, декодирование не будет выполнено.
errors (str) – обработка ошибок для декодирования кодировки.
unsafe (str) –

Тип возвращаемого значения:

str

Устаревшая с версии 2.3: Будет удалена в Werkzeug 3.0. Используйте urllib.parse.unquote вместо этого.

werkzeug.urls.url_unquote_plus(s, charset='utf-8', errors='replace')

Декодирование URL для одной строки с заданной charset и декодирование “+” в пробелы.

По умолчанию ошибки кодирования игнорируются. Если нужно другое поведение, можно установить errors на 'replace' или 'strict'.

Параметры:

s (str | bytes) – Строка для декодирования.
charset (str) – кодировка строки запроса. Если установлено в None, декодирование не будет выполнено.
errors (str) – обработка ошибок для декодирования charset.

Тип возвращаемого значения:

str

Устаревшая с версии 2.3: Будет удалена в Werkzeug 3.0. Используйте urllib.parse.unquote_plus вместо этого.