Утилиты

Функции 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 для кодирования. Если это строка с широким диапазоном символов (т.е., compat.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 является строкой с широким диапазоном символов (т.е., compat.text_type), она будет закодирована в массив байтов UTF-8, а все многобайтовые последовательности будут закодированы в процентах как есть.
Возвращает:	Экранированную версию uri, где все недопустимые символы закодированы в процентах.
Тип возвращаемого значения:	str

falcon.uri.decode(encoded_uri, unquote_plus=True) [source]

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

Эта функция моделирует поведение urllib.parse.unquote_plus, но более быстро и прямолинейно.

Параметры:	encoded_uri (str) – закодированный URI (полный или частичный).
Ключевые аргументы:
	unquote_plus (bool) – Установите в False чтобы сохранить все символы плюс (‘+’) в данной строке вместо их преобразования в пробелы (значение по умолчанию True). Обычно вы должны установить это в False при декодировании любой части URI, кроме строки запроса.
Возвращает:	Декодированный URL. Если 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=False, csv=True) [source]

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

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

Примечание

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

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

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

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

falcon.uri.unquote_string(quoted) [source]

Расквитировать строку «quoted-string» по RFC 7320.

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

Разное

falcon.deprecated(instructions) [source]

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

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

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

falcon.http_now() [source]

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

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

falcon.dt_to_http(dt) [source]

Преобразует экземпляр datetime в строку даты HTTP.

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

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

Преобразует строку даты HTTP в экземпляр datetime.

Параметры:	http_date (строка) – Строка даты RFC 1123, например: «Втр, 15 ноя 1994 12:45:26 GMT».
Ключевые аргументы:
	obs_date (логическое значение) – Поддержка форматов 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 (словарь) – Словарь параметров, где каждый ключ — имя параметра, а каждое значение — либо str или то, что может быть преобразовано в str, или список таких значений. Если list, значение будет преобразовано в строку значений, разделенных запятыми (например, ‘thing=1,2,3’). comma_delimited_lists (логическое значение) – Установите в False для кодирования значений списка, указав несколько экземпляров параметра (например, ‘thing=1&thing=2&thing=3’). В противном случае параметры будут закодированы как значения, разделенные запятыми (например, ‘thing=1,2,3’). По умолчанию True. prefix (логическое значение) – Установите в False для исключения префикса ‘?’ в результирующей строке (по умолчанию True).
Возвращает:	Строка запроса URI, включая префикс ‘?’ (если prefix не False), или пустая строка, если параметры отсутствуют (dict пуста).
Тип возвращаемого значения:	строка

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

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

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

falcon.get_bound_method(obj, method_name) [source]

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

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

class falcon.TimezoneGMT [source]

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

dst(dt) [source]

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

Параметры:	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

class falcon.Context [source]

Удобный класс для хранения контекстной информации в своих атрибутах.

Этот класс используется в качестве типа контекста по умолчанию для Request и Response (см. Request.context_type и Response.context_type, соответственно).

В версиях Falcon до 2.0 типом контекста по умолчанию был dict. Для облегчения миграции к объектному подходу контекста на основе атрибутов, этот класс также реализует интерфейс отображения; т.е. атрибуты объекта связаны с элементами словаря, и наоборот. Например:

>>> context = falcon.Context()
>>> context.cache_strategy = 'lru'
>>> context.get('cache_strategy')
'lru'
>>> 'cache_strategy' in context
True

Примечание

Специфичные для Python 2 методы dict доступны независимо от версии языка Python, однако, так как они делегируются подлежащему __dict__, аналогичная ошибка будет возникать, как если бы вы пытались использовать эти методы для обычного словаря Python 3.

class falcon.ETag [source]

Удобный класс для представления разобранного тега сущности HTTP.

Этот класс — просто подкласс str с несколькими вспомогательными методами и дополнительным атрибутом, указывающим, является ли тег сущности слабым или сильным. Значение строки эквивалентно тому, что RFC 7232 называет «непрозрачным тегом», т.е. тегу сущности без кавычек и индикатора слабости.

Примечание

Учитывая, что сравнение слабого тега сущности может быть выполнено с помощью оператора == (по примеру ниже), предоставляется только метод strong_compare().

Вот пример on_get() метода, демонстрирующего, как использовать экземпляры этого класса:

def on_get(self, req, resp):
    content_etag = self._get_content_etag()
    for etag in (req.if_none_match or []):
        if etag == '*' or etag == content_etag:
            resp.status = falcon.HTTP_304
            return

    # ...

    resp.etag = content_etag
    resp.status = falcon.HTTP_200

(См. также: RFC 7232)

is_weak

True если тег сущности слабый, иначе False.

Тип:	bool

dumps() [source]

Сериализует ETag в строку, подходящую для использования в заголовке условия.

(См. также: RFC 7232, Раздел 2.3)

Возвращает:	Прозрачная строка в кавычках, возможно, с префиксом индикатора слабости W/.
Тип возвращаемого значения:	str

classmethod loads(etag_str) [source]

Метод класса, который десериализует строку одного тега сущности из заголовка условия.

Примечание

Этот метод предназначен только для разбора одного тега сущности. Его нельзя использовать для разбора списка значений, разделенных запятыми.

(См. также: RFC 7232, Раздел 2.3)

Параметры:	etag_str (str) – ASCII строка, представляющая одиночный тег сущности, как определено в RFC 7232.
Возвращает:	Экземпляр ~.ETag, представляющий разобранный тег сущности.
Тип возвращаемого значения:	ETag

strong_compare(other) [source]

Выполняет сильное сравнение тегов сущностей.

Два тега сущностей эквивалентны, если оба не слабые и их непрозрачные теги совпадают символ за символом.

(См. также: RFC 7232, Раздел 2.3.2)

Параметры:	other (ETag) – Другой ETag для сравнения one. (this) –
Возвращает:	True если два тега сущностей совпадают, иначе False.
Тип возвращаемого значения:	bool