Add alternatives.update_item event (#148)

Author: geigerzaehler

CHANGELOG.md

@@ -1,79 +1,95 @@
-Change Log
-==========
+# Change Log
 
 ## Unreleased
-* Promote `typing-extensions` to runtime dependency
-* Improved disk write performance when encoding items
+
+- Promote `typing-extensions` to runtime dependency
+- Improved disk write performance when encoding items
+- You can now hook into collection updates and run your own logic using the
+  `alternatives.item_updated` event.
 
 ## v0.13.3 - 2025-05-12
-* Add support for beets v2.3.x
+
+- Add support for beets v2.3.x
 
 ## v0.13.2 - 2025-02-28
-* Make builds more reliable for packagers
+
+- Make builds more reliable for packagers
 
 ## v0.13.1 - 2024-11-17
-* Resize embedded art in alternative files with `albumart_maxwidth` option.
+
+- Resize embedded art in alternative files with `albumart_maxwidth` option.
 
 ## v0.13.0 - 2024-08-17
-* Consistently use Unicode paths to alternative items. This may result and
+
+- Consistently use Unicode paths to alternative items. This may result and
   collection updates and orphaned files in alternatives. It may also improve
   usability on non-standard file systems (see [#74]).
-* Require Python >= 3.10
+- Require Python >= 3.10
 
 [#74]: https://github.com/geigerzaehler/beets-alternatives/issues/74
 
 ## v0.12.0 - 2024-06-25
-* Fix an issue where items in a symlink collection with relative links were
+
+- Fix an issue where items in a symlink collection with relative links were
   always unnecessarily updated.
-* Support [Beets v2](https://beets.readthedocs.io/en/latest/changelog.html#may-30-2024)
+- Support [Beets v2](https://beets.readthedocs.io/en/latest/changelog.html#may-30-2024)
 
 ## v0.11.1 - 2024-04-24
-* Add `--all` flag to update command which will update all configured
+
+- Add `--all` flag to update command which will update all configured
   collections.
 
 ## v0.11.0 - 2023-06-06
-* Use the convert’s plugin [`thread` configuration][convert-config] when
+
+- Use the convert’s plugin [`thread` configuration][convert-config] when
   transcoding files. ([@johnyerhot](https://github.com/johnyerhot))
-* Drop support for Python 2. Require Python >= 3.8
-* Require beets >= 1.6.0
+- Drop support for Python 2. Require Python >= 3.8
+- Require beets >= 1.6.0
 
 [convert-config]: https://beets.readthedocs.io/en/latest/plugins/convert.html#configuration
 
 ## v0.10.2 - 2020-07-15
-* Add `beet alt list-tracks` command
-* SymlinkView: Fix stale symlinks not being removed when files are moved in the
+
+- Add `beet alt list-tracks` command
+- SymlinkView: Fix stale symlinks not being removed when files are moved in the
   main library [#47][]
 
 [#47]: https://github.com/geigerzaehler/beets-alternatives/issues/47
 
 ## v0.10.1 - 2019-09-18
-* Running `beet completion` does not crash anymore [#38][]
+
+- Running `beet completion` does not crash anymore [#38][]
 
 [#38]: https://github.com/geigerzaehler/beets-alternatives/issues/38
 
 ## v0.10.0 - 2019-08-25
-* Symlink views now support relative symlinks (@daviddavo)
-* Running just `beet alt` does not throw an error anymore (@daviddavo)
+
+- Symlink views now support relative symlinks (@daviddavo)
+- Running just `beet alt` does not throw an error anymore (@daviddavo)
 
 ## v0.9.0 - 2018-11-24
-* The package is now on PyPI
-* Require at least beets v1.4.7
-* Update album art in alternatives when it changes
-* Python 3 support (Python 2.7 continuous to be supported)
-* Support the format aliases defined by the convert plugin ('wma' and 'vorbis'
+
+- The package is now on PyPI
+- Require at least beets v1.4.7
+- Update album art in alternatives when it changes
+- Python 3 support (Python 2.7 continuous to be supported)
+- Support the format aliases defined by the convert plugin ('wma' and 'vorbis'
   with current beets)
-* Bugfix: Explicitly write tags after encoding instead of relying on the
+- Bugfix: Explicitly write tags after encoding instead of relying on the
   encoder to do so
-* Bugfix: If the `formats` config option is modified, don't move files if the
+- Bugfix: If the `formats` config option is modified, don't move files if the
   extension would change, but re-encode
 
 ## v0.8.2 - 2015-05-31
-* Fix a bug that made the plugin crash when reading unicode strings
+
+- Fix a bug that made the plugin crash when reading unicode strings
   from the configuration
 
 ## v0.8.1 - 2015-05-30
-* Require beets v1.3.13 and drop support for all older versions.
-* Embed cover art when converting items
+
+- Require beets v1.3.13 and drop support for all older versions.
+- Embed cover art when converting items
 
 ## v0.8.0 - 2015-04-14
+
 First proper release

README.md

@@ -168,7 +168,8 @@ alternatives:
     link_type: relative
 ```
 
-With this config, the `beet alt update by-year` command will create relative symlinks. E.g:
+With this config, the `beet alt update by-year` command will create relative
+symlinks. E.g:
 
 ```plain
 /music/by-year/1982/Thriller/Beat It.mp3
@@ -260,8 +261,7 @@ following settings.
 * **`albumart_maxwidth`** Downscale the embedded album art to a width
   of maximum `albumart_maxwidth` pixels. The aspect ratio of the image
   will be preserved. This is comparable to the setting with the same
-  name of the [convert plugin][convert plugin]. 
-
+  name of the [convert plugin][convert plugin].
 
 * **`removable`** If this is `true` (the default) and `directory` does
   not exist, the `update` command will ask you to confirm the creation
@@ -271,6 +271,37 @@ following settings.
   **`formats`** is `link`, it sets the type of links to create. For
   differences between link types and examples see [Symlink Views](#symlink-views).
 
+Events
+------
+
+The plugin emits the `alternatives.item_updated` event after an item (track) is
+added, removed or updated in a collection by the `update` command.You can use
+the [Hook plugin][] to run a shell command whenever an item is updated.
+
+```yaml
+hook:
+  hooks:
+  - event: alternatives.item_updated
+    command: "bash -c 'echo \"{collection}: {action} {item.path}\" >> events.log"
+```
+
+Alternatively, you can [listen for events][] from a custom plugin.
+
+The event listener receives the following arguments:
+
+* `collection: str` — name of the collection
+* [`item: beets.Item`][Item] — library item the action is taken on
+* `path: str` — absolute path of the item in the collection
+* `action: str` — type of update action:
+  * `ADD`: The item is added to the collection and was not present before
+  * `REMOVE`: The item is removed from the collection
+  * `MOVE`: The file for an item is moved to a different location in the collection
+  * `WRITE`: Updated metadata is written to the file in the collection
+  * `SYNC_ART`: Updated album art is written to the file in the collection
+
+[hook plugin]: https://beets.readthedocs.io/en/stable/plugins/hook.html
+[listen for events]: https://beets.readthedocs.io/en/stable/dev/plugins.html#listen-for-events
+[Item]: https://beets.readthedocs.io/en/stable/dev/library.html#beets.library.Item
 
 Feature Requests
 ----------------
@@ -283,7 +314,6 @@ The following is a list of things I might add in the feature.
 * Symbolic links for each artist in a multiple artists release (see the
   [beets issue][beets-issue-split-symlinks])
 
-
 License
 -------
 
@@ -307,7 +337,6 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-
 [beets-docs]: https://beets.readthedocs.io/en/latest/index.html
 [beets-issue-split-symlinks]: https://github.com/sampsyo/beets/issues/153
 [config-directory]: http://beets.readthedocs.org/en/latest/reference/config.html#directory

beetsplug/alternatives.py

@@ -22,6 +22,7 @@
 from typing import Literal, TypeVar
 
 import beets
+import beets.plugins
 import beetsplug.convert as convert
 import confuse
 from beets import art, util
@@ -231,11 +232,22 @@ def __init__(self, collection_id: str, config: confuse.ConfigView, lib: Library)
 
 
 class Action(Enum):
-    ADD = 1
-    REMOVE = 2
-    WRITE = 3
-    MOVE = 4
-    SYNC_ART = 5
+    """Action to take for a track when syncing a collection"""
+
+    #: Track was not present in the collection before and is added
+    ADD = "ADD"
+
+    #: Remove the track from the collection
+    REMOVE = "REMOVE"
+
+    #: Write tags
+    WRITE = "WRITE"
+
+    #: Move the file for an existing track in a collection to a different path.
+    MOVE = "MOVE"
+
+    #: Write album art to the track’s metadata
+    SYNC_ART = "SYNC_ART"
 
 
 class External:
@@ -323,13 +335,20 @@ def finalize_converted_item(item: Item, dest: Path):
                 self._sync_art(item, dest)
             self._set_stored_path(item, dest)
             item.store()
+            _send_item_updated(
+                collection=self._config.collection_id,
+                path=dest,
+                item=item,
+                action=action,
+            )
 
         converter, converting_done = self._converter()
         with converter as converter:
             for item, actions in self._items_actions():
                 dest = self.destination(item)
                 path = self._get_stored_path(item)
                 for action in actions:
+                    delay_finalize = False
                     if action == Action.MOVE:
                         assert (
                             path is not None
@@ -358,6 +377,7 @@ def finalize_converted_item(item: Item, dest: Path):
                         print_(f"+{dest}")
                         dest.parent.mkdir(exist_ok=True, parents=True)
                         if self._should_transcode(item):
+                            delay_finalize = True
                             converter.run(item, dest)
                         else:
                             self._log.debug(f"copying {dest}")
@@ -375,6 +395,14 @@ def finalize_converted_item(item: Item, dest: Path):
                         self._remove_file(item)
                         item.store()
 
+                    if not delay_finalize:
+                        _send_item_updated(
+                            collection=self._config.collection_id,
+                            path=dest,
+                            item=item,
+                            action=action,
+                        )
+
                 for item, dest in _get_queue_available(converting_done):
                     finalize_converted_item(item, dest)
 
@@ -514,17 +542,24 @@ def update(self, create: bool | None = None):
                     self._remove_file(item)
                     self._create_symlink(item)
                     self._set_stored_path(item, dest)
+                    item.store()
                 elif action == Action.ADD:
                     print_(f"+{dest}")
                     self._create_symlink(item)
                     self._set_stored_path(item, dest)
+                    item.store()
                 elif action == Action.REMOVE:
                     assert path is not None  # action guarantees that `path` is not none
                     print_(f"-{path}")
                     self._remove_file(item)
-                else:
-                    continue
-                item.store()
+                    item.store()
+
+                _send_item_updated(
+                    collection=self._config.collection_id,
+                    path=dest,
+                    item=item,
+                    action=action,
+                )
 
     def _create_symlink(self, item: Item):
         dest = self.destination(item)
@@ -573,6 +608,16 @@ def _get_queue_available(q: queue.Queue[_T] | queue.SimpleQueue[_T]):
         yield item
 
 
+def _send_item_updated(*, collection: str, path: Path, item: Item, action: Action):
+    beets.plugins.send(
+        "alternatives.item_updated",
+        collection=collection,
+        path=path,
+        item=item,
+        action=action.value,
+    )
+
+
 _beets_version = tuple(map(int, beets.__version__.split(".")[0:2]))
 
 if _beets_version >= (2, 3):