Getter

A “Getter” is an instance used by a backend to extract the authentication information from a falcon Request.

Getter

class falcon_auth2.Getter

Represents a class that extracts authentication information from a request.

Note

Subclasses that wish to only support the load_async() method are also required to override the load() method since it is defined as abstract. In these cases the sync version may just raise an exception.

async_calls_sync_load: ClassVar[bool | None] = None

Indicates if this Getter has an async load implementation that is not just a fallback to sync load() method, like the default load_async() method.

This property is automatically set by the Getter when a subclass is defined (using __init_subclass__) if not specified directly by a subclass (by setting it to a valued different than None).

abstractmethod load(req: Request, *, challenges: Iterable[str] | None = None) → str

Loads the specified attribute from the provided request.

If a getter cannot be used with the current request, a BackendNotApplicable is raised. The challenges, when provided, will be added to WWW-Authenticate header in case of error.

Parameters:

req (Request) – The current request. This may be a wsgi or an asgi falcon request.

Keyword Arguments:

challenges (Optional[Iterable[str]], optional) – One or more authentication challenges to use as the value of the WWW-Authenticate header in case of errors.

Returns:

str – The loaded data, in case of success.

async load_async(req: Request, *, challenges: Iterable[str] | None = None) → str

Async version of load(). The default implementation simply calls load(), but subclasses may override this implementation to provide an async version.

HeaderGetter

class falcon_auth2.HeaderGetter(header_key: str)

Returns the specified header from a request.

Parameters:

header_key (str) – the name of the header to load.

async_calls_sync_load: ClassVar[bool | None] = True

Indicates if this Getter has an async load implementation that is not just a fallback to sync load() method, like the default load_async() method.

This property is automatically set by the Getter when a subclass is defined (using __init_subclass__) if not specified directly by a subclass (by setting it to a valued different than None).

load(req: Request, *, challenges: Iterable[str] | None = None) → str

Loads the header from the provided request

AuthHeaderGetter

class falcon_auth2.AuthHeaderGetter(auth_header_type: str, *, header_key: str = 'Authorization')

Returns the auth header from a request, checking that it in the form <auth_header_type> value.

Parameters:

auth_header_type (str) – The type of the auth header. Common values are "Basic", "Bearer".

Keyword Arguments:

header_key (str, optional) – The name of the header to load. Defaults to "Authorization".

async_calls_sync_load: ClassVar[bool | None] = True

Indicates if this Getter has an async load implementation that is not just a fallback to sync load() method, like the default load_async() method.

This property is automatically set by the Getter when a subclass is defined (using __init_subclass__) if not specified directly by a subclass (by setting it to a valued different than None).

load(req: Request, *, challenges: Iterable[str] | None = None) → str

Loads the auth header from the provided request

ParamGetter

class falcon_auth2.ParamGetter(param_name: str)

Returns the specified parameter from the request.

If the parameter appears multiple times an error will be raised.

Note

When the falcon Request option RequestOptions.auto_parse_form_urlencoded is set to True, this getter can also retrieve parameter in the body of a form-urlencoded request.

Parameters:

param_name (str) – the name of the param to load.

async_calls_sync_load: ClassVar[bool | None] = True

Indicates if this Getter has an async load implementation that is not just a fallback to sync load() method, like the default load_async() method.

This property is automatically set by the Getter when a subclass is defined (using __init_subclass__) if not specified directly by a subclass (by setting it to a valued different than None).

load(req: Request, *, challenges: Iterable[str] | None = None) → str

Loads the parameter from the provided request

CookieGetter

class falcon_auth2.CookieGetter(cookie_name: str)

Returns the specified cookie from the request.

If the cookie appears multiple times an error will be raised.

Parameters:

cookie_name (str) – the name of the cookie to load.

async_calls_sync_load: ClassVar[bool | None] = True

Indicates if this Getter has an async load implementation that is not just a fallback to sync load() method, like the default load_async() method.

This property is automatically set by the Getter when a subclass is defined (using __init_subclass__) if not specified directly by a subclass (by setting it to a valued different than None).

load(req: Request, *, challenges: Iterable[str] | None = None) → str

Loads the cookie from the provided request

MultiGetter

class falcon_auth2.MultiGetter(getters: Iterable[Getter])

Combines multiple getters. This is useful if a value can be passed in multiple ways to the server, like using an header or a query parameter.

Will use the first value successfully returned, ignoring all BackendNotApplicable exceptions raised by the previously tried getters. If no getter can return a valid value an exception will only be raised.

Parameters:

getters (Iterable[Getter]) – The getters to use. They will be tried in order and the first value successfully returned is used.

async_calls_sync_load: ClassVar[bool | None] = True

Indicates if this Getter has an async load implementation that is not just a fallback to sync load() method, like the default load_async() method.

This property is automatically set by the Getter when a subclass is defined (using __init_subclass__) if not specified directly by a subclass (by setting it to a valued different than None).

load(req: Request, *, challenges: Iterable[str] | None = None) → str

Loads the value from the provided request using the provided getters

async load_async(req: Request, *, challenges: Iterable[str] | None = None) → str

Async version of load().

Makes sure load is called inside a greenlet spawn context