# `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.

  abstract deserialize(value) → T | None

    Cast raw string to appropriate type.

    Return type:

      `Optional`[`TypeVar`(`T`)]

  serialize(value, display=False) → str | DeprecatedValue

    Convert value back to string for saving.

    Return type:

      `str` | `DeprecatedValue`

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

  Float value.

  deserialize(value) → float | None

    Cast raw string to appropriate type.

    Return type:

      `float` | `None`

class mopidy.config.List(optional=False, unique=False, subtype=<mopidy.config.types.String object>) → 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) → tuple[V, ...] | frozenset[V]

    Cast raw string to appropriate type.

    Return type:

      `tuple`[`TypeVar`(`V`, bound= ConfigValue), `...`] | `frozenset`[`TypeVar`(`V`, bound= ConfigValue)]

  serialize(value, display=False) → str

    Convert value back to string for saving.

    Return type:

      `str`

class mopidy.config.Pair(optional=False, optional_pair=False, separator='|', subtypes=(<mopidy.config.types.String object>, <mopidy.config.types.String object>)) → 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) → tuple[K, V] | None

    Cast raw string to appropriate type.

    Return type:

      `tuple`[`TypeVar`(`K`, bound= ConfigValue), `TypeVar`(`V`, bound= ConfigValue)] | `None`

  serialize(value, display=False) → str | DeprecatedValue

    Convert value back to string for saving.

    Return type:

      `str` | `DeprecatedValue`

## Config section schemas

class mopidy.config.schemas.ConfigSchema(name) → None

  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) → tuple[dict[str, Any], dict[str, Any]]

    Validates the given `values` using the config schema.

    Returns a tuple with cleaned values and errors.

    Return type:

      `tuple`[`dict`[`str`, `Any`], `dict`[`str`, `Any`]]

  serialize(values, display=False) → dict[str, Any]

    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.

    Return type:

      `dict`[`str`, `Any`]

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

  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) → None

  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) → bool | None

    Cast raw string to appropriate type.

    Return type:

      `bool` | `None`

  serialize(value, display=False) → Literal['true', 'false']

    Convert value back to string for saving.

    Return type:

      `Literal`[`'true'`, `'false'`]

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.

  abstract deserialize(value) → T | None

    Cast raw string to appropriate type.

    Return type:

      `Optional`[`TypeVar`(`T`)]

  serialize(value, display=False) → str | DeprecatedValue

    Convert value back to string for saving.

    Return type:

      `str` | `DeprecatedValue`

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) → DeprecatedValue

    Cast raw string to appropriate type.

    Return type:

      `DeprecatedValue`

  serialize(value, display=False) → DeprecatedValue

    Convert value back to string for saving.

    Return type:

      `DeprecatedValue`

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

  Float value.

  deserialize(value) → float | None

    Cast raw string to appropriate type.

    Return type:

      `float` | `None`

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

  Network hostname value.

  deserialize(value, display=False) → str | None

    Cast raw string to appropriate type.

    Return type:

      `str` | `None`

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

  Integer value.

  deserialize(value) → int | None

    Cast raw string to appropriate type.

    Return type:

      `int` | `None`

class mopidy.config.types.List(optional=False, unique=False, subtype=<mopidy.config.types.String object>) → 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) → tuple[V, ...] | frozenset[V]

    Cast raw string to appropriate type.

    Return type:

      `tuple`[`TypeVar`(`V`, bound= ConfigValue), `...`] | `frozenset`[`TypeVar`(`V`, bound= ConfigValue)]

  serialize(value, display=False) → str

    Convert value back to string for saving.

    Return type:

      `str`

class mopidy.config.types.LogColor
  deserialize(value) → Literal['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white']

    Cast raw string to appropriate type.

    Return type:

      `Literal`[`'black'`, `'red'`, `'green'`, `'yellow'`, `'blue'`, `'magenta'`, `'cyan'`, `'white'`]

  serialize(value, display=False) → str

    Convert value back to string for saving.

    Return type:

      `str`

class mopidy.config.types.LogLevel

  Log level value.

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

  deserialize(value) → int | None

    Cast raw string to appropriate type.

    Return type:

      `int` | `None`

  serialize(value, display=False) → str

    Convert value back to string for saving.

    Return type:

      `str`

class mopidy.config.types.Pair(optional=False, optional_pair=False, separator='|', subtypes=(<mopidy.config.types.String object>, <mopidy.config.types.String object>)) → 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) → tuple[K, V] | None

    Cast raw string to appropriate type.

    Return type:

      `tuple`[`TypeVar`(`K`, bound= ConfigValue), `TypeVar`(`V`, bound= ConfigValue)] | `None`

  serialize(value, display=False) → str | DeprecatedValue

    Convert value back to string for saving.

    Return type:

      `str` | `DeprecatedValue`

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) → _ExpandedPath | None

    Cast raw string to appropriate type.

    Return type:

      `_ExpandedPath` | `None`

  serialize(value, display=False) → str

    Convert value back to string for saving.

    Return type:

      `str`

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) → None

  Secret string value.

  Is decoded as utf-8, and n and 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) → str

    Convert value back to string for saving.

    Return type:

      `str`

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

  String value.

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

  deserialize(value) → str | None

    Cast raw string to appropriate type.

    Return type:

      `str` | `None`

  serialize(value, display=False) → str

    Convert value back to string for saving.

    Return type:

      `str`

## Config value validators

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

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

  Normally called in `deserialize()`.

  Return type:

    `None`

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

  Validate that `value` is at most `maximum`.

  Normally called in `deserialize()`.

  Return type:

    `None`

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

  Validate that `value` is at least `minimum`.

  Normally called in `deserialize()`.

  Return type:

    `None`

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

  Validate that `value` is set if `required`.

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

  Return type:

    `None`