Getter¶
A “Getter” is an instance used by a backend to extract the authentication information from a falcon Request
.
-
class
falcon_auth2.
Getter
[source]¶ 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 theload()
method since it is defined as abstract. In these cases the sync version may just raise an exception.-
async_calls_sync_load
= None¶ Indicates if this Getter has an async load implementation that is not just a fallback to sync
load()
method, like the defaultload_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 thanNone
).
-
abstract
load
(req: falcon.request.Request, *, challenges: Optional[Iterable[str]] = None) → str[source]¶ Loads the specified attribute from the provided request.
If a getter cannot be used with the current request, a
BackendNotApplicable
is raised. Thechallenges
, when provided, will be added toWWW-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.
-
-
class
falcon_auth2.
HeaderGetter
(header_key: str)[source]¶ Returns the specified header from a request.
- Parameters
header_key (str) – the name of the header to load.
-
class
falcon_auth2.
AuthHeaderGetter
(auth_header_type: str, *, header_key: str = 'Authorization')[source]¶ 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"
.
-
class
falcon_auth2.
ParamGetter
(param_name: str)[source]¶ Returns the specified parameter from the request.
If the parameter appears multiple times an error will be raised.
Note
When the falcon
Request
optionRequestOptions.auto_parse_form_urlencoded
is set toTrue
, this getter can also retrieve parameter in the body of aform-urlencoded
request.- Parameters
param_name (str) – the name of the param to load.
-
class
falcon_auth2.
CookieGetter
(cookie_name: str)[source]¶ 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.
-
class
falcon_auth2.
MultiGetter
(getters: Iterable[falcon_auth2.getter.Getter])[source]¶ 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.