BeetsPlugin

class beets.plugins.BeetsPlugin(name: str | None = None)

Bases: object

The base class for all beets plugins. Plugins provide functionality by defining a subclass of BeetsPlugin and overriding the abstract methods defined here.

__init__(name: str | None = None)

Perform one-time plugin setup.

Public methods summary

add_media_field(name, descriptor)	Add a field that is synchronized between media files and items.
commands()	Should return a list of beets.ui.Subcommand objects for commands that should be added to beets' CLI.
get_early_import_stages()	Return a list of functions that should be called as importer pipelines stages early in the pipeline.
get_import_stages()	Return a list of functions that should be called as importer pipelines stages.
queries()	Return a dict mapping prefixes to Query subclasses.
register_listener(event, func)	Add a function as a listener for the specified event.
template_field(name)	Decorator that registers a path template field computation.
template_func(name)	Decorator that registers a path template function.

Methods definition

add_media_field(name: str, descriptor: MediaField) → None

Add a field that is synchronized between media files and items.

When a media field is added item.write() will set the name property of the item's MediaFile to item[name] and save the changes. Similarly item.read() will set item[name] to the value of the name property of the media file.

commands() → Sequence[Subcommand]

Should return a list of beets.ui.Subcommand objects for commands that should be added to beets' CLI.

get_early_import_stages() → list[ImportStageFunc]

Return a list of functions that should be called as importer pipelines stages early in the pipeline.

The callables are wrapped versions of the functions in self.early_import_stages. Wrapping provides some bookkeeping for the plugin: specifically, the logging level is adjusted to WARNING.

get_import_stages() → list[ImportStageFunc]

Return a list of functions that should be called as importer pipelines stages.

The callables are wrapped versions of the functions in self.import_stages. Wrapping provides some bookkeeping for the plugin: specifically, the logging level is adjusted to WARNING.

queries() → dict[str, type[Query]]

Return a dict mapping prefixes to Query subclasses.

register_listener(event: EventType, func: Listener) → None

Add a function as a listener for the specified event.

classmethod template_field(name: str) → Callable[[TFunc[Item]], TFunc[Item]]

Decorator that registers a path template field computation. The value will be referenced as $name from path format strings. The function must accept a single parameter, the Item being formatted.

classmethod template_func(name: str) → Callable[[TFunc[str]], TFunc[str]]

Decorator that registers a path template function. The function will be invoked as %name{} from path format strings.