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

werkzeug.urls

werkzeug.urls используется для предоставления нескольких функций-обёртки для urlparse в Python 2, основное назначение которых — обход поведения стандартной библиотеки Py2 и отсутствие поддержки Unicode. Хотя эта ситуация уже была несколько неудобной, она стала ещё сложнее из-за того, что urllib.parse в Python 3 на самом деле корректно обрабатывает Unicode. Другими словами, этот модуль оборачивал две библиотеки с совершенно разным поведением. Поэтому теперь этот модуль содержит обратный порт совместимый с Python 2 и 3, urllib.parse, который в основном совместим с API.

class werkzeug.urls.BaseURL

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

ascii_host

Работает точно так же, как host, но возвращает результат, ограниченный ASCII. Если он находит netloc, который не является ASCII, он попытается декодировать его с помощью idna. Это полезно для операций с сокетами, когда URL может содержать символы национальных алфавитов.

auth

Часть аутентификации в URL, если она доступна, None в противном случае.

decode_netloc()

Декодирует часть netloc в строку.

decode_query(*args, **kwargs)

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

get_file_location(pathformat=None)

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

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

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

Параметры:	pathformat – Ожидаемый формат компонента пути. В настоящее время поддерживаются 'windows' и 'posix'. По умолчанию None — автоматическое определение.

host

Часть хоста URL, если доступна, иначе None. Хост — это либо имя хоста, либо IP-адрес, указанные в URL. Он не будет содержать порт.

join(*args, **kwargs)

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

password

Пароль, если он был частью URL, None в противном случае. Он подвергается URL-декодированию и всегда будет строкой Unicode.

port

Порт в URL в виде целого числа, если он был указан, None в противном случае. Это не заполняет порты по умолчанию.

raw_password

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

raw_username

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

replace(**kwargs)

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

to_iri_tuple()

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

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

to_uri_tuple()

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

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

to_url()

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

username

Имя пользователя, если он был частью URL, None в противном случае. Он подвергается URL-декодированию и всегда будет строкой Unicode.

class werkzeug.urls.BytesURL

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

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

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

encode_netloc()

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

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

Реализует вызываемый объект, который строит URL с заданным базовым 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'

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

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

class werkzeug.urls.URL

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

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

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

encode_netloc()

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

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 – IRI для преобразования. charset – Кодировка IRI. errors – Обработчик ошибок при bytes.encode. safe_conversion – Вернуть URL без изменений, если он содержит только символы ASCII и без пробелов. См. объяснение ниже.

Существует общая проблема с преобразованием 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 – URI для преобразования. charset – Кодировка для кодирования нескодированных байтов. errors – Обработчик ошибок при bytes.encode. По умолчанию некорректные байты оставляются закодированными.

Изменения

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

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

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

Разбор строки запроса и возврат в виде MultiDict. Существуют различия в декодировании ключей в разных версиях Python. В Python 3 ключи всегда полностью декодированы, тогда как в Python 2 ключи остаются байтовыми строками, если они помещаются в ASCII. В 2.x ключи можно принудительно преобразовать в unicode, установив decode_keys в True.

Если charset установлен в None, декодирование unicode не произойдёт и будут возвращены сырые байты.

По умолчанию отсутствующее значение для ключа устанавливается в пустое значение. Если вы не хотите этого поведения, вы можете установить include_empty в False.

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

Изменения

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

Добавлен параметр cls.

Параметры:

s – строка со строкой запроса для декодирования. charset – кодировка строки запроса. Если установлено None, декодирование unicode не выполняется. decode_keys – Используется в Python 2.x для управления тем, должны ли ключи принудительно преобразовываться в объекты unicode. Если установлено в True, ключи будут unicode в любом случае. В противном случае они остаются str, если они помещаются в ASCII. include_empty – Установите в False, если вы не хотите, чтобы пустые значения появлялись в словаре. errors – поведение при ошибках декодирования. separator – разделитель пар, по умолчанию & cls – необязательный класс словаря для использования. Если это не указано или None, используется MultiDict по умолчанию.

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

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

Изменения

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

Параметры:

stream – поток с закодированной строкой запроса charset – кодировка строки запроса. Если установлено None, декодирование unicode не выполняется. decode_keys – Используется в Python 2.x для управления тем, должны ли ключи принудительно преобразовываться в объекты unicode. Если установлено в True, ключи будут unicode в любом случае. В противном случае они остаются str если они помещаются в ASCII. include_empty – Установите в False, если вы не хотите, чтобы пустые значения появлялись в словаре. errors – поведение при ошибках декодирования. separator – разделитель пар, по умолчанию & cls – необязательный класс словаря для использования. Если это не указано или None, используется MultiDict по умолчанию. limit – длина содержимого данных URL. Не обязательно, если предоставлен ограниченный поток. return_iterator – если установлено в True, аргумент cls игнорируется, и возвращается итератор по всем декодированным парам.

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

Кодирование словаря/MultiDict в URL. Если значение None, оно не появится в результирующей строке. По умолчанию кодируются только значения в целевые строки charset. Если encode_keys установлено в True, поддерживаются и unicode ключи.

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

Изменения

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

Параметры:

obj – объект, который нужно закодировать в строку запроса. charset – кодировка строки запроса. encode_keys – установите в True, если у вас есть unicode ключи. (Игнорируется в Python 3.x) sort – установите в True, если вы хотите сортировать параметры по key. separator – разделитель, используемый для пар. key – необязательная функция, используемая для сортировки. Для получения дополнительной информации, ознакомьтесь с документацией sorted().

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

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

Изменения

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

Параметры:

obj – объект, который нужно закодировать в строку запроса. stream – поток для записи закодированного объекта или None если должен возвращаться итератор по закодированным парам. В этом случае аргумент separator игнорируется. charset – кодировка строки запроса. encode_keys – установите в True, если у вас есть unicode ключи. (Игнорируется в Python 3.x) sort – установите в True, если вы хотите сортировать параметры по key. separator – разделитель, используемый для пар. key – необязательная функция, используемая для сортировки. Для получения дополнительной информации, ознакомьтесь с документацией sorted().

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

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

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

Параметры:	s – строка с URL для исправления. charset – целевая кодировка символов для URL, если URL был задан как строка Unicode.

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

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

Параметры:	base – базовый URL для операции объединения. url – URL для объединения. allow_fragments – указывает, разрешены ли фрагменты.

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

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

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

Параметры:	url – URL для разбора. scheme – стандартная схема для использования, если URL не имеет схемы. allow_fragments – если установлено значение False, фрагмент будет удален из URL.

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

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

Параметры:	s – строка, которую нужно закодировать. charset – используемая кодировка. safe – (необязательный) список безопасных символов. unsafe – (необязательный) список небезопасных символов.

Changelog

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

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

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

Параметры:	s – строка для кодирования. charset – используемая кодировка. safe – (необязательный) список безопасных символов.

werkzeug.urls.url_unparse(components)

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

Параметры:	components – разобранный URL в виде кортежа, который должен быть преобразован в строку URL.

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

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

Параметры:	s – строка для декодирования. charset – кодировка строки запроса. Если установлено значение None, декодирование Unicode не будет выполнено. errors – обработка ошибок при декодировании кодировки символов.

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

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

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

Параметры:	s – строка для декодирования. charset – кодировка строки запроса. Если установлено значение None, декодирование Unicode не будет выполнено. errors – обработка ошибок при декодировании charset.