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