Config field reference¶
ConfigField
base class¶
-
class
ConfigField
(doc, required=False, default=None, static=False, fallbacks=())[source]¶ 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 overrideclean()
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)[source]¶ 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)[source]¶ Find a value in the source data, fallbacks, or field default.
Parameters: config – Config
object containing config data.Returns: The first value it finds.
-
get_doc
()[source]¶ Build documentation for this field.
A reST
:param:
field is generated based on thename
,doc
, andfield_type
attributes.Returns: A string containing a documentation section for this field.
-
get_value
(config)[source]¶ Get the cleaned value for this config field.
This calls
find_value()
to get the raw value and then callsclean()
to process it, unless the value isNone
.This method may be overridden in subclasses if
None
needs to be handled differently.Parameters: config – Config
object containing config data.Returns: A cleaned value suitable for Python code to use.
-
present
(config, check_fallbacks=True)[source]¶ Check if a value for this field is present in the config data.
Parameters: - config –
Config
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.- config –
-
raise_config_error
(message_suffix)[source]¶ 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)[source]¶ 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 callingclean()
and the value is assumed to be valid if no exceptions are raised.Parameters: config – Config
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.