Module eoxserver.core.util.decoders

This module contains interfaces and partial implementations for parameter decoding. These classes are primarily intended for OWS request parsing, therefore there are currently two concrete implementations:

The module documentation starts with a bit on type definitions in the schemas used by KVPDecoder and XMLDecoder.

Schemas

EOxServer parameter decoders use schemas to define how to obtain the values for given parameter names or keys; these schemas are defined as Python dictionaries which follow certain rules. The basic structure of a schema is as follows:

PARAM_SCHEMA = {
    "<parameter_name>": {
        "<location_parameter>": "<location>",
        "<type_parameter>": "<type_definition>",
        ["<optional_parameter>": <optional_value>, ...]
    }
}

where

  • parameter_name denotes the name that can be used to retrieve the parameter value in calls to getValue() or getValueStrict(),
  • location_parameter denotes the name defined by the concrete decoder implementation for the location parameter, e.g. kvp_key for KVP Decoders,
  • location denotes the location string which must be provided by the developer in a format defined by the decoder implementation, e.g. an XPath expression for XML Decoders,
  • type_parameter denotes the name defined by the concrete decoder implementation for the type parameter, e.g. kvp_type for KVP decoders
  • type_definition denotes a type definition string formed according to the rules below to be provided by the developer,
  • optional parameters may be defined by the decoder implementations.

Type definition strings have a common format. They consist of a basetype definition followed by an optional occurrence definition. The most straightforward way is to simply define a parameter which is expected to occur exactly once:

"<base_type_name>"

The type of the return value is determined by the base_type_name you choose. Now that was easy.

For validation purposes you might want to add an occurrence definition. This means you specify minimum and/or maximum expected occurrence for the parameters. The call to getValue() and “~.Decoder.getValueStrict` will fail if the actual occurrence of the parameter is outside the bounds defined in the schema. A list will be returned in case the defined maximum occurrence exceeds 1.

The occurrences are declared in square brackets following the base_type_name:

"<base_type_name>[<min_occ>:<max_occ>]"

The parameters min_occ and max_occ must be castable to integers and will be translated to the expected minimum and maximum occurrences respectively. This is the strictest form of occurrence definitions, but there are shortcuts.

Omitting min_occ is allowed; minimum occurrence is then set to 0. Omitting max_occ is allowed, meaning the occurrence is unbounded. The occurrence definition may contain only a single occurrence value, meaning the parameter is expected exactly occ times:

"<base_type_name>[<occ>]"

And finally empty brackets mean arbitrary occurrence:

"<base_type_name>[]"

Important

Occurrence definitions always refer to the occurrence of the parameter itself, and never to its content. For intlist and similar base types they do not refer to the length of the parameter list! So intlist[2] does not denote a list of two integer values, but a list containing two lists of integer values each with arbitrary length.

Interfaces

class eoxserver.core.util.decoders.DecoderInterface

This is the common interface for request parameter decoding.

setParams(params)

This method shall set the parameters object to be parsed by the decoder implementation

setSchema(schema)

This method shall set the schema used by the decoder instance for parsing the parameters object. The input is expected to be a dictionary that represents the schema.

getValueStrict(expr)

This method shall return a parameter value according to the expression expr.

MissingParameterException or one of its descendants shall be raised if the requested value could not be found in the parameters.

InvalidParameterException or one of its descendants shall be raised if:

  • the requested value could not be converted to the expected type
  • the occurrence bounds given by the schema are violated
  • some other validation of the content defined in the schema fails

InternalError shall be raised in case the expression expr is invalid.

getValue(expr, default=None)

This method shall return a parameter value according to the expression expr.

It shall the optional default value or None if the requested value could not be found in the parameters.

InvalidParameterException or one of its descendants shall be raised if:

  • the requested value cannot be converted to the expected type
  • the occurrence bounds given by the schema are violated
  • some other validation of the content defined in the schema fails
getParams()

This method shall return the parameters object the decoder is parsing.

getParamType()

This method shall return the a significative code for the type of parameters the decoder is operating on.

Implementations

class eoxserver.core.util.decoders.Decoder(params=None, schema=None)

This is a partial implementation of the DecoderInterface which defines the basic structure of parameter decoders. It provides canonical implementations of getValueStrict(), getValue() and the constructor as well as private methods for schema parsing support.

getParamType()

This method is required by the interface definition. It shall return a significative code for the type of parameters the decoder is operating on. It must be overridden by concrete implementations. It raises InternalError by default.

getParams()

This method is required by the interface definition. It shall return the parameters object the decoder implementation is parsing. It must be overridden by concrete implementations. It raises InternalError by default.

getValue(expr, default=None)

This method is required by the interface definition. It invokes getValueStrict(), but returns None or an optional default value in case the parameter is not found.

getValueStrict(expr)

This method is required by the interface definition. It returns the parsing result for the given expression expr. Any occurring exceptions will be passed on to the caller.

The method invokes either _getValueSchema() if a schema has been defined or _getValueDefault() otherwise.

setParams(params)

This method is required by the interface definition. It shall set the parameters object to be parsed by the decoder. It may also validate and prepare parsing of the input. It must be overridden by the concrete implementations; InternalError is raised by default.

setSchema(schema)

This method is required by the interface definition. It shall set the schema used for parsing. It can be overidden by the implementations in order to validate and parse he schema.