confu.schema.core

Fundamental schema attributes

These can be imported directly from confu.schema

Functions

apply_default

def apply_default(config, attribute, path)

Apply attribute default to config dict at the specified path

Arguments

  • config (dict): the config dictonary
  • attribute (Attribute): attribute instance
  • path (list(str)): full path of the attribute in the schema

apply_defaults

def apply_defaults(schema, config, debug=False)

Take a config object and apply a schema's default values to keys that are missing.

Arguments

  • schema (Schema): schema instance
  • config (dict): the config dictonary

validate

def validate(schema, config, raise_errors=False, log=None, **kwargs)

Helper function that allows schema validation to either collect or raise errors

Arguments

  • schema (Schema): schema instance
  • config (dict|munge.Config)

Keyword Arguments

  • raise_errors (bool=False): if True will raise a ValidationError exception if it encounters validation errors

If False it will instead collect errors and warnings and return a tuple:

success(bool), errors(CollectValidationExceptions), warnings(CollectValidationException)

  • log (callable): function to use to log errors, will be passed a str message
  • any additional kwargs will be passed on to Schema.validate

Classes

Attribute

Attribute(builtins.object)

Base confu schema attribute. All other schema attributes should extend this

Instanced Attributes

These attributes / properties will be available on instances of the class

  • choices (@property): Return a list of possible value choices for this attribute

Will return an empty list if the attribute is NOT limited by choices - cli (@property): Returns whether or not the attribute is available in as a cli argument when confu is used to generated argparse or click arguments - default (@property): Return the default value for this attribute - default_is_none (@property): None - has_default (@property): None

Methods

__init__

def __init__(self, name=, **kwargs)

Initialize attribute

Keyword Arguments

  • name (str): describes the attribute name, if not specified explicitly will be set through the schema that instantiates the attribute.
  • default (mixed): the default value of this attribute. Once a default value is set, schema validation will no longer raise a validation error if the attribute is missing from the configuration.
  • choices (list): if specified on values in this list may be set for this attribute
  • help (str): help description
  • cli (bool=True|function): enable CLI support for this attribute
  • deprecated (str): version id of when this attribute will be deprecated
  • added (str): version id of when this attribute was added to the schema
  • removed (str): version id of when this attribute will be removed

validate

def validate(self, value, path, **kwargs)

Validate a value for this attribute

Will raise a ValidationError or ValidationWarning exception on validation failure

Arguments

  • value (mixed): the value to validate
  • path (list): current path in the config schema, this is mostly used to identify where an error occured when validating against config data, you can pass an empty list to it when calling this manually

Bool

Bool(confu.schema.core.Attribute)

Attribute that requires a boolean value

Methods

__init__

def __init__(self, name=, **kwargs)

Initialize attribute

Keyword Arguments

  • name (str): describes the attribute name, if not specified explicitly will be set through the schema that instantiates the attribute.
  • default (mixed): the default value of this attribute. Once a default value is set, schema validation will no longer raise a validation error if the attribute is missing from the configuration.
  • choices (list): if specified on values in this list may be set for this attribute
  • help (str): help description
  • cli (bool=True|function): enable CLI support for this attribute
  • deprecated (str): version id of when this attribute will be deprecated
  • added (str): version id of when this attribute was added to the schema
  • removed (str): version id of when this attribute will be removed

validate

def validate(self, value, path, **kwargs)

Validate a value for this attribute

Will raise a ValidationError or ValidationWarning exception on validation failure

Arguments

  • value (mixed): the value to validate
  • path (list): current path in the config schema, this is mostly used to identify where an error occured when validating against config data, you can pass an empty list to it when calling this manually

CollectValidationExceptions

CollectValidationExceptions(confu.schema.core.ValidationErrorProcessor)

This validation error processor will store all errors and warnings it encounters and NOT raise any exceptions

Methods

__init__

def __init__(self)

Initialize self. See help(type(self)) for accurate signature.

Dict

Dict(confu.schema.core.Schema)

Wrapper for schema with arbitrary keys

For this the item property needs to be set.

Methods

__init__

def __init__(self, name=None, item=None, *args, **kwargs)

Initialize schema

Keyword Arguments

  • item (Attribute): allows you to specify an arbitrary attribute to use for all values in the schema. This is only allowed if your schema does NOT explicitly set any attributes in it's definition
  • name (str): describes the attribute name, if not specified explicitly will be set through the schema that instantiates the attribute.
  • default (mixed): the default value of this attribute. Once a default value is set, schema validation will no longer raise a validation error if the attribute is missing from the configuration.
  • help (str): help description
  • cli (bool=True): enable CLI support for this attribute
  • deprecated (str): version id of when this attribute will be deprecated
  • added (str): version id of when this attribute was added to the schema
  • removed (str): version id of when this attribute will be removed

Directory

Directory(confu.schema.core.Str)

Attribute that requires an existing directory path

Keyword Arguments

  • require_exist ('bool=True'): if True directory needs to exist
  • create (octal): if set, instead of raising a ValidationError on a non-existing directory, attempt to create directory first using the value passed as mode (chmod) e.g., create=0o777

Methods

__init__

def __init__(self, name=, **kwargs)

Initialize attribute

Keyword Arguments

  • name (str): describes the attribute name, if not specified explicitly will be set through the schema that instantiates the attribute.
  • default (mixed): the default value of this attribute. Once a default value is set, schema validation will no longer raise a validation error if the attribute is missing from the configuration.
  • choices (list): if specified on values in this list may be set for this attribute
  • help (str): help description
  • cli (bool=True|function): enable CLI support for this attribute
  • deprecated (str): version id of when this attribute will be deprecated
  • added (str): version id of when this attribute was added to the schema
  • removed (str): version id of when this attribute will be removed

validate

def validate(self, value, path, **kwargs)

Validate a value for this attribute

Will raise a ValidationError or ValidationWarning exception on validation failure

Arguments

  • value (mixed): the value to validate
  • path (list): current path in the config schema, this is mostly used to identify where an error occured when validating against config data, you can pass an empty list to it when calling this manually

File

File(confu.schema.core.Str)

Attribute that requires a file to exist at path

Keyword Attributes

  • require_exist ('bool=True'): if True file needs to exist

Methods

__init__

def __init__(self, name=, **kwargs)

Initialize attribute

Keyword Arguments

  • name (str): describes the attribute name, if not specified explicitly will be set through the schema that instantiates the attribute.
  • default (mixed): the default value of this attribute. Once a default value is set, schema validation will no longer raise a validation error if the attribute is missing from the configuration.
  • choices (list): if specified on values in this list may be set for this attribute
  • help (str): help description
  • cli (bool=True|function): enable CLI support for this attribute
  • deprecated (str): version id of when this attribute will be deprecated
  • added (str): version id of when this attribute was added to the schema
  • removed (str): version id of when this attribute will be removed

validate

def validate(self, value, path, **kwargs)

Validate a value for this attribute

Will raise a ValidationError or ValidationWarning exception on validation failure

Arguments

  • value (mixed): the value to validate
  • path (list): current path in the config schema, this is mostly used to identify where an error occured when validating against config data, you can pass an empty list to it when calling this manually

Float

Float(confu.schema.core.Attribute)

Attribute that requires a float value

Methods

validate

def validate(self, value, path, **kwargs)

Validate a value for this attribute

Will raise a ValidationError or ValidationWarning exception on validation failure

Arguments

  • value (mixed): the value to validate
  • path (list): current path in the config schema, this is mostly used to identify where an error occured when validating against config data, you can pass an empty list to it when calling this manually

Int

Int(confu.schema.core.Attribute)

Attribute that requires an integer value

Methods

validate

def validate(self, value, path, **kwargs)

Validate a value for this attribute

Will raise a ValidationError or ValidationWarning exception on validation failure

Arguments

  • value (mixed): the value to validate
  • path (list): current path in the config schema, this is mostly used to identify where an error occured when validating against config data, you can pass an empty list to it when calling this manually

List

List(confu.schema.core.Attribute)

Attribute that requires a list value

Instanced Attributes

These attributes / properties will be available on instances of the class

  • cli (@property): None

Methods

__init__

def __init__(self, name=None, item=None, **kwargs)

Initialize List attribute

Keyword Arguments

  • name (str): describes the attribute name, if not specified explicitly will be set through the schema that instantiates the attribute.
  • item (Attribute): allows you to specify an arbitrary attribute to use for all values in the list.
  • default (mixed): the default value of this attribute. Once a default value is set, schema validation will no longer raise a validation error if the attribute is missing from the configuration.
  • help (str): help description
  • cli (bool=True): enable CLI support for this attribute
  • deprecated (str): version id of when this attribute will be deprecated
  • added (str): version id of when this attribute was added to the schema
  • removed (str): version id of when this attribute will be removed

validate

def validate(self, value, path, **kwargs)

Validate a value for this attribute

Will raise a ValidationError or ValidationWarning exception on validation failure

Arguments

  • value (mixed): the value to validate
  • path (list): current path in the config schema, this is mostly used to identify where an error occured when validating against config data, you can pass an empty list to it when calling this manually

ProxySchema

ProxySchema(confu.schema.core.Schema)

An object that can be used in place of a schema in order to dynamically obtain a schema instance from somewhere else during validate

Methods

schema

def schema(self, config)

return a schema instance

validate

def validate(self, config, path=None, errors=None, warnings=None)

call validate on the schema returned by self.schema

Schema

Schema(confu.schema.core.Attribute)

Describes a confu schema.

Instantiate confu attributes as properties of the schema.

As the schema itself is a confu attribute, you may nest schemas within schemas

Example

class MySchema(Schema):
    str_attr = Str()

Methods

__init__

def __init__(self, *args, **kwargs)

Initialize schema

Keyword Arguments

  • item (Attribute): allows you to specify an arbitrary attribute to use for all values in the schema. This is only allowed if your schema does NOT explicitly set any attributes in it's definition
  • name (str): describes the attribute name, if not specified explicitly will be set through the schema that instantiates the attribute.
  • default (mixed): the default value of this attribute. Once a default value is set, schema validation will no longer raise a validation error if the attribute is missing from the configuration.
  • help (str): help description
  • cli (bool=True): enable CLI support for this attribute
  • deprecated (str): version id of when this attribute will be deprecated
  • added (str): version id of when this attribute was added to the schema
  • removed (str): version id of when this attribute will be removed

validate

def validate(self, config, path=None, errors=None, warnings=None)

Validate config data against this schema

Attributes

  • config (dict): config to validate

Keyword Attributes

  • path (list): current path in the config data, this can be ignored on the initial call and will be set automatically on any subsequent calls (nested schemas)
  • errors (ValidationErrorProcessor)
  • warnigns (ValidationErrorProcessor)

Str

Str(confu.schema.core.Attribute)

Attribute that requires a string value

Keyword Attributes: - blank : if True allow "" as a value

Instanced Attributes

These attributes / properties will be available on instances of the class

  • default_is_blank (@property): None

Methods

__init__

def __init__(self, name=, **kwargs)

Initialize attribute

Keyword Arguments

  • name (str): describes the attribute name, if not specified explicitly will be set through the schema that instantiates the attribute.
  • default (mixed): the default value of this attribute. Once a default value is set, schema validation will no longer raise a validation error if the attribute is missing from the configuration.
  • choices (list): if specified on values in this list may be set for this attribute
  • help (str): help description
  • cli (bool=True|function): enable CLI support for this attribute
  • deprecated (str): version id of when this attribute will be deprecated
  • added (str): version id of when this attribute was added to the schema
  • removed (str): version id of when this attribute will be removed

validate

def validate(self, value, path, **kwargs)

Validate a value for this attribute

Will raise a ValidationError or ValidationWarning exception on validation failure

Arguments

  • value (mixed): the value to validate
  • path (list): current path in the config schema, this is mostly used to identify where an error occured when validating against config data, you can pass an empty list to it when calling this manually

ValidationErrorProcessor

ValidationErrorProcessor(builtins.object)

This the default validation error processor, it will raise an exception when a warning or error is encountered