def get_param(self, name, required=False, store=None, default=None):
"""Return the raw value of a query string parameter as a string.
Note:
If an HTML form is POSTed to the API using the
*application/x-www-form-urlencoded* media type, the
parameters from the request body will be merged into
the query string parameters.
If a key appears more than once in the form data, one of the
values will be returned as a string, but it is undefined which
one. Use `req.get_param_as_list()` to retrieve all the values.
Note:
Similar to the way multiple keys in form data is handled,
if a query parameter is assigned a comma-separated list of
values (e.g., 'foo=a,b,c'), only one of those values will be
returned, and it is undefined which one. Use
`req.get_param_as_list()` to retrieve all the values.
Args:
name (str): Parameter name, case-sensitive (e.g., 'sort').
required (bool, optional): Set to ``True`` to raise
``HTTPBadRequest`` instead of returning ``None`` when the
parameter is not found (default ``False``).
store (dict, optional): A ``dict``-like object in which to place
the value of the param, but only if the param is present.
default (any, optional): If the param is not found returns the
given value instead of None
Returns:
str: The value of the param as a string, or ``None`` if param is
not found and is not required.
Raises:
HTTPBadRequest: A required param is missing from the request.
"""
params = self._params
# PERF: Use if..in since it is a good all-around performer; we don't
# know how likely params are to be specified by clients.
if name in params:
# NOTE(warsaw): If the key appeared multiple times, it will be
# stored internally as a list. We do not define which one
# actually gets returned, but let's pick the last one for grins.
param = params[name]
if isinstance(param, list):
param = param[-1]
if store is not None:
store[name] = param
return param
if not required:
return default
raise errors.HTTPMissingParam(name)
def require_params(self, req):
"""
Require all parameters from request that are defined for this resource.
Raises ``falcon.errors.HTTPMissingParam`` exception if any of required
parameters is missing and ``falcon.errors.HTTPInvalidParam`` if any
of parameters could not be understood (wrong format).
Args:
req (falcon.Request): request object
"""
# TODO: handle specifying parameter multiple times in query string!
params = {}
for name, param in self.params.items():
if name not in req.params and param.required:
# we could simply raise with this single param or use get_param
# with required=True parameter but for client convenience
# we prefer to list all missing params that are required
missing = set(
p for p in self.params if self.params[p].required) - set(
req.params.keys())
raise errors.HTTPMissingParam(", ".join(missing))
elif name in req.params or param.default:
# Note: lack of key in req.params means it was not specified
# so unless there is default value it will not be included in
# output params dict.
# This way we have explicit information that param was
# not specified. Using None would not be as good because param
# class can also return None from `.value()` method as a valid
# translated value.
try:
if param.many:
# params with "many" enabled need special care
params[name] = req.get_param_as_list(
name,
param.value,
) or [param.default and param.value(param.default)]
else:
# note that if many==False and query parameter
# occurs multiple times in qs then it is
# **unspecified** which one will be used. See:
# http://falcon.readthedocs.org/en/latest/api/request_and_response.html#falcon.Request.get_param # noqa
params[name] = param.value(
req.get_param(name, default=param.default))
except ValueError as err:
raise errors.HTTPInvalidParam(str(err), name)
return params
def get_param_as_bool(self, name, required=False, store=None,
blank_as_true=False):
"""Return the value of a query string parameter as a boolean
The following boolean strings are supported::
TRUE_STRINGS = ('true', 'True', 'yes', '1')
FALSE_STRINGS = ('false', 'False', 'no', '0')
Args:
name (str): Parameter name, case-sensitive (e.g., 'detailed').
required (bool, optional): Set to ``True`` to raise
``HTTPBadRequest`` instead of returning ``None`` when the
parameter is not found or is not a recognized boolean
string (default ``False``).
store (dict, optional): A ``dict``-like object in which to place
the value of the param, but only if the param is found (default
``None``).
blank_as_true (bool): If ``True``, an empty string value will be
treated as ``True``. Normally empty strings are ignored; if
you would like to recognize such parameters, you must set the
`keep_blank_qs_values` request option to ``True``. Request
options are set globally for each instance of ``falcon.API``
through the `req_options` attribute.
Returns:
bool: The value of the param if it is found and can be converted
to a ``bool``. If the param is not found, returns ``None``
unless required is ``True``.
Raises:
HTTPBadRequest: A required param is missing from the request.
"""
params = self._params
# PERF: Use if..in since it is a good all-around performer; we don't
# know how likely params are to be specified by clients.
if name in params:
val = params[name]
if isinstance(val, list):
val = val[-1]
if val in TRUE_STRINGS:
val = True
elif val in FALSE_STRINGS:
val = False
elif blank_as_true and not val:
val = True
else:
msg = 'The value of the parameter must be "true" or "false".'
raise errors.HTTPInvalidParam(msg, name)
if store is not None:
store[name] = val
return val
if not required:
return None
raise errors.HTTPMissingParam(name)
def get_param_as_int(self, name,
required=False, min=None, max=None, store=None):
"""Return the value of a query string parameter as an int.
Args:
name (str): Parameter name, case-sensitive (e.g., 'limit').
required (bool, optional): Set to ``True`` to raise
``HTTPBadRequest`` instead of returning ``None`` when the
parameter is not found or is not an integer (default
``False``).
min (int, optional): Set to the minimum value allowed for this
param. If the param is found and it is less than min, an
``HTTPError`` is raised.
max (int, optional): Set to the maximum value allowed for this
param. If the param is found and its value is greater than
max, an ``HTTPError`` is raised.
store (dict, optional): A ``dict``-like object in which to place
the value of the param, but only if the param is found
(default ``None``).
Returns:
int: The value of the param if it is found and can be converted to
an integer. If the param is not found, returns ``None``, unless
`required` is ``True``.
Raises
HTTPBadRequest: The param was not found in the request, even though
it was required to be there. Also raised if the param's value
falls outside the given interval, i.e., the value must be in
the interval: min <= value <= max to avoid triggering an error.
"""
params = self._params
# PERF: Use if..in since it is a good all-around performer; we don't
# know how likely params are to be specified by clients.
if name in params:
val = params[name]
if isinstance(val, list):
val = val[-1]
try:
val = int(val)
except ValueError:
msg = 'The value must be an integer.'
raise errors.HTTPInvalidParam(msg, name)
if min is not None and val < min:
msg = 'The value must be at least ' + str(min)
raise errors.HTTPInvalidParam(msg, name)
if max is not None and max < val:
msg = 'The value may not exceed ' + str(max)
raise errors.HTTPInvalidParam(msg, name)
if store is not None:
store[name] = val
return val
if not required:
return None
raise errors.HTTPMissingParam(name)
def get_param_as_list(self, name,
transform=None, required=False, store=None):
"""Return the value of a query string parameter as a list.
List items must be comma-separated or must be provided
as multiple instances of the same param in the query string
ala *application/x-www-form-urlencoded*.
Args:
name (str): Parameter name, case-sensitive (e.g., 'ids').
transform (callable, optional): An optional transform function
that takes as input each element in the list as a ``str`` and
outputs a transformed element for inclusion in the list that
will be returned. For example, passing ``int`` will
transform list items into numbers.
required (bool, optional): Set to ``True`` to raise
``HTTPBadRequest`` instead of returning ``None`` when the
parameter is not found (default ``False``).
store (dict, optional): A ``dict``-like object in which to place
the value of the param, but only if the param is found (default
``None``).
Returns:
list: The value of the param if it is found. Otherwise, returns
``None`` unless required is True. Empty list elements will be
discarded. For example, the following query strings would
both result in `['1', '3']`::
things=1,,3
things=1&things=&things=3
Raises:
HTTPBadRequest: A required param is missing from the request.
HTTPInvalidParam: A transform function raised an instance of
``ValueError``.
"""
params = self._params
# PERF: Use if..in since it is a good all-around performer; we don't
# know how likely params are to be specified by clients.
if name in params:
items = params[name]
# NOTE(warsaw): When a key appears multiple times in the request
# query, it will already be represented internally as a list.
# NOTE(kgriffs): Likewise for comma-delimited values.
if not isinstance(items, list):
items = [items]
# PERF(kgriffs): Use if-else rather than a DRY approach
# that sets transform to a passthrough function; avoids
# function calling overhead.
if transform is not None:
try:
items = [transform(i) for i in items]
except ValueError:
msg = 'The value is not formatted correctly.'
raise errors.HTTPInvalidParam(msg, name)
if store is not None:
store[name] = items
return items
if not required:
return None
raise errors.HTTPMissingParam(name)
