Source code for staticconf.schema

"""
Configuration schemas can be used to group configuration values
together.  These schemas can be instantiated at import time, and values can
be retrieved from them by accessing the attributes of the schema object.
Each field on the schema turns into an accessor for a configuration value.
These accessors will cache the return value of the validator that they use, so
expensive operations are not repeated.

Example
-------

.. code-block:: python

    from staticconf import schema

    class MyClassSchema(object):
        __metaclass__ = schema.SchemaMeta

        # Namespace to retrieve configuration values from
        namespace = 'my_package'

        # (optional) Config path to prepend to all config keys in this schema
        config_path = 'my_class.foo'

        # Attributes accept the same values as a getter (default, help, etc)
        ratio = schema.float(default=0.2) # configured at my_class.foo.ratio

        # You can optionally specify a different name from the attribute name
        max_threshold = schema.int(config_key='max') # configued at my_class.foo.max


You can also create your schema objects by subclassing Schema

.. code-block:: python

    from staticconf import schema

    class MyClassSchema(schema.Schema):
        ...


Access the values from a schema by instantiating the schema class.

.. code-block:: python

    config = MyClassSchema()
    print config.ratio


Arguments
---------

Schema accessors accept the following kwargs:

config_key
    string configuration key
default
    if no ``default`` is given, the key must be present in the configuration.
    Raises :class:`staticconf.errors.ConfigurationError` on missing key.
help
    a help string describing the purpose of the config value. See
    :func:`staticconf.config.view_help`.



Custom schema types
-------------------

You can also create your own custom types using :func:`build_value_type`.

.. code-block:: python

    from staticconf import schema

    def validator(value):
        try:
            return do_some_casting(value)
        except Exception:
            raise ConfigurationError("%s can't be validated as a foo" % value)

    foo_type = schema.build_value_type(validator)


    class MySchema(object):
        __metaclass__ = schema.SchemaMeta

        something = foo_type(default=...)

"""
import functools

import six

from staticconf import validation, proxy, config, errors, getters


class ValueTypeDefinition(object):
    __slots__ = ['validator', 'config_key', 'default', 'help']

    def __init__(
            self,
            validator,
            config_key=None,
            default=proxy.UndefToken,
            help=None):
        self.validator      = validator
        self.config_key     = config_key
        self.default        = default
        self.help           = help


class ValueToken(object):
    __slots__ = [
        'validator',
        'config_key',
        'default',
        '_value',
        'namespace',
        '__weakref__'
    ]

    def __init__(self, validator, namespace, key, default):
        self.validator      = validator
        self.namespace      = namespace
        self.config_key     = key
        self.default        = default
        self._value         = proxy.UndefToken

    @classmethod
    def from_definition(cls, value_def, namespace, key):
        return cls(value_def.validator, namespace, key, value_def.default)

    @proxy.cache_as_field('_value')
    def get_value(self):
        return proxy.extract_value(self)

    def reset(self):
        """Clear the cached value so that configuration can be reloaded."""
        self._value = proxy.UndefToken


def build_property(value_token):
    """Construct a property from a ValueToken. The callable gets passed an
    instance of the schema class, which is ignored.
    """
    def caller(_):
        return value_token.get_value()
    return property(caller)


[docs]class SchemaMeta(type):
    """Metaclass to construct config schema object."""

    def __new__(mcs, name, bases, attributes):
        namespace = mcs.get_namespace(attributes)
        attributes = mcs.build_attributes(attributes, namespace)
        return super(SchemaMeta, mcs).__new__(mcs, name, bases, attributes)

    @classmethod
    def get_namespace(cls, attributes):
        if 'namespace' not in attributes:
            raise errors.ConfigurationError("ConfigSchema requires a namespace.")
        return config.get_namespace(attributes['namespace'])

    @classmethod
[docs]    def build_attributes(cls, attributes, namespace):
        """Return an attributes dictionary with ValueTokens replaced by a
        property which returns the config value.
        """
        config_path = attributes.get('config_path')
        tokens = {}

        def build_config_key(value_def, config_key):
            key = value_def.config_key or config_key
            return '%s.%s' % (config_path, key) if config_path else key

        def build_token(name, value_def):
            config_key = build_config_key(value_def, name)
            value_token = ValueToken.from_definition(
                                            value_def, namespace, config_key)
            getters.register_value_proxy(namespace, value_token, value_def.help)
            tokens[name] = value_token
            return name, build_property(value_token)

        def build_attr(name, attribute):
            if not isinstance(attribute, ValueTypeDefinition):
                return name, attribute
            return build_token(name, attribute)

        attributes = dict(build_attr(*item)
                          for item in six.iteritems(attributes))
        attributes['_tokens'] = tokens
        return attributes


@six.add_metaclass(SchemaMeta)
[docs]class Schema(object):
    """Base class for configuration schemas, uses :class:`SchemaMeta`."""

    namespace = None


[docs]def build_value_type(validator):
    """A factory function to create a new schema type.

    :param validator: a function which accepts one argument and returns that
                      value as the correct type.
    """
    return functools.partial(ValueTypeDefinition, validator)


# Backwards compatible with staticconf 0.5.2
create_value_type = build_value_type


for name, validator in validation.get_validators():
    name = name or 'any'
    globals()[name] = build_value_type(validator)
    list_of_validator = validation.build_list_type_validator(validator)
    globals()['list_of_%s' % name] = build_value_type(list_of_validator)