Module eoxserver.core.util.kvptools

This module contains the parameter decoder implementation for key-value-pair encoded URL parameters. See also Module eoxserver.core.util.decoders for general information on parameter decoders.

Decoding Schemas

KVP decoding schemas can be defined following the general rules for schemas defined in the Module eoxserver.core.util.decoders. The KVP decoder expects kvp_key for the location parameter and kvp_type for the type definition parameter. That means, KVP decoding schemas generally have the form:

PARAM_SCHEMA = {
    "<parameter_name>": {
        "kvp_key": "<kvp_key>",
        "kvp_type": "<type_definition>"
    },
    ...
}

where

The valid base type names for KVP decoders are:

  • string: the string value of the parameter is returned as is,
  • int: the value will be typecasted to an integer; an exception is raised if the cast fails
  • float: the value will be typecasted to a float; an exception is raised if the cast fails
  • stringlist: the value is expected to be a comma separated list; a list of strings will be returned
  • intlist: the value is expected to be a comma separated list of integers; a list of integers will be returned; if typecasting fails, an exception is raised
  • floatlist: the value is expected to be a comma separated list of floats; a list of floats will be returned; if typecasting fails, an exception is raised.

Minimum and maximum occurrences can be defined as described for the Module eoxserver.core.util.decoders and will be validated.

Classes

class eoxserver.core.util.kvptools.KVPDecoder

This class provides a parameter decoder for key-value-pair parameters.

KVPDecoder(params=None, schema=None)

The constructor accepts two optional arguments:

  • params is expected to be either an URL-encoded string or a django.http.QueryDict instance containing request parameter information
  • schema is expected to be a schema as described under Decoding Schemas above.
setParams(params)

This method accepts one mandatory parameter params which is expected to be either an URL-encoded string or a django.http.QueryDict instance containing request parameter information.

The input params is converted to a canonical format internally. This information can be retrieved using getParams().

setSchema(schema)

This method accepts a KVP decoding schema as described under Decoding Schemas above and sets the internal schema to this value. Note that the schema is validated only when getValue() or getValueStrict() are called. Invalid schemas will cause exceptions then.

getValue(expr, default=None)

This method accepts an expression expr and a default value default as input.

If no schema has been defined, expr will be interpreted as being the key of a key-value-pair. The string value of the last occurrence of the key will be returned; if the value is missing default is returned.

If a schema has been defined, expr will be looked up in the schema, and the according value will be returned. If it is not found, default will be returned.

This method raises a KVPKeyOccurrenceError if the minimum or maximum occurrence bounds for the given KVP key are violated. In case the raw value of the KVP could not be casted to the expected type KVPTypeError is raised. In case expr is not defined in the schema or an error in the schema definition is detected, InternalError is raised.

getValueStrict(expr)

This method accepts an expression expr as input.

If no schema has been defined, expr will be interpreted as being the key of a key-value-pair. The string value of the last occurrence of the key will be returned; if the value is missing KVPKeyNotFound will be raised.

If a schema has been defined, expr will be looked up in the schema, and the according value will be returned. If it is not found, KVPKeyNotFound will be raised.

This method raises a KVPKeyOccurrenceError if the minimum or maximum occurrence bounds for the given KVP key are violated. In case the raw value of the KVP could not be casted to the expected type KVPTypeError is raised. In case expr is not defined in the schema or an error in the schema definition is detected, InternalError is raised.

getParams()

Returns a dictionary of params. The keys of the dictionary correspond to the KVP keys provided, the values are lists of KVP values (this is to account for multiple definitions for the same KVP key).

getParamType()

Returns "kvp".