kepler.api.api_util module

The module contains functionality for automating the implementation of the REST API.

class kepler.api.api_util.ApiDateParam(value=None, optional=False, doc=None)

Bases: kepler.api.api_util.ApiParam

A convenience class for date parameters. Automatically casts the value to python datetime.datetime.

class kepler.api.api_util.ApiParam(value=None, cast=None, optional=False, doc=None)

Bases: object

The utility class is used to both document and implement REST API calls.

Initialize the API parameter.

Parameters:
  • value – Optional default value for the parameter.
  • cast – Optional cast function that is called for the parameter value.
  • optional – Specifies if this parameter is optional or not.
  • doc – The documentation string for the parameter in reStructuredText format.
cast = None

Optional cast function that is called for the parameter value.

doc = None

The REST API documentation for this call parameter.

get_value(name, value)

Gets the value of the parameter. If the parameter is not optional and value is None, the method raises a ValueError exception.

Parameters:
  • name – The name of the parameter.
  • value – The value of the parameter.
Raises ValueError:
 

If the value is not optional, but the value is None. Also when the self.cast is not None and casting fails with ValueError a new ValueError is raised.
optional = False

Specifies, if the parameter is optional or not.

value = None

The default value of the parameter.

class kepler.api.api_util.ApiParamObject

Bases: object

The object holds all REST API parameters parsed from the request body.

set_attribute(name, value)

Sets the attribute with the specified name.

Parameters:
  • name – The name of the attribute.
  • value – The value of the attribute.
class kepler.api.api_util.ApiParamsBase

Bases: object

The base class for API parameter classes.

get_names()

Returns all parameter names of this parameter class.

get_params()

Returns all parameters of this parameter class as name-attribute pairs.

read_from_json(json)

Reads the parameters from the given JSON object (dictionary).

If the json parameter is None (i.e. the JSON object was null) and there were any non-optional parameters, throws ValueError. Otherwise uses defaults for parameters that are not found or are null in the JSON.

Parameters:json – Dictionary object parsed from the JSON request body.
Returns:ApiParamObject holding the parameter values.
Raises ValueError:
 If no value is given for non-optional parameter.
read_from_request(request)

Reads the API parameter from the specified Pyramid request object.

Parameters:request – The Pyramid request object.
Returns:ApiParamObject holding the parameter values.
class kepler.api.api_util.ApiParamsMeta

Bases: type

The class is ApiParamsBase meta class. It uses the Python meta class system to automatically add name attribute to ApiParams class attributes of type ApiParam.

class kepler.api.api_util.ApiStrParam(value=None, stripped=False, optional=False, doc=None)

Bases: kepler.api.api_util.ApiParam

A convenience class for string parameters. Automatically casts the value to string, and optionally strips whitespace from both sides of the string.

If stripped is True, strips empty space from both ends of the string.

kepler.api.api_util.rest_api(description, **kwargs)

The decorator for REST API call handlers automates some of the API implementation and documenting.

Parameters:
  • description – The description of the API call in reStructuredText format.
  • kwargs – Optional parameters.
Returns:

The decorated REST API call.

The optional keyword parameters that are recognized, are following:

Parameters:
  • param_type – The class that defines the format of the parameters.
  • params – Additional documentation for parameters.
  • example – Example parameters and/or result of the API call.