mopidy.config — Config API — Mopidy 3.4.1 documentation

# `mopidy.config` — Config API

class mopidy.config.ConfigValue

  Represents a config key’s value and how to handle it.

  Normally you will only be interacting with sub-classes for config values that encode either deserialization behavior and/or validation.

  Each config value should be used for the following actions:

  1. Deserializing from a raw string and validating, raising ValueError on failure.

  2. Serializing a value back to a string that can be stored in a config.

  3. Formatting a value to a printable form (useful for masking secrets).

  `None` values should not be deserialized, serialized or formatted, the code interacting with the config should simply skip None config values.

  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

class mopidy.config.Float(minimum=None, maximum=None, optional=False)

  Float value.

  deserialize(value)

    Cast raw string to appropriate type.

class mopidy.config.List(optional=False, unique=False, subtype=None)

  List value.

  Supports elements split by commas or newlines. Newlines take precedence and empty list items will be filtered out.

  Enforcing unique entries in the list will result in a set data structure being used. This does not preserve ordering, which could result in the serialized output being unstable.

  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

class mopidy.config.Pair(optional=False, optional_pair=False, separator='|', subtypes=None)

  Pair value

  The value is expected to be a pair of elements, separated by a specified delimiter. Values can optionally not be a pair, in which case the whole input is provided for both sides of the value.

  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

## Config section schemas

class mopidy.config.schemas.ConfigSchema(name)

  Logical group of config values that correspond to a config section.

  Schemas are set up by assigning config keys with config values to instances. Once setup `deserialize()` can be called with a dict of values to process. For convienience we also support `format()` method that can used for converting the values to a dict that can be printed and `serialize()` for converting the values to a form suitable for persistence.

  deserialize(values)

    Validates the given `values` using the config schema.

    Returns a tuple with cleaned values and errors.

  serialize(values, display=False)

    Converts the given `values` to a format suitable for persistence.

    If `display` is `True` secret config values, like passwords, will be masked out.

    Returns a dict of config keys and values.

class mopidy.config.schemas.MapConfigSchema(name, value_type)

  Schema for handling multiple unknown keys with the same type.

  Does not sub-class `ConfigSchema`, but implements the same serialize/deserialize interface.

## Config value types

class mopidy.config.types.Boolean(optional=False)

  Boolean value.

  Accepts `1`, `yes`, `true`, and `on` with any casing as `True`.

  Accepts `0`, `no`, `false`, and `off` with any casing as `False`.

  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

class mopidy.config.types.ConfigValue

  Represents a config key’s value and how to handle it.

  Normally you will only be interacting with sub-classes for config values that encode either deserialization behavior and/or validation.

  Each config value should be used for the following actions:

  1. Deserializing from a raw string and validating, raising ValueError on failure.

  2. Serializing a value back to a string that can be stored in a config.

  3. Formatting a value to a printable form (useful for masking secrets).

  `None` values should not be deserialized, serialized or formatted, the code interacting with the config should simply skip None config values.

  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

class mopidy.config.types.Deprecated

  Deprecated value.

  Used for ignoring old config values that are no longer in use, but should not cause the config parser to crash.

  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

class mopidy.config.types.Float(minimum=None, maximum=None, optional=False)

  Float value.

  deserialize(value)

    Cast raw string to appropriate type.

class mopidy.config.types.Hostname(optional=False)

  Network hostname value.

  deserialize(value, display=False)

    Cast raw string to appropriate type.

class mopidy.config.types.Integer(minimum=None, maximum=None, choices=None, optional=False)

  Integer value.

  deserialize(value)

    Cast raw string to appropriate type.

class mopidy.config.types.List(optional=False, unique=False, subtype=None)

  List value.

  Supports elements split by commas or newlines. Newlines take precedence and empty list items will be filtered out.

  Enforcing unique entries in the list will result in a set data structure being used. This does not preserve ordering, which could result in the serialized output being unstable.

  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

class mopidy.config.types.LogColor
  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

class mopidy.config.types.LogLevel

  Log level value.

  Expects one of `critical`, `error`, `warning`, `info`, `debug`, `trace`, or `all`, with any casing.

  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

class mopidy.config.types.Pair(optional=False, optional_pair=False, separator='|', subtypes=None)

  Pair value

  The value is expected to be a pair of elements, separated by a specified delimiter. Values can optionally not be a pair, in which case the whole input is provided for both sides of the value.

  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

class mopidy.config.types.Path(optional=False)

  File system path.

  The following expansions of the path will be done:

  - `~` to the current user’s home directory

  - `$XDG_CACHE_DIR` according to the XDG spec

  - `$XDG_CONFIG_DIR` according to the XDG spec

  - `$XDG_DATA_DIR` according to the XDG spec

  - `$XDG_MUSIC_DIR` according to the XDG spec

  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

class mopidy.config.types.Port(choices=None, optional=False)

  Network port value.

  Expects integer in the range 0-65535, zero tells the kernel to simply allocate a port for us.

class mopidy.config.types.Secret(optional=False, choices=None, transformer=None)

  Secret string value.

  Is decoded as utf-8 and n t escapes should work and be preserved.

  Should be used for passwords, auth tokens etc. Will mask value when being displayed.

  serialize(value, display=False)

    Convert value back to string for saving.

class mopidy.config.types.String(optional=False, choices=None, transformer=None)

  String value.

  Is decoded as utf-8 and n t escapes should work and be preserved.

  deserialize(value)

    Cast raw string to appropriate type.

  serialize(value, display=False)

    Convert value back to string for saving.

## Config value validators

mopidy.config.validators.validate_choice(value, choices)

  Validate that `value` is one of the `choices`

  Normally called in `deserialize()`.

mopidy.config.validators.validate_maximum(value, maximum)

  Validate that `value` is at most `maximum`

  Normally called in `deserialize()`.

mopidy.config.validators.validate_minimum(value, minimum)

  Validate that `value` is at least `minimum`

  Normally called in `deserialize()`.

mopidy.config.validators.validate_required(value, required)

  Validate that `value` is set if `required`

  Normally called in `deserialize()` on the raw string, _not_ the converted value.