Utilities

URI Functions

falcon.util.uri.decode(encoded_uri)

Decodes percent-encoded characters in a URI or query string.

This function models the behavior of urllib.parse.unquote_plus, but is faster. It is also more robust, in that it will decode escaped UTF-8 mutibyte sequences.

Parameters:encoded_uri (str) – An encoded URI (full or partial). Returns:

A decoded URL. Will be of type unicode on Python 2 IFF the

URL contained escaped non-ASCII characters, in which case UTF-8 is assumed per RFC 3986.

Return type:str

falcon.util.uri.encode(uri)

Encodes a full or relative URI according to RFC 3986.

RFC 3986 defines a set of “unreserved” characters as well as a set of “reserved” characters used as delimiters. This function escapes all other “disallowed” characters by percent-encoding them.

Note

This utility is faster in the average case than the similar quote function found in urlib. It also strives to be easier to use by assuming a sensible default of allowed characters.

Parameters:uri (str) – URI or part of a URI to encode. If this is a wide string (i.e., six.text_type), it will be encoded to a UTF-8 byte array and any multibyte sequences will be percent-encoded as-is. Returns:

An escaped version of uri, where all disallowed characters

have been percent-encoded.

Return type:str

falcon.util.uri.encode_value(uri)

Encodes a value string according to RFC 3986.

Disallowed characters are percent-encoded in a way that models urllib.parse.quote(safe="~"). However, the Falcon function is faster in the average case than the similar quote function found in urlib. It also strives to be easier to use by assuming a sensible default of allowed characters.

All reserved characters are lumped together into a single set of “delimiters”, and everything in that set is escaped.

Note

RFC 3986 defines a set of “unreserved” characters as well as a set of “reserved” characters used as delimiters.

Parameters:uri (str) – URI fragment to encode. It is assumed not to cross delimiter boundaries, and so any reserved URI delimiter characters included in it will be escaped. If value is a wide string (i.e., six.text_type), it will be encoded to a UTF-8 byte array and any multibyte sequences will be percent-encoded as-is. Returns:

An escaped version of uri, where all disallowed characters

have been percent-encoded.

Return type:str

falcon.util.uri.parse_host(host, default_port=None)

Parse a canonical ‘host:port’ string into parts.

Parse a host string (which may or may not contain a port) into parts, taking into account that the string may contain either a domain name or an IP address. In the latter case, both IPv4 and IPv6 addresses are supported.

Parameters:

• host (str) – Host string to parse, optionally containing a port number.
• default_port (int, optional) – Port number to return when the host string does not contain one (default None).

Returns:

A parsed (host, port) tuple from the given

host string, with the port converted to an int. If the host string does not specify a port, default_port is used instead.

Return type:

tuple

falcon.util.uri.parse_query_string(query_string, keep_blank_qs_values=False)

Parse a query string into a dict.

Query string parameters are assumed to use standard form-encoding. Only parameters with values are parsed. for example, given ‘foo=bar&flag’, this function would ignore ‘flag’ unless the keep_blank_qs_values option is set.

Note

In addition to the standard HTML form-based method for specifying lists by repeating a given param multiple times, Falcon supports a more compact form in which the param may be given a single time but set to a list of comma-separated elements (e.g., ‘foo=a,b,c’).

When using this format, all commas uri-encoded will not be treated by Falcon as a delimiter. If the client wants to send a value as a list, it must not encode the commas with the values.

The two different ways of specifying lists may not be mixed in a single query string for the same parameter.

Parameters:

• query_string (str) – The query string to parse.
• keep_blank_qs_values (bool) – If set to True, preserves boolean fields and fields with no content as blank strings.

Returns:

A dictionary of (name, value) pairs, one per query

parameter. Note that value may be a single str, or a list of str.

Return type:

dict

Raises:

TypeError – query_string was not a str.

falcon.util.uri.unquote_string(quoted)

Unquote an RFC 7320 “quoted-string”.

Parameters:quoted (str) – Original quoted string Returns:unquoted string Return type:str Raises:TypeError – quoted was not a str.

Miscellaneous

falcon.deprecated(instructions)

Flags a method as deprecated.

This function returns a decorator which can be used to mark deprecated functions. Applying this decorator will result in a warning being emitted when the function is used.

Parameters:instructions (str) – Specific guidance for the developer, e.g.: ‘Please migrate to add_proxy(...)’‘

falcon.http_now()

Returns the current UTC time as an IMF-fixdate.

Returns:

The current UTC time as an IMF-fixdate,

e.g., ‘Tue, 15 Nov 1994 12:45:26 GMT’.

Return type:str

falcon.dt_to_http(dt)

Converts a datetime instance to an HTTP date string.

Parameters:dt (datetime) – A datetime instance to convert, assumed to be UTC. Returns:An RFC 1123 date string, e.g.: “Tue, 15 Nov 1994 12:45:26 GMT”. Return type:str

falcon.http_date_to_dt(http_date, obs_date=False)

Converts an HTTP date string to a datetime instance.

Parameters:

• http_date (str) – An RFC 1123 date string, e.g.: “Tue, 15 Nov 1994 12:45:26 GMT”.
• obs_date (bool, optional) – Support obs-date formats according to RFC 7231, e.g.: “Sunday, 06-Nov-94 08:49:37 GMT” (default False).

Returns:

A UTC datetime instance corresponding to the given

HTTP date.

Return type:

datetime

Raises:

ValueError – http_date doesn’t match any of the available time formats

falcon.to_query_str(params)

Converts a dictionary of params to a query string.

Parameters:params (dict) – A dictionary of parameters, where each key is a parameter name, and each value is either a str or something that can be converted into a str. If params is a list, it will be converted to a comma-delimited string of values (e.g., ‘thing=1,2,3’) Returns:

A URI query string including the ‘?’ prefix, or an empty string

if no params are given (the dict is empty).

Return type:str

class falcon.util.TimezoneGMT

GMT timezone class implementing the datetime.tzinfo interface.

dst(dt)

Return the daylight saving time (DST) adjustment.

Parameters:dt (datetime.datetime) – Ignored Returns:DST adjustment for GMT, which is always 0. Return type:datetime.timedelta

tzname(dt)

Get the name of this timezone.

Parameters:dt (datetime.datetime) – Ignored Returns:“GMT” Return type:str

utcoffset(dt)

Get the offset from UTC.

Parameters:dt (datetime.datetime) – Ignored Returns:

GMT offset, which is equivalent to UTC and

so is aways 0.

Return type:datetime.timedelta