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