Утилиты

Функции 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.parse.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]

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

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

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

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 заставит фреймворк обрабатывать запятые как символы в каждом вхождении значения параметра.
Возвращает:	Словарь пар (имя, значение), по одному на каждый параметр запроса. Обратите внимание, что значение может быть одним 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, например: «Tue, 15 Nov 1994 12:45:26 GMT».
Тип возвращаемого значения:	str

falcon.dt_to_http(dt) [source]

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

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

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

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

Параметры:	http_date (str) – Строка даты в формате RFC 1123, например: «Tue, 15 Nov 1994 12:45:26 GMT».
Ключевые аргументы:
	obs_date (bool) – Поддержка форматов obs-date в соответствии с RFC 7231, например: «Sunday, 06-Nov-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) – Игнорируется
Возвращает:	Корректировка DST для GMT, которая всегда равна 0.
Тип возвращаемого значения:	datetime.timedelta

tzname(dt) [source]

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

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

utcoffset(dt) [source]

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

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