Справочные данные по URL

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

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

class werkzeug.urls.BaseURL(scheme, netloc, path, query, fragment)

Базовый класс для URL и BytesURL.

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

Параметры

схема (str) –
доменное имя (str) –
путь (str) –
запрос (str) –
фрагмент (str) –

property ascii_host: Optional[str]: Точно так же, как host, но возвращает результат, ограниченный ASCII. Если найдено доменное имя, не являющееся ASCII, оно будет декодировано с помощью idna. Это полезно для операций с сокетами, когда URL может содержать символы национальных языков.

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

decode_netloc()

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

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

decode_query(*args, **kwargs)

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

Параметры

args (Any) –
kwargs (Any) –

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

ds.MultiDict[str, str]

encode_netloc()

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

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

get_file_location(pathformat=None)

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

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

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

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

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

join(*args, **kwargs)

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

Параметры

args (Any) –
kwargs (Any) –

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

werkzeug.urls.BaseURL

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

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

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

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

replace(**kwargs)

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

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

to_iri_tuple()

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

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

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

to_uri_tuple()

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

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

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

to_url()

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

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

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

class werkzeug.urls.BytesURL(scheme, netloc, path, query, fragment)

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

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

Параметры

схема (str) –
доменное имя (str) –
путь (str) –
запрос (str) –
фрагмент (str) –

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

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

Параметры

кодировка символов (str) –
ошибки (str) –

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

werkzeug.urls.URL

encode_netloc()

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

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

class werkzeug.urls.Href(base='./', charset='utf-8', sort=False, key=None)

Реализует вызываемый объект, который строит URL с заданной базой. Функция может вызываться с любым количеством позиционных и ключевых аргументов, которые затем используются для сборки URL. Работает с URL и POSIX-путями.

Позиционные аргументы добавляются как отдельные сегменты к пути URL:

>>> href = Href('/foo')
>>> href('bar', 23)
'/foo/bar/23'
>>> href('foo', bar=23)
'/foo/foo?bar=23'

Если любой из аргументов (позиционный или ключевой) имеет значение None он будет пропущен. Если ключевые аргументы не заданы, последний аргумент может быть dict или MultiDict (или любой другой подкласс словаря), в противном случае ключевые аргументы используются для параметров запроса, отбрасывая первую конечную подчёркивание в имени параметра:

>>> href(is_=42)
'/foo?is=42'
>>> href({'foo': 'bar'})
'/foo?foo=bar'

Комбинирование обоих методов не допускается:

>>> href({'foo': 'bar'}, bar=42)
Traceback (most recent call last):
  ...
TypeError: keyword arguments and query-dicts can't be combined

Обращение к атрибутам объекта href создаёт новый объект href с именем атрибута в качестве префикса:

>>> bar_href = href.bar
>>> bar_href("blub")
'/foo/bar/blub'

Если sort установлено в True элементы сортируются по key или по алгоритму сортировки по умолчанию:

>>> href = Href("/", sort=True)
>>> href(a=1, b=2, c=3)
'/?a=1&b=2&c=3'

Устарело начиная с версии 2.0: Будет удалено в Werkzeug 2.1. Используйте werkzeug.routing вместо этого.

Изменения

Добавлено в версии 0.5: sort и key были добавлены.

class werkzeug.urls.URL(scheme, netloc, path, query, fragment)

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

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

Параметры

схема (str) –
доменное имя (str) –
путь (str) –
запрос (str) –
фрагмент (str) –

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

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

Параметры

кодировка символов (str) –
ошибки (str) –

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

werkzeug.urls.BytesURL

werkzeug.urls.iri_to_uri(iri, charset='utf-8', errors='strict', safe_conversion=False)

Преобразует 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 (Union[str, Tuple[str, str, str, str, str]]) – IRI для преобразования.
кодировка символов (str) – Кодировка IRI.
ошибки (str) – Обработчик ошибок для использования во время bytes.encode.
безопасное преобразование (bool) – Возвратить URL без изменений, если он содержит только символы ASCII и без пробелов. См. объяснение ниже.

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

str

Существует общая проблема с преобразованием IRI в некоторых протоколах, которые нарушают спецификацию URI. Рассмотрим следующие два IRI:

magnet:?xt=uri:whatever
itms-services://?action=download-manifest

После анализа мы не знаем, требует ли схема //, которая удаляется, если пуста, но имеет разное значение в конечном URL, если она присутствует или нет. В этом случае можно использовать safe_conversion, которое вернёт URL без изменений, если он содержит только символы ASCII и без пробелов. Это может привести к URI с необработанными символами, если он не был правильно обработано, но сохраняет семантику URL. Werkzeug использует это для заголовка Location для редиректов.

Изменения

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

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

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

werkzeug.urls.uri_to_iri(uri, charset='utf-8', errors='werkzeug.url_quote')

Преобразовать 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 (Union[str, Tuple[str, str, str, str, str]]) – URI для преобразования.
charset (str) – Кодировка для кодирования байтов без кавычек.
errors (str) – Обработчик ошибок при bytes.encode. По умолчанию недопустимые байты остаются в кавычках.

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

str

Изменения

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

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

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

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

Параметры

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

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

ds.MultiDict[str, str]

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

Изменения

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

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

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

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

Параметры

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

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

ds.MultiDict[str, str]

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

Изменения

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

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

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

Параметры

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

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

str

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

Изменения

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

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

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

Параметры

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

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

None

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

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

Добавлена в версии 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

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

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

Параметры

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

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

str

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

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

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

Параметры

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

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

werkzeug.urls.BaseURL

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

Кодирует URL одну строку с заданной кодировкой.

Параметры

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

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

str

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

Добавлено в версии 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

werkzeug.urls.url_unparse(components)

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

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

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

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

Параметры

s (Union[str, bytes]) – Строка, которую нужно декодировать.
charset (str) – Кодировка строки запроса. Если установлена на None, декодирование не будет выполнено.
errors (str) – Обработка ошибок при декодировании кодировки.
unsafe (str) –

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

str

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

Декодировать строку URL с заданной кодировкой и преобразовать «+» в пробелы.

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

Параметры

s (Union[str, bytes]) – Строка, которую нужно декодировать.
charset (str) – Кодировка строки запроса. Если установлена на None, декодирование не будет выполнено.
errors (str) – Обработка ошибок при декодировании кодировки.

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

str