Skip to content

Config API

mopidy.config

Modules:

Classes:

  • Boolean –

    Boolean value.

  • ConfigSchema –

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

  • ConfigValue –

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

  • Deprecated –

    Deprecated value.

  • Float –

    Float value.

  • Hostname –

    Network hostname value.

  • Integer –

    Integer value.

  • List –

    List value.

  • LogLevel –

    Log level value.

  • MapConfigSchema –

    Schema for handling multiple unknown keys with the same type.

  • Pair –

    Pair value.

  • Path –

    File system path.

  • Port –

    Network port value.

  • Secret –

    Secret string value.

  • String –

    String value.

Functions:

  • read –

    Helper to load config defaults in same way across core and extensions.

Boolean 

Boolean(optional: bool = False)

Bases: ConfigValue[bool]

Boolean value.

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

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

ConfigSchema 

ConfigSchema(name: str, data: dict[str, Any] | None = None)

Bases: UserDict

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 convenience 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.

Methods:

  • deserialize –

    Validates the given values using the config schema.

  • serialize –

    Converts the given values to a format suitable for persistence.

deserialize 

deserialize(values: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]

Validates the given values using the config schema.

Returns a tuple with cleaned values and errors.

serialize 

serialize(values: dict[str, Any], display: bool = 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.

ConfigValue

Bases: ABC

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.

Methods:

  • deserialize –

    Cast raw string to appropriate type.

  • serialize –

    Convert value back to string for saving.

deserialize abstractmethod 

deserialize(value: AnyStr) -> T | None

Cast raw string to appropriate type.

serialize 

serialize(value: T, display: bool = False) -> str | DeprecatedValue

Convert value back to string for saving.

Deprecated

Bases: ConfigValue[Any]

Deprecated value.

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

Float 

Float(
    minimum: float | None = None,
    maximum: float | None = None,
    optional: bool = False,
)

Bases: ConfigValue[float]

Float value.

Methods:

  • serialize –

    Convert value back to string for saving.

serialize 

serialize(value: T, display: bool = False) -> str | DeprecatedValue

Convert value back to string for saving.

Hostname 

Hostname(optional: bool = False)

Bases: ConfigValue[str]

Network hostname value.

Methods:

  • serialize –

    Convert value back to string for saving.

serialize 

serialize(value: T, display: bool = False) -> str | DeprecatedValue

Convert value back to string for saving.

Integer 

Integer(
    minimum: int | None = None,
    maximum: int | None = None,
    choices: Iterable[int] | None = None,
    optional: bool = False,
)

Bases: ConfigValue[int]

Integer value.

Methods:

  • serialize –

    Convert value back to string for saving.

serialize 

serialize(value: T, display: bool = False) -> str | DeprecatedValue

Convert value back to string for saving.

List 

List(optional: bool = False, unique: bool = False, subtype: V = String())

Bases: ConfigValue[tuple[V, ...] | frozenset[V]]

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.

LogLevel

Bases: ConfigValue[int]

Log level value.

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

MapConfigSchema 

MapConfigSchema(name: str, value_type: ConfigValue)

Schema for handling multiple unknown keys with the same type.

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

Pair 

Pair(
    optional: bool = False,
    optional_pair: bool = False,
    separator: str = "|",
    subtypes: tuple[K, V] = (String(), String()),
)

Bases: ConfigValue[tuple[K, V]]

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.

Path 

Path(optional: bool = False)

Bases: ConfigValue[_ExpandedPath]

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

Port 

Port(choices: Iterable[int] | None = None, optional: bool = False)

Bases: Integer

Network port value.

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

Methods:

  • serialize –

    Convert value back to string for saving.

serialize 

serialize(value: T, display: bool = False) -> str | DeprecatedValue

Convert value back to string for saving.

Secret 

Secret(
    optional: bool = False,
    choices: None = None,
    transformer: Callable[[str], str] | None = None,
)

Bases: String

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.

String 

String(
    optional: bool = False,
    choices: Iterable[str] | None = None,
    transformer: Callable[[str], str] | None = None,
)

Bases: ConfigValue[str]

String value.

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

read 

read(config_file: Path) -> str

Helper to load config defaults in same way across core and extensions.

mopidy.config.schemas

Classes:

  • ConfigSchema –

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

  • MapConfigSchema –

    Schema for handling multiple unknown keys with the same type.

ConfigSchema 

ConfigSchema(name: str, data: dict[str, Any] | None = None)

Bases: UserDict

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 convenience 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.

Methods:

  • deserialize –

    Validates the given values using the config schema.

  • serialize –

    Converts the given values to a format suitable for persistence.

deserialize 

deserialize(values: dict[str, Any]) -> tuple[dict[str, Any], dict[str, Any]]

Validates the given values using the config schema.

Returns a tuple with cleaned values and errors.

serialize 

serialize(values: dict[str, Any], display: bool = 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.

MapConfigSchema 

MapConfigSchema(name: str, value_type: ConfigValue)

Schema for handling multiple unknown keys with the same type.

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

mopidy.config.types

Classes:

Boolean 

Boolean(optional: bool = False)

Bases: ConfigValue[bool]

Boolean value.

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

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

ConfigValue

Bases: ABC

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.

Methods:

  • deserialize –

    Cast raw string to appropriate type.

  • serialize –

    Convert value back to string for saving.

deserialize abstractmethod 

deserialize(value: AnyStr) -> T | None

Cast raw string to appropriate type.

serialize 

serialize(value: T, display: bool = False) -> str | DeprecatedValue

Convert value back to string for saving.

Deprecated

Bases: ConfigValue[Any]

Deprecated value.

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

Float 

Float(
    minimum: float | None = None,
    maximum: float | None = None,
    optional: bool = False,
)

Bases: ConfigValue[float]

Float value.

Methods:

  • serialize –

    Convert value back to string for saving.

serialize 

serialize(value: T, display: bool = False) -> str | DeprecatedValue

Convert value back to string for saving.

Hostname 

Hostname(optional: bool = False)

Bases: ConfigValue[str]

Network hostname value.

Methods:

  • serialize –

    Convert value back to string for saving.

serialize 

serialize(value: T, display: bool = False) -> str | DeprecatedValue

Convert value back to string for saving.

Integer 

Integer(
    minimum: int | None = None,
    maximum: int | None = None,
    choices: Iterable[int] | None = None,
    optional: bool = False,
)

Bases: ConfigValue[int]

Integer value.

Methods:

  • serialize –

    Convert value back to string for saving.

serialize 

serialize(value: T, display: bool = False) -> str | DeprecatedValue

Convert value back to string for saving.

List 

List(optional: bool = False, unique: bool = False, subtype: V = String())

Bases: ConfigValue[tuple[V, ...] | frozenset[V]]

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.

LogLevel

Bases: ConfigValue[int]

Log level value.

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

Pair 

Pair(
    optional: bool = False,
    optional_pair: bool = False,
    separator: str = "|",
    subtypes: tuple[K, V] = (String(), String()),
)

Bases: ConfigValue[tuple[K, V]]

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.

Path 

Path(optional: bool = False)

Bases: ConfigValue[_ExpandedPath]

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

Port 

Port(choices: Iterable[int] | None = None, optional: bool = False)

Bases: Integer

Network port value.

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

Methods:

  • serialize –

    Convert value back to string for saving.

serialize 

serialize(value: T, display: bool = False) -> str | DeprecatedValue

Convert value back to string for saving.

Secret 

Secret(
    optional: bool = False,
    choices: None = None,
    transformer: Callable[[str], str] | None = None,
)

Bases: String

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.

String 

String(
    optional: bool = False,
    choices: Iterable[str] | None = None,
    transformer: Callable[[str], str] | None = None,
)

Bases: ConfigValue[str]

String value.

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

mopidy.config.validators

Functions:

validate_choice 

validate_choice[T](value: T, choices: Iterable[T] | None) -> None

Validate that value is one of the choices.

Normally called in ConfigValue.deserialize.

validate_maximum 

validate_maximum[CT: Comparable](value: CT, maximum: CT | None) -> None

Validate that value is at most maximum.

Normally called in ConfigValue.deserialize.

validate_minimum 

validate_minimum[CT: Comparable](value: CT, minimum: CT | None) -> None

Validate that value is at least minimum.

Normally called in ConfigValue.deserialize.

validate_required 

validate_required(value: Any, required: bool) -> None

Validate that value is set if required.

Normally called in ConfigValue.deserialize on the raw string, not the converted value.