Utilities

URI

URI utilities.

This module provides utility functions to parse, encode, decode, and otherwise manipulate a URI. These functions are not available directly in the falcon module, and so must be explicitly imported:

from falcon import uri

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

falcon.uri.decode(encoded_uri: str, unquote_plus: bool = True) → str

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

This function models the behavior of urllib.parse.unquote_plus, albeit in a faster, more straightforward manner.

Parameters:

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

Keyword Arguments:

unquote_plus (bool) – Set to False to retain any plus (‘+’) characters in the given string, rather than converting them to spaces (default True). Typically you should set this to False when decoding any part of a URI other than the query string.

Returns:

A decoded URL. If the URL contains escaped non-ASCII characters, UTF-8 is assumed per RFC 3986.

Return type:

str

falcon.uri.encode(uri: str) → str

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.

Returns:

An escaped version of uri, where all disallowed characters have been percent-encoded.

Return type:

str

falcon.uri.encode_check_escaped(uri: str) → str

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 unless they appear to have been previously encoded. For example, '%26' will not be encoded again as it follows the format of an encoded value.

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.

Returns:

An escaped version of uri, where all disallowed characters have been percent-encoded.

Return type:

str

falcon.uri.encode_value(uri: str) → str

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 percent-encoded.

Returns:

An escaped version of uri, where all disallowed characters have been percent-encoded.

Return type:

str

falcon.uri.encode_value_check_escaped(uri: str) → str

Encodes a value string according to RFC 3986.

RFC 3986 defines a set of “unreserved” characters as well as a set of “reserved” characters used as delimiters. Disallowed characters are percent-encoded in a way that models urllib.parse.quote(safe="~") unless they appear to have been previously encoded. For example, '%26' will not be encoded again as it follows the format of an encoded value.

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

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 fragment to encode. It is assumed not to cross delimiter boundaries, and so any reserved URI delimiter characters included in it will be percent-encoded.

Returns:

An escaped version of uri, where all disallowed characters have been percent-encoded.

Return type:

str

falcon.uri.parse_host(host: str, default_port: int | None = None) → Tuple[str, int | 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.

Keyword Arguments:

default_port (int) – 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.uri.parse_query_string(query_string: str, keep_blank: bool = False, csv: bool = False) → Dict[str, str | List[str]]

Parse a query string into a dict.

Query string parameters are assumed to use standard form-encoding. Only parameters with values are returned. For example, given ‘foo=bar&flag’, this function would ignore ‘flag’ unless the keep_blank 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’). This comma-separated format can be enabled by setting the csv option (see below) to True.

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 (bool) – Set to True to return fields even if they do not have a value (default False). For comma-separated values, this option also determines whether or not empty elements in the parsed list are retained.

• csv – Set to True in order to enable splitting query parameters on , (default False). Depending on the user agent, encoding lists as multiple occurrences of the same parameter might be preferable. In this case, keeping parse_qs_csv at its default value (False) will cause the framework to treat commas as literal characters in each occurring parameter value.

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.uri.unquote_string(quoted: str) → str

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.

Date and Time

falcon.http_now() → str

Return 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: datetime) → str

Convert 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: str, obs_date: bool = False) → datetime

Convert 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”.

Keyword Arguments:

obs_date (bool) – 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

class falcon.TimezoneGMT

GMT timezone class implementing the datetime.tzinfo interface.

dst(dt: datetime | None) → timedelta

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: datetime | None) → str

Get the name of this timezone.

Parameters:

dt (datetime.datetime) – Ignored

Returns:

“GMT”

Return type:

str

utcoffset(dt: datetime | None) → timedelta

Get the offset from UTC.

Parameters:

dt (datetime.datetime) – Ignored

Returns:

GMT offset, which is equivalent to UTC and so is always 0.

Return type:

datetime.timedelta

HTTP Status

falcon.http_status_to_code(status: HTTPStatus | int | bytes | str) → int

Normalize an HTTP status to an integer code.

This function takes a member of http.HTTPStatus, an HTTP status line string or byte string (e.g., '200 OK'), or an int and returns the corresponding integer code.

An LRU is used to minimize lookup time.

Parameters:

status – The status code or enum to normalize.

Returns:

Integer code for the HTTP status (e.g., 200)

Return type:

int

falcon.code_to_http_status(status: int | HTTPStatus | bytes | str) → str

Normalize an HTTP status to an HTTP status line string.

This function takes a member of http.HTTPStatus, an int status code, an HTTP status line string or byte string (e.g., '200 OK') and returns the corresponding HTTP status line string.

An LRU is used to minimize lookup time.

Note

Unlike the deprecated get_http_status(), this function will not attempt to coerce a string status to an integer code, assuming the string already denotes an HTTP status line.

Parameters:

status – The status code or enum to normalize.

Returns:

HTTP status line corresponding to the given code. A newline

is not included at the end of the string.

Return type:

str

falcon.get_http_status(status_code: str | int, default_reason: str = 'Unknown') → str

Get both the http status code and description from just a code.

Warning

As of Falcon 3.0, this method has been deprecated in favor of code_to_http_status().

Parameters:

• status_code – integer or string that can be converted to an integer

• default_reason – default text to be appended to the status_code if the lookup does not find a result

Returns:

status code e.g. “404 Not Found”

Return type:

str

Raises:

ValueError – the value entered could not be converted to an integer

Media types

falcon.parse_header(line: str) → Tuple[str, dict]

Parse a Content-type like header.

Return the main content-type and a dictionary of options.

Parameters:

line – A header value to parse.

Returns:

(the main content-type, dictionary of options).

Return type:

tuple

Note

This function replaces an equivalent method previously available in the stdlib as cgi.parse_header(). It was removed from the stdlib in Python 3.13.

Async

Aliases

These functions provide simple aliases for those implemented in asyncio, with fallbacks for older versions of Python.

falcon.get_running_loop()

Return the running event loop. Raise a RuntimeError if there is none.

This function is thread-specific.

falcon.create_task(coro, *, name=None)

Schedule the execution of a coroutine object in a spawn task.

Return a Task object.

Adapters

These functions help traverse the barrier between sync and async code.

async falcon.sync_to_async(func: Callable[[...], Any], *args: Any, **kwargs: Any) → Callable[[...], Awaitable[Any]]

Schedule a synchronous callable on the default executor and await the result.

This helper makes it easier to call functions that can not be ported to use async natively (e.g., functions exported by a database library that does not yet support asyncio).

To execute blocking operations safely, without stalling the async loop, the wrapped callable is scheduled to run in the background, on a separate thread, when the wrapper is called.

The default executor for the running loop is used to schedule the synchronous callable.

Warning

This helper can only be used to execute thread-safe callables. If the callable is not thread-safe, it can be executed serially by first wrapping it with wrap_sync_to_async(), and then executing the wrapper directly.

Warning

Calling a synchronous function safely from an asyncio event loop adds a fair amount of overhead to the function call, and should only be used when a native async library is not available for the operation you wish to perform.

Parameters:

• func (callable) – Function, method, or other callable to wrap

• *args – All additional arguments are passed through to the callable.

Keyword Arguments:

**kwargs – All keyword arguments are passed through to the callable.

Returns:

An awaitable coroutine function that wraps the synchronous callable.

Return type:

function

falcon.wrap_sync_to_async(func: Callable[[...], Any], threadsafe: bool | None = None) → Callable[[...], Any]

Wrap a callable in a coroutine that executes the callable in the background.

This helper makes it easier to call functions that can not be ported to use async natively (e.g., functions exported by a database library that does not yet support asyncio).

To execute blocking operations safely, without stalling the async loop, the wrapped callable is scheduled to run in the background, on a separate thread, when the wrapper is called.

Normally, the default executor for the running loop is used to schedule the synchronous callable. If the callable is not thread-safe, it can be scheduled serially in a global single-threaded executor.

Warning

Wrapping a synchronous function safely adds a fair amount of overhead to the function call, and should only be used when a native async library is not available for the operation you wish to perform.

Parameters:

func (callable) – Function, method, or other callable to wrap

Keyword Arguments:

threadsafe (bool) – Set to False when the callable is not thread-safe (default True). When this argument is False, the wrapped callable will be scheduled to run serially in a global single-threaded executor.

Returns:

An awaitable coroutine function that wraps the synchronous callable.

Return type:

function

falcon.wrap_sync_to_async_unsafe(func: Callable[[...], Any]) → Callable[[...], Any]

Wrap a callable in a coroutine that executes the callable directly.

This helper makes it easier to use synchronous callables with ASGI apps. However, it is considered “unsafe” because it calls the wrapped function directly in the same thread as the asyncio loop. Generally, you should use wrap_sync_to_async() instead.

Warning

This helper is only to be used for functions that do not perform any blocking I/O or lengthy CPU-bound operations, since the entire async loop will be blocked while the wrapped function is executed. For a safer, non-blocking alternative that runs the function in a thread pool executor, use sync_to_async() instead.

Parameters:

func (callable) – Function, method, or other callable to wrap

Returns:

An awaitable coroutine function that wraps the synchronous callable.

Return type:

function

falcon.async_to_sync(coroutine: Callable[[...], Awaitable[Result]], *args: Any, **kwargs: Any) → Result

Invoke a coroutine function from a synchronous caller.

This method can be used to invoke an asynchronous task from a synchronous context. The coroutine will be scheduled to run on the current event loop for the current OS thread. If an event loop is not already running, one will be created.

Warning

Executing async code in this manner is inefficient since it involves synchronization via threading primitives, and is intended primarily for testing, prototyping or compatibility purposes.

Note

On Python 3.11+, this function leverages a module-wide asyncio.Runner.

Parameters:

• coroutine – A coroutine function to invoke.

• *args – Additional args are passed through to the coroutine function.

Keyword Arguments:

**kwargs – Additional args are passed through to the coroutine function.

falcon.runs_sync(coroutine: Callable[[...], Awaitable[Result]]) → Callable[[...], Result]

Transform a coroutine function into a synchronous method.

This is achieved by always invoking the decorated coroutine function via async_to_sync().

Warning

This decorator is very inefficient and should only be used for adapting asynchronous test functions for use with synchronous test runners such as pytest or the unittest module.

It will create an event loop for the current thread if one is not already running.

Parameters:

coroutine – A coroutine function to masquerade as a synchronous one.

Returns:

A synchronous function.

Return type:

callable

Other

falcon.util.deprecated(instructions: str, is_property: bool = False, method_name: str | None = None) → Callable[[Callable[[...], Any]], Any]

Flag 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(…)’.

• is_property (bool) – If the deprecated object is a property. It will omit the (...) from the generated documentation.

• method_name (str, optional) – Set to override the name of the deprecated function or property in the generated documentation (default None). This is useful when decorating an alias that carries the target’s __name__.

falcon.util.deprecated_args(*, allowed_positional: int, is_method: bool = True) → Callable[[...], Callable[[...], Any]]

Flag a method call with positional args as deprecated.

Keyword Arguments:

• allowed_positional (int) – Number of allowed positional arguments

• is_method (bool, optional) – The decorated function is a method. Will add one to the number of allowed positional args to account for self. Defaults to True.

falcon.to_query_str(params: dict, comma_delimited_lists: bool = True, prefix: bool = True) → str

Convert a dictionary of parameters 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, or a list of such values. If a list, the value will be converted to a comma-delimited string of values (e.g., ‘thing=1,2,3’).

• comma_delimited_lists (bool) – Set to False to encode list values by specifying multiple instances of the parameter (e.g., ‘thing=1&thing=2&thing=3’). Otherwise, parameters will be encoded as comma-separated values (e.g., ‘thing=1,2,3’). Defaults to True.

• prefix (bool) – Set to False to exclude the ‘?’ prefix in the result string (default True).

Returns:

A URI query string, including the ‘?’ prefix (unless prefix is False), or an empty string if no params are given (the dict is empty).

Return type:

str

falcon.get_bound_method(obj: object, method_name: str) → None | Callable[[...], Any]

Get a bound method of the given object by name.

Parameters:

• obj – Object on which to look up the method.

• method_name – Name of the method to retrieve.

Returns:

Bound method, or None if the method does not exist on the object.

Raises:

AttributeError – The method exists, but it isn’t bound (most likely a class was passed, rather than an instance of that class).

falcon.secure_filename(filename: str) → str

Sanitize the provided filename to contain only ASCII characters.

Only ASCII alphanumerals, '.', '-' and '_' are allowed for maximum portability and safety wrt using this name as a filename on a regular file system. All other characters will be replaced with an underscore ('_').

Note

The filename is normalized to the Unicode NKFD form prior to ASCII conversion in order to extract more alphanumerals where a decomposition is available. For instance:

>>> secure_filename('Bold Digit 𝟏')
'Bold_Digit_1'
>>> secure_filename('Ångström unit physics.pdf')
'A_ngstro_m_unit_physics.pdf'

Parameters:

filename (str) – Arbitrary filename input from the request, such as a multipart form filename field.

Returns:

The sanitized filename.

Return type:

str

Raises:

ValueError – the provided filename is an empty string.

falcon.is_python_func(func: Callable | Any) → bool

Determine if a function or method uses a standard Python type.

This helper can be used to check a function or method to determine if it uses a standard Python type, as opposed to an implementation-specific native extension type.

For example, because Cython functions are not standard Python functions, is_python_func(f) will return False when f is a reference to a cythonized function or method.

Parameters:

func – The function object to check.

Returns:

True if the function or method uses a standard Python type; False otherwise.

Return type:

bool

class falcon.Context

Convenience class to hold contextual information in its attributes.

This class is used as the default Request and Response context type (see Request.context_type and Response.context_type, respectively).

In Falcon versions prior to 2.0, the default context type was dict. To ease the migration to attribute-based context object approach, this class also implements the mapping interface; that is, object attributes are linked to dictionary items, and vice versa. For instance:

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

class falcon.ETag

Convenience class to represent a parsed HTTP entity-tag.

This class is simply a subclass of str with a few helper methods and an extra attribute to indicate whether the entity-tag is weak or strong. The value of the string is equivalent to what RFC 7232 calls an “opaque-tag”, i.e. an entity-tag sans quotes and the weakness indicator.

Note

Given that a weak entity-tag comparison can be performed by using the == operator (per the example below), only a strong_compare() method is provided.

Here is an example on_get() method that demonstrates how to use instances of this class:

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

    # -- snip --

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

(See also: RFC 7232)

is_weak

True if the entity-tag is weak, otherwise False.

Type:

bool

dumps() → str

Serialize the ETag to a string suitable for use in a precondition header.

(See also: RFC 7232, Section 2.3)

Returns:

An opaque quoted string, possibly prefixed by a weakness indicator W/.

Return type:

str

classmethod loads(etag_str: str) → ETag

Deserialize a single entity-tag string from a precondition header.

Note

This method is meant to be used only for parsing a single entity-tag. It can not be used to parse a comma-separated list of values.

(See also: RFC 7232, Section 2.3)

Parameters:

etag_str (str) – An ASCII string representing a single entity-tag, as defined by RFC 7232.

Returns:

An instance of ~.ETag representing the parsed entity-tag.

Return type:

ETag

strong_compare(other: ETag) → bool

Perform a strong entity-tag comparison.

Two entity-tags are equivalent if both are not weak and their opaque-tags match character-by-character.

(See also: RFC 7232, Section 2.3.2)

Parameters:

• other (ETag) – The other ETag to which you are comparing

• one. (this)

Returns:

True if the two entity-tags match, otherwise False.

Return type:

bool