Skip to content

Extension API

If you want to learn how to make Mopidy extensions, read Extension development.

mopidy.ext

Classes:

  • Extension –

    Base class for Mopidy extensions.

  • Registry –

    Registry of components provided by Mopidy extensions.

Extension

Base class for Mopidy extensions.

Methods:

  • get_cache_dir –

    Get or create cache directory for the extension.

  • get_command –

    Command to expose to command line users running mopidy.

  • get_config_dir –

    Get or create configuration directory for the extension.

  • get_config_schema –

    The extension's config validation schema.

  • get_data_dir –

    Get or create data directory for the extension.

  • get_default_config –

    The extension's default config as a text string.

  • setup –

    Register the extension's components in the extension [Registry][].

  • validate_environment –

    Check if the extension can run in the current environment.

Attributes:

  • dist_name (str) –

    The extension's distribution name, as registered on PyPI

  • ext_name (str) –

    The extension's short name, as used in setup.py and as config section

  • version (str) –

    The extension's version.

dist_name instance-attribute 

dist_name: str

The extension's distribution name, as registered on PyPI

Example: mopidy-soundspot

ext_name instance-attribute 

ext_name: str

The extension's short name, as used in setup.py and as config section name

Example: soundspot

version instance-attribute 

version: str

The extension's version.

Should match the __version__ attribute on the extension's main Python module and the version registered on PyPI.

get_cache_dir classmethod 

get_cache_dir(config: Config) -> Path

Get or create cache directory for the extension.

Use this directory to cache data that can safely be thrown away.

get_command 

get_command() -> App | None

Command to expose to command line users running mopidy.

This method should return a cyclopts.App instance. The app will be mounted as the mopidy <ext_name> command. It can have subcommands on its own, e.g. mopidy local scan. Please refer to the cyclopts docs for details on how to implement this.

Note

In Mopidy < 4.0, this method returned a custom Command class, which is no longer supported.

get_config_dir classmethod 

get_config_dir(config: Config) -> Path

Get or create configuration directory for the extension.

get_config_schema 

get_config_schema() -> ConfigSchema

The extension's config validation schema.

get_data_dir classmethod 

get_data_dir(config: Config) -> Path

Get or create data directory for the extension.

Use this directory to store data that should be persistent.

get_default_config 

get_default_config() -> str

The extension's default config as a text string.

setup 

setup(registry: Registry) -> None

Register the extension's components in the extension Registry.

For example, to register a backend:

def setup(self, registry):
    from .backend import SoundspotBackend
    registry.add('backend', SoundspotBackend)

See Registry for a list of registry keys with a special meaning. Mopidy will instantiate and start any classes registered under the frontend and backend registry keys.

This method can also be used for other setup tasks not involving the extension registry.

Parameters:

  • registry
    (Registry) –

    The extension registry.

validate_environment 

validate_environment() -> None

Check if the extension can run in the current environment.

Dependencies described by setup.py are checked by Mopidy, so you should not check their presence here.

If a problem is found, raise ExtensionError with a message explaining the issue.

Raises:

  • ExtensionError –

    If the environment is not suitable.

Registry 

Registry()

Bases: Mapping

Registry of components provided by Mopidy extensions.

Passed to the setup method of all extensions. The registry can be used like a dict of string keys and lists.

Some keys have a special meaning, including, but not limited to:

  • backend is used for Mopidy backend classes.
  • frontend is used for Mopidy frontend classes.

Extensions can use the registry to allow others to extend the extension itself. For example, Mopidy-Local historically used the local:library key to allow other extensions to register library providers for it to use. Extensions should namespace custom keys with the extension's ext_name, e.g. local:foo or http:bar.

Methods:

  • add –

    Add a component to the registry.

add 

add(name: str, entry: RegistryEntry) -> None

Add a component to the registry.

Multiple classes can be registered to the same name.