Config field reference

ConfigField base class

class ConfigField(doc, required=False, default=None, static=False, fallbacks=())

The base class for all config fields.

A config field is a descriptor that reads a value from the source data, validates it, and transforms it into an appropriate Python object.

Parameters:
  • doc (str) – Description of this field to be included in generated documentation.
  • required (bool) – Set to True if this field is required, False if it is optional. Unless otherwise specified, fields are not required.
  • default – The default value for this field if no value is provided. This is unused if the field is required.
  • static (bool) – Set to True if this is a static field. See Static fields for further information.
  • fallbacks – A list of FieldFallback objects to try if the value isn’t present in the source data. See Field fallbacks for further information.

Subclasses of ConfigField are expected to override clean() to convert values from the source data to the required form. clean() is called during validation and also on every attribute access, so it should not perform expensive computation. (If expensive computation is necessary for some reason, the result should be cached.)

There are two special attributes on this descriptor:

field_type = None

A class attribute that specifies the field type in generated documentation. It should be a string, or None to indicate that the field type should remain unspecified.

name

An instance attribute containing the name bound to this descriptor instance. It is set by metaclass magic when a Config subclass is defined.

clean(value)

Clean and process a value from the source data.

This should be overridden in subclasses to handle different kinds of fields.

Parameters:value – A value from the source data.
Returns:A value suitable for Python code to use. This implementation merely returns the value it was given.
find_value(config)

Find a value in the source data, fallbacks, or field default.

Parameters:configConfig object containing config data.
Returns:The first value it finds.
get_doc()

Build documentation for this field.

A reST :param: field is generated based on the name, doc, and field_type attributes.

Returns:A string containing a documentation section for this field.
get_value(config)

Get the cleaned value for this config field.

This calls find_value() to get the raw value and then calls clean() to process it, unless the value is None.

This method may be overridden in subclasses if None needs to be handled differently.

Parameters:configConfig object containing config data.
Returns:A cleaned value suitable for Python code to use.
present(config, check_fallbacks=True)

Check if a value for this field is present in the config data.

Parameters:
  • configConfig object containing config data.
  • check_fallbacks (bool) – If False, fallbacks will not be checked. (This is used internally to determine whether to use fallbacks when looking up data.)
Returns:

True if the value is present in the provided data, False otherwise.

raise_config_error(message_suffix)

Raise a ConfigError referencing this field.

The text “Field ‘<field name>’ <message suffix>” is used as the exception message.

Parameters:message_suffix (str) – A string to append to the exception message.
Returns:Doesn’t return, but raises a ConfigError.
validate(config)

Check that the value is present if required and valid if present.

If the field is required but no value is found, a ConfigError is raised. Further validation is performed by calling clean() and the value is assumed to be valid if no exceptions are raised.

Parameters:configConfig object containing config data.
Returns:None, but exceptions are raised for validation failures.

confmodel.fields module

All standard config field classes live here.

TODO: Write docstrings for remaining more fields.