Утилиты

Функции URI

Утилиты URI.

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

from falcon import uri

name, port = uri.parse_host('example.org:8080')

falcon.uri.encode(uri)

Кодирует полный или относительный URI в соответствии с RFC 3986.

RFC 3986 определяет набор «незарезервированных» символов и набор «зарезервированных» символов, используемых в качестве разделителей. Эта функция экранирует все другие «запрещённые» символы путём их процентов-кодирования.

Примечание

Эта утилита в среднем случае быстрее, чем аналогичная функция quote в urlib. Она также стремится быть более удобной в использовании, предполагая разумный набор допустимых символов.

Параметры:	uri (str) – URI или часть URI для кодирования. Если это широкая строка (т.е., six.text_type), она будет закодирована в массив байтов UTF-8, и любые многобайтовые последовательности будут процентов-кодированы как есть.
Возвращает:	Заэкранированная версия uri, где все недопустимые символы были процентов-кодированы.
Тип возвращаемого значения:	str

falcon.uri.encode_value(uri)

Кодирует строку значения в соответствии с RFC 3986.

Недопустимые символы процентов-кодируются таким образом, что моделирует urllib.parse.quote(safe="~"). Однако функция Falcon в среднем случае быстрее, чем аналогичная функция quote в urlib. Она также стремится быть более удобной в использовании, предполагая разумный набор допустимых символов.

Все зарезервированные символы объединены в один набор «разделителей», и всё в этом наборе экранируется.

Примечание

RFC 3986 определяет набор «незарезервированных» символов и набор «зарезервированных» символов, используемых в качестве разделителей.

Параметры:	uri (str) – фрагмент URI для кодирования. Предполагается, что он не пересекает границы разделителей, и поэтому любые зарезервированные разделители URI, включённые в него, будут экранированы. Если value является широкой строкой (т.е., six.text_type), она будет закодирована в массив байтов UTF-8, и любые многобайтовые последовательности будут процентов-кодированы как есть.
Возвращает:	Заэкранированная версия uri, где все недопустимые символы были процентов-кодированы.
Тип возвращаемого значения:	str

falcon.uri.decode(encoded_uri) [source]

Декодирует процентов-кодированные символы в URI или строке запроса.

Эта функция моделирует поведение urllib.unquote_plus, но быстрее. Она также более устойчива, так как она будет декодировать экранированные многобайтовые последовательности UTF-8.

Параметры:	encoded_uri (str) – закодированный URI (полный или частичный).
Возвращает:	Декодированный URL. Будет типа unicode в Python 2, ЕСЛИ URL содержал экранированные символы не ASCII, в этом случае предполагается UTF-8 согласно RFC 3986.
Тип возвращаемого значения:	str

falcon.uri.parse_host(host, default_port=None) [source]

Разбирает каноническую строку «host:port» на части.

Разбирает строку хоста (которая может или не может содержать порт), учитывая, что строка может содержать либо доменное имя, либо IP-адрес. В последнем случае поддерживаются как IPv4, так и IPv6 адреса.

Параметры:	host (str) – строка хоста для разбора, необязательно содержащая номер порта.
Ключевые аргументы:
	default_port (int) – номер порта для возврата, когда строка хоста не содержит его (по умолчанию None).
Возвращает:	Кортеж (host, port) из заданной строки хоста, где порт преобразован в int. Если строка хоста не указывает порт, используется default_port.
Тип возвращаемого значения:	tuple

falcon.uri.parse_query_string(query_string, keep_blank_qs_values=False, parse_qs_csv=True) [source]

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

Параметры строки запроса предполагаются использующими стандартное кодирование формы. Возвращаются только параметры со значениями. Например, для «foo=bar&flag», эта функция проигнорирует «flag», если опция keep_blank_qs_values не установлена.

Примечание

В дополнение к стандартному HTML-формату для задания списков путём повторения определённого параметра несколько раз, Falcon поддерживает более компактный формат, в котором параметр может быть задан один раз, но установлен в list из запятыми разделенных элементов (например, «foo=a,b,c»).

При использовании этого формата все запятые, uri-кодированные, не будут восприниматься Falcon в качестве разделителя. Если клиент хочет отправить значение в виде списка, он не должен кодировать запятые со значениями.

Два различных способа задания списков не могут быть смешаны в одной строке запроса для одного и того же параметра.

Параметры:	query_string (str) – строка запроса для разбора. keep_blank_qs_values (bool) – Установите в True для возврата полей, даже если у них нет значения (по умолчанию False). Для значений, разделенных запятыми, эта опция также определяет, сохраняются ли пустые элементы в обработанном списке. parse_qs_csv – Установите в False для отключения разделения параметров запроса по , (по умолчанию True). В зависимости от пользователя, кодирование списков в виде нескольких вхождений одного и того же параметра может быть предпочтительнее. В этом случае установка parse_qs_csv в False заставит фреймворк рассматривать запятые как буквальные символы в каждом возникающем значении параметра.
Возвращает:	Словарь пар (name, value), по одному на параметр запроса. Обратите внимание, что value может быть одним str, или list из str.
Тип возвращаемого значения:	dict
Возможные исключения:	TypeError – query_string не было str.

falcon.uri.unquote_string(quoted) [source]

Разобрать RFC 7320 «строку в кавычках».

Параметры:	quoted (str) – Исходная строка в кавычках
Возвращает:	строку без кавычек
Тип возвращаемого значения:	str
Возможные исключения:	TypeError – quoted не было str

Разное

falcon.deprecated(instructions) [source]

Помечает метод как устаревший.

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

Параметры:	instructions (str) – Конкретные рекомендации для разработчика, например: «Пожалуйста, перейдите к add_proxy(…)»

falcon.http_now() [source]

Возвращает текущее время UTC в формате IMF-fixdate.

Возвращает:	Текущее время UTC в формате IMF-fixdate, например, «Втр, 15 ноя 1994 12:45:26 GMT».
Тип возвращаемого значения:	str

falcon.dt_to_http(dt) [source]

Преобразует объект datetime в строку HTTP-даты.

Параметры:	dt (datetime) – Объект datetime для преобразования, предполагается, что он находится в формате UTC.
Возвращает:	Строка даты в формате RFC 1123, например: «Втр, 15 ноя 1994 12:45:26 GMT».
Тип возвращаемого значения:	str

falcon.http_date_to_dt(http_date, obs_date=False) [source]

Преобразует строку HTTP-даты в объект datetime.

Параметры:	http_date (str) – Строка даты в формате RFC 1123, например: «Втр, 15 ноя 1994 12:45:26 GMT».
Ключевые аргументы:
	obs_date (bool) – Поддержка форматов obs-date согласно RFC 7231, например: «Воскресенье, 06-ноя-94 08:49:37 GMT» (по умолчанию False).
Возвращает:	Объект datetime в формате UTC, соответствующий заданной HTTP-дате.
Тип возвращаемого значения:	datetime
Исключения:	ValueError – http_date не соответствует ни одному из доступных форматов времени

falcon.to_query_str(params, comma_delimited_lists=True, prefix=True) [source]

Преобразует словарь параметров в строку запроса.

Параметры:	params (dict) – Словарь параметров, где каждый ключ — имя параметра, а каждое значение — либо str, либо то, что может быть преобразовано в str, или список таких значений. Если list, значение будет преобразовано в строку значений, разделённых запятыми (например, «thing=1,2,3»). comma_delimited_lists (bool) – Установите в False для кодирования списков значений, указав несколько экземпляров параметра (например, «thing=1&thing=2&thing=3»). В противном случае параметры будут закодированы как значения, разделённые запятыми (например, «thing=1,2,3»). По умолчанию True. prefix (bool) – Установите в False для исключения префикса «?» в результирующей строке (по умолчанию True).
Возвращает:	Строка URI запроса, включая префикс «?» (если prefix не False), или пустую строку, если параметры не заданы (то есть dict пуста).
Тип возвращаемого значения:	str

falcon.get_http_status(status_code, default_reason='Unknown') [source]

Получает код и описание HTTP-статуса по коду.

Параметры:	status_code – целое число или строка, которая может быть преобразована в целое число default_reason – текст по умолчанию, который будет добавлен к status_code, если поиск не найдет результат
Возвращает:	код состояния, например, «404 Not Found»
Тип возвращаемого значения:	str
Исключения:	ValueError – введенное значение не может быть преобразовано в целое число

falcon.get_bound_method(obj, method_name) [source]

Получает связанный метод данного объекта по имени.

Параметры:	obj – Объект, в котором ищется метод. method_name – Имя метода для извлечения.
Возвращает:	Связанный метод или None, если метод не существует в объекте.
Исключения:	AttributeError – Метод существует, но он не связан (вероятнее всего, был передан класс, а не экземпляр этого класса).

class falcon.TimezoneGMT [source]

Класс часового пояса GMT, реализующий интерфейс datetime.tzinfo.

dst(dt) [source]

Возвращает корректировку по летнему времени (DST).

Параметры:	dt (datetime.datetime) – Игнорируется
Возвращает:	Корректировка по летнему времени для GMT, которая всегда равна 0.
Тип возвращаемого значения:	datetime.timedelta

tzname(dt) [source]

Получить имя часового пояса.

Параметры:	dt (datetime.datetime) – Игнорируется
Возвращает:	“GMT”
Тип возвращаемого значения:	str

utcoffset(dt) [source]

Получить смещение от UTC.

Параметры:	dt (datetime.datetime) – Игнорируется
Возвращает:	Смещение GMT, которое эквивалентно UTC и поэтому всегда равно 0.
Тип возвращаемого значения:	datetime.timedelta