Утилиты

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

Разбор канонической строки «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, например, «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).
Возвращает:	Объект UTC datetime, соответствующий заданной 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