# Readers

Functions to read values directly from a `staticconf.config.ConfigNamespace`. Values will be validated and cast to the requested type.

## Examples

    import staticconf

    # read an int
    max_cycles = staticconf.read_int('max_cycles')
    start_id = staticconf.read_int('poller.init.start_id', default=0)

    # start_date will be a datetime.date
    start_date = staticconf.read_date('start_date')

    # matcher will be a regex object
    matcher = staticconf.read_regex('matcher_pattern')

    # Read a value from a different namespace
    intervals = staticconf.read_float('intervals', namespace='something')

Readers can be attached to a namespace using a `NamespaceReaders` object.

    import staticconf

    bling_reader = staticconf.NamespaceReaders('bling')

    # These values are read from the `bling` ConfigNamespace
    currency = bling_reader.read_string('currency')
    value = bling_reader.read_float('value')

## Arguments

Readers accept the following kwargs:

config_key

  string configuration key using dotted notation

default

  if no default is given, the key must be present in the configuration. If the key is missing a `staticconf.errors.ConfigurationError` is raised.

namespace

  get the value from this namespace instead of DEFAULT.

## Building custom readers

`build_reader()` is a factory function which can be used for creating custom readers from a validation function. A validation function should handle all exceptions and raise a `staticconf.errors.ValidationError` if there is a problem.

First create a validation function

    def validate_currency(value):
        try:
            # Assume a tuple or a list
            name, decimal_points = value
            return Currency(name, decimal_points)
        except Exception, e:
            raise ValidationErrror(...)

Example of a custom reader:

    from staticconf import readers

    read_currency = readers.build_reader(validate_currency)

    # Returns a Currency object using the data from the config namespace
    # at they key `currencies.usd`.
    usd_currency = read_currency('currencies.usd')

`staticconf.readers.``NamespaceReaders`(name)

  An object with all reader functions which retrieve configuration from a named namespace, instead of DEFAULT.

`staticconf.readers.``build_reader`(validator, reader_namespace='DEFAULT')

  A factory method for creating a custom config reader from a validation function.

  Parameters

    - validator – a validation function which acceptance one argument (the configuration value), and returns that value casted to the appropriate type.

    - reader_namespace – the default namespace to use. Defaults to DEFAULT.