diff --git a/docs/dev/plugins/events.rst b/docs/dev/plugins/events.rst index 3895d35aa..325b01b33 100644 --- a/docs/dev/plugins/events.rst +++ b/docs/dev/plugins/events.rst @@ -44,163 +44,176 @@ registration process in this case: def loaded(self): self._log.info("Plugin loaded!") -.. list-table:: Plugin Events - :widths: 15 25 60 - :header-rows: 1 +.. rubric:: Plugin Events - - - Event - - Parameters - - Description - - - `pluginload` - - - - called after all the plugins have been loaded after the ``beet`` command - starts - - - `import` - - :py:class:`lib `, ``paths`` is a list of paths - (strings) - - called after the ``import`` command finishes. - - - `album_imported` - - :py:class:`lib `, :py:class:`album +``pluginload`` + :Parameters: (none) + :Description: Called after all plugins have been loaded after the ``beet`` + command starts. + +``import`` + :Parameters: :py:class:`lib `, ``paths`` (list of + path strings) + :Description: Called after the ``import`` command finishes. + +``album_imported`` + :Parameters: :py:class:`lib `, :py:class:`album ` - - called every time the ``import`` command finishes adding an album to the - library - - - `album_removed` - - :py:class:`lib `, :py:class:`album + :Description: Called every time the importer finishes adding an album to the + library. + +``album_removed`` + :Parameters: :py:class:`lib `, :py:class:`album ` - - called every time an album is removed from the library (even when its - file is not deleted from disk) - - - `item_copied` - - :py:class:`item `, ``source`` path, ``destination`` - path - - called whenever an item file is copied - - - `item_imported` - - :py:class:`lib `, :py:class:`item + :Description: Called every time an album is removed from the library (even + when its files are not deleted from disk). + +``item_copied`` + :Parameters: :py:class:`item `, ``source`` (path), + ``destination`` (path) + :Description: Called whenever an item file is copied. + +``item_imported`` + :Parameters: :py:class:`lib `, :py:class:`item ` - - called every time the importer adds a singleton to the library (not - called for full-album imports) - - - `before_item_imported` - - :py:class:`item `, ``source`` path, ``destination`` - path - - called with an item object immediately before it is imported - - - `before_item_moved` - - :py:class:`item `, ``source`` path, ``destination`` - path - - called with an ``Item`` object immediately before its file is moved - - - `item_moved` - - :py:class:`item `, ``source`` path, ``destination`` - path - - called with an ``Item`` object whenever its file is moved - - - `item_linked` - - :py:class:`item `, ``source`` path, ``destination`` - path - - called with an ``Item`` object whenever a symlink is created for a file - - - `item_hardlinked` - - :py:class:`item `, ``source`` path, ``destination`` - path - - called with an ``Item`` object whenever a hardlink is created for a file - - - `item_reflinked` - - :py:class:`item `, ``source`` path, ``destination`` - path - - called with an ``Item`` object whenever a reflink is created for a file - - - `item_removed` - - :py:class:`item ` - - called with an ``Item`` object every time an item (singleton or album's - part) is removed from the library (even when its file is not deleted - from disk). - - - `write` - - :py:class:`item `, ``path``, ``tags`` dictionary - - called with an ``Item`` object, a ``path``, and a ``tags`` dictionary - just before a file's metadata is written to disk (i.e., just before the - file on disk is opened). Event handlers may change the ``tags`` - dictionary to customize the tags that are written to the media file. - Event handlers may also raise a ``library.FileOperationError`` exception - to abort the write operation. Beets will catch that exception, print an - error message, and continue. - - - `after_write` - - :py:class:`item ` - - called with an ``Item`` object after a file's metadata is written to - disk (i.e., just after the file on disk is closed). - - - `import_task_created` - - :py:class:`task `, :py:class:`session - ` - - called immediately after an import task is initialized. Plugins can use - this to, for example, change imported files of a task before anything - else happens. It's also possible to replace the task with another task - by returning a list of tasks. This list can contain zero or more - ImportTasks. Returning an empty list will stop the task. - - - `import_task_start` - - :py:class:`task `, :py:class:`session - ` - - called when before an import task begins processing. - - - `import_task_apply` - - :py:class:`task `, :py:class:`session - ` - - called after metadata changes have been applied in an import task. This - is called on the same thread as the UI, so use this sparingly and only - for tasks that can be done quickly. For most plugins, an import pipeline - stage is a better choice (see :ref:`plugin-stage`). - - - `import_task_before_choice` - - :py:class:`task `, :py:class:`session - ` - - called after candidate search for an import task before any decision is - made about how/if to import or tag. Can be used to present information - about the task or initiate interaction with the user before importing - occurs. Return an importer action to take a specific action. Only one - handler may return a non-None result. - - - `import_task_choice` - - :py:class:`task `, :py:class:`session - ` - - called after a decision has been made about an import task. This event - can be used to initiate further interaction with the user. Use - ``task.choice_flag`` to determine or change the action to be taken. - - - `import_task_files` - - :py:class:`task `, :py:class:`session - ` - - called after an import task finishes manipulating the filesystem - (copying and moving files, writing metadata tags). - - - `library_opened` - - :py:class:`lib ` - - called after beets starts up and initializes the main Library object. - - - `database_change` - - :py:class:`lib `, :py:class:`model + :Description: Called every time the importer adds a singleton to the library + (not called for full-album imports). + +``before_item_imported`` + :Parameters: :py:class:`item `, ``source`` (path), + ``destination`` (path) + :Description: Called with an ``Item`` object immediately before it is + imported. + +``before_item_moved`` + :Parameters: :py:class:`item `, ``source`` (path), + ``destination`` (path) + :Description: Called with an ``Item`` object immediately before its file is + moved. + +``item_moved`` + :Parameters: :py:class:`item `, ``source`` (path), + ``destination`` (path) + :Description: Called with an ``Item`` object whenever its file is moved. + +``item_linked`` + :Parameters: :py:class:`item `, ``source`` (path), + ``destination`` (path) + :Description: Called with an ``Item`` object whenever a symlink is created + for a file. + +``item_hardlinked`` + :Parameters: :py:class:`item `, ``source`` (path), + ``destination`` (path) + :Description: Called with an ``Item`` object whenever a hardlink is created + for a file. + +``item_reflinked`` + :Parameters: :py:class:`item `, ``source`` (path), + ``destination`` (path) + :Description: Called with an ``Item`` object whenever a reflink is created + for a file. + +``item_removed`` + :Parameters: :py:class:`item ` + :Description: Called with an ``Item`` object every time an item (singleton + or part of an album) is removed from the library (even when its file is + not deleted from disk). + +``write`` + :Parameters: :py:class:`item `, ``path`` (path), + ``tags`` (dict) + :Description: Called just before a file's metadata is written to disk. + Handlers may modify ``tags`` or raise ``library.FileOperationError`` to + abort. + +``after_write`` + :Parameters: :py:class:`item ` + :Description: Called after a file's metadata is written to disk. + +``import_task_created`` + :Parameters: :py:class:`task `, + :py:class:`session ` + :Description: Called immediately after an import task is initialized. May + return a list (possibly empty) of replacement tasks. + +``import_task_start`` + :Parameters: :py:class:`task `, + :py:class:`session ` + :Description: Called before an import task begins processing. + +``import_task_apply`` + :Parameters: :py:class:`task `, + :py:class:`session ` + :Description: Called after metadata changes have been applied in an import + task (on the UI thread; keep fast). Prefer a pipeline stage otherwise + (see :ref:`plugin-stage`). + +``import_task_before_choice`` + :Parameters: :py:class:`task `, + :py:class:`session ` + :Description: Called after candidate search and before deciding how to + import. May return an importer action (only one handler may return + non-None). + +``import_task_choice`` + :Parameters: :py:class:`task `, + :py:class:`session ` + :Description: Called after a decision has been made about an import task. + Use ``task.choice_flag`` to inspect or change the action. + +``import_task_files`` + :Parameters: :py:class:`task `, + :py:class:`session ` + :Description: Called after filesystem manipulation (copy/move/write) for an + import task. + +``library_opened`` + :Parameters: :py:class:`lib ` + :Description: Called after beets starts and initializes the main Library + object. + +``database_change`` + :Parameters: :py:class:`lib `, :py:class:`model ` - - a modification has been made to the library database. The change might - not be committed yet. - - - `cli_exit` - - :py:class:`lib ` - - called just before the ``beet`` command-line program exits. - - - `import_begin` - - :py:class:`session ` - - called just before a ``beet import`` session starts up. - - - `trackinfo_received` - - :py:class:`info ` - - called after metadata for a track item has been fetched from a data - source, such as MusicBrainz. You can modify the tags that the rest of - the pipeline sees on a ``beet import`` operation or during later - adjustments, such as ``mbsync``. - - - `albuminfo_received` - - :py:class:`info ` - - like `trackinfo_received`, the event indicates new metadata for album - items. - - - `before_choose_candidate` - - :py:class:`task `, :py:class:`session - ` - - called before the user is prompted for a decision during a ``beet - import`` interactive session. Plugins can use this event for - :ref:`appending choices to the prompt ` by - returning a list of ``PromptChoices``. - - - `mb_track_extract` - - :py:class:`data ` - - called after the metadata is obtained from MusicBrainz. The parameter is - a ``dict`` containing the tags retrieved from MusicBrainz for a track. - Plugins must return a new (potentially empty) ``dict`` with additional - ``field: value`` pairs, which the autotagger will apply to the item, as - flexible attributes if ``field`` is not a hardcoded field. Fields - already present on the track are overwritten. - - - `mb_album_extract` - - :py:class:`data ` - - Like `mb_track_extract`, but for album tags. Overwrites tags set at the - track level, if they have the same ``field``. + :Description: A modification has been made to the library database (may not + yet be committed). + +``cli_exit`` + :Parameters: :py:class:`lib ` + :Description: Called just before the ``beet`` command-line program exits. + +``import_begin`` + :Parameters: :py:class:`session ` + :Description: Called just before a ``beet import`` session starts. + +``trackinfo_received`` + :Parameters: :py:class:`info ` + :Description: Called after metadata for a track is fetched (e.g., from + MusicBrainz). Handlers can modify the tags seen by later pipeline stages + or adjustments (e.g., ``mbsync``). + +``albuminfo_received`` + :Parameters: :py:class:`info ` + :Description: Like ``trackinfo_received`` but for album-level metadata. + +``before_choose_candidate`` + :Parameters: :py:class:`task `, + :py:class:`session ` + :Description: Called before prompting the user during interactive import. + May return a list of ``PromptChoices`` to append to the prompt (see + :ref:`append_prompt_choices`). + +``mb_track_extract`` + :Parameters: :py:class:`data ` + :Description: Called after metadata is obtained from MusicBrainz for a + track. Must return a (possibly empty) dict of additional ``field: + value`` pairs to apply (overwriting existing fields). + +``mb_album_extract`` + :Parameters: :py:class:`data ` + :Description: Like ``mb_track_extract`` but for album tags. Overwrites tags + set at the track level with the same field. The included ``mpdupdate`` plugin provides an example use case for event listeners.