Appendix D: API Documentation

The conversionkit Module

Conversion Toolkit

See the docs/source/manual.rst for an explanation of this module.

class conversionkit.Conversion(value)

When writing converters for this conversion object you should ensure that converters designed to work with single values set the .result attribute directly whereas converters which operate on nested data structures set the .children attribute and leave this object to calculate the result from the child conversions.

error

perform(converter, state=None, formencode_method=None)

result

successful

Can return True or False. Raises a ConversionKitError exception if no conversion has been performed yet.

value

class conversionkit.Field(converter, missing_error=None, empty_error=None, missing_default=None, empty_default=None, missing_or_empty_default=None, missing_or_empty_error=None)

class conversionkit.Missing

This class is used in a toDictionary() conversion when a field is missing. In order to make the handling of errors due to missing fields consistent with the behaviour of other errors, including empty value errors, a child conversion is set up for the missing field but because no value was present it isn’t possible to set a .value attribute on the conversion so this class is used instead.

conversionkit.chainConverters(*converters)

conversionkit.chainPostConverters(*converters)

conversionkit.message(state, message, args=None)

conversionkit.noConversion(copy_mode='shallow')

conversionkit.oneOf(values)

conversionkit.set_error(conversion, error)

conversionkit.set_result(conversion, result)

conversionkit.toDictionary(converters, missing_defaults=None, empty_defaults=None, missing_errors=None, empty_errors=None, missing_or_empty_errors=None, missing_or_empty_defaults=None, filter_extra_fields=True, allow_extra_fields=True, raise_on_extra_fields=True, use_many_message_after_failures=3, msg_many_invalid_fields='Multiple fields were invalid', msg_some_invalid_fields='The %(fields)s fields were invalid', msg_single_invalid_field='The %(field)s field is invalid', msg_field_not_allowed='The field %r is not allowed', msg_fields_not_allowed="The fields '%s' and '%s' are not allowed")

This is a converter which handles pre-converters and post converters as well as a dictionary of converters. Rather than using this class it is recommended you use make_dictionary() together with the chain() converter to chain any pre-handlers, dictionary converter and post-handlers.

conversionkit.toListOf(converter, min=None, max=None)

conversionkit.tryEach(alternatives, stop_on_first_result=True, stop_on_first_error=False, children_keys=None, MSG_NONE_SUCCESSFUL=None)