The zaqar.transport.wsgi.utils module

JSONArray

Represents a JSON array in Python.

alias of list

JSONObject

Represents a JSON object in Python.

alias of dict

deserialize(stream, len)

Deserializes JSON from a file-like stream.

This function deserializes JSON from a stream, including translating read and parsing errors to HTTP error types.

Parameters:
  • stream – file-like object from which to read an object or array of objects.
  • len – number of bytes to read from stream
Raises:

HTTPBadRequest, HTTPServiceUnavailable

filter(document, spec)

Validates and retrieves typed fields from a single document.

Sanitizes a dict-like document by checking it against a list of field spec, and returning only those fields specified.

Parameters:
  • document – dict-like object
  • spec – iterable describing expected fields, yielding tuples with the form of: (field_name, value_type). Note that value_type may either be a Python type, or the special string ‘*’ to accept any type.
Raises:

HTTPBadRequest if any field is missing or not an instance of the specified type

Returns:

A filtered dict containing only the fields listed in the spec

format_message_v1(message, base_path, claim_id=None)
format_message_v1_1(message, base_path, claim_id=None)
get_checked_field(document, name, value_type, default_value)

Validates and retrieves a typed field from a document.

This function attempts to look up doc[name], and raises appropriate HTTP errors if the field is missing or not an instance of the given type.

Parameters:
  • document – dict-like object
  • name – field name
  • value_type – expected value type, or ‘*’ to accept any type
  • default_value – Default value to use if the value is missing, or None to make the value required.
Raises:

HTTPBadRequest if the field is missing or not an instance of value_type

Returns:

value obtained from doc[name]

load(req)

Reads request body, raising an exception if it is not JSON.

Parameters:req (falcon.Request) – The request object to read from
Returns:a dictionary decoded from the JSON stream
Return type:dict
Raises:errors.HTTPBadRequestBody
message_url(message, base_path, claim_id=None)
sanitize(document, spec=None, doctype=<type ‘dict’>)

Validates a document and drops undesired fields.

Parameters:
  • document – A dict to verify according to spec.
  • spec

    (Default None) Iterable describing expected fields, yielding tuples with the form of:

    (field_name, value_type, default_value)

    Note that value_type may either be a Python type, or the special string ‘*’ to accept any type. default_value is the default to give the field if it is missing, or None to require that the field be present.

    If spec is None, the incoming documents will not be validated.

  • doctype – type of document to expect; must be either JSONObject or JSONArray.
Raises:

HTTPBadRequestBody

Returns:

A sanitized, filtered version of the document. If the document is a list of objects, each object will be filtered and returned in a new list. If, on the other hand, the document is expected to contain a single object, that object’s fields will be filtered and the resulting object will be returned.

validate(validator, document)

Verifies a document against a schema.

Parameters:
  • validator (jsonschema.Draft4Validator) – a validator to use to check validity
  • document (dict) – document to check
Raises:

errors.HTTPBadRequestBody