Media file tags can be customized with the write event

Author: Thomas Scholtes

beets/library.py

@@ -473,15 +473,16 @@ def write(self, path=None):
         else:
             path = normpath(path)
 
-        plugins.send('write', item=self, path=path)
+        tags = dict(self)
+        plugins.send('write', item=self, path=path, tags=tags)
 
         try:
             mediafile = MediaFile(syspath(path),
                                   id3v23=beets.config['id3v23'].get(bool))
         except (OSError, IOError, UnreadableFileError) as exc:
             raise ReadError(self.path, exc)
 
-        mediafile.update(self)
+        mediafile.update(tags)
         try:
             mediafile.save()
         except (OSError, IOError, MutagenError) as exc:

docs/changelog.rst

@@ -68,6 +68,8 @@ Fixes:
   this case.
 * :doc:`/plugins/convert`: Fix filename extensions when converting
   automatically.
+* The ``write`` event allows plugins to change the tags that are
+  written to a media file.
 
 .. _discogs_client: https://github.com/discogs/discogs_client
 

docs/dev/plugins.rst

@@ -143,11 +143,14 @@ currently available are:
   or album's part) is removed from the library (even when its file is not
   deleted from disk).
 
-* *write*: called with an ``Item`` object just before a file's metadata is
-  written to disk (i.e., just before the file on disk is opened). Event
-  handlers may raise a ``library.FileOperationError`` exception to abort
-  the write operation. Beets will catch that exception, print an error
-  message and continue.
+* *write*: 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*: called with an ``Item`` object after a file's metadata is
   written to disk (i.e., just after the file on disk is closed).

test/test_plugins.py

@@ -14,16 +14,17 @@
 
 from mock import patch
 from _common import unittest
-from helper import TestHelper
+import helper
 
 from beets import plugins
 from beets.library import Item
 from beets.dbcore import types
+from beets.mediafile import MediaFile
 
 
-class PluginTest(unittest.TestCase, TestHelper):
+class TestHelper(helper.TestHelper):
 
-    def setUp(self):
+    def setup_plugin_loader(self):
         # FIXME the mocking code is horrific, but this is the lowest and
         # earliest level of the plugin mechanism we can hook into.
         self._plugin_loader_patch = patch('beets.plugins.load_plugins')
@@ -35,9 +36,22 @@ def myload(names=()):
         load_plugins.side_effect = myload
         self.setup_beets()
 
-    def tearDown(self):
+    def teardown_plugin_loader(self):
         self._plugin_loader_patch.stop()
         self.unload_plugins()
+
+    def register_plugin(self, plugin_class):
+        self._plugin_classes.add(plugin_class)
+
+
+class ItemTypesTest(unittest.TestCase, TestHelper):
+
+    def setUp(self):
+        self.setup_plugin_loader()
+        self.setup_beets()
+
+    def tearDown(self):
+        self.teardown_plugin_loader()
         self.teardown_beets()
 
     def test_flex_field_type(self):
@@ -64,8 +78,38 @@ class RatingPlugin(plugins.BeetsPlugin):
         out = self.run_with_output('ls', 'rating:3..5')
         self.assertNotIn('aaa', out)
 
-    def register_plugin(self, plugin_class):
-        self._plugin_classes.add(plugin_class)
+
+class ItemWriteTest(unittest.TestCase, TestHelper):
+
+    def setUp(self):
+        self.setup_plugin_loader()
+        self.setup_beets()
+
+        class EventListenerPlugin(plugins.BeetsPlugin):
+            pass
+        self.event_listener_plugin = EventListenerPlugin
+        self.register_plugin(EventListenerPlugin)
+
+    def tearDown(self):
+        self.teardown_plugin_loader()
+        self.teardown_beets()
+
+    def test_change_tags(self):
+
+        def on_write(item=None, path=None, tags=None):
+            if tags['artist'] == 'XXX':
+                tags['artist'] = 'YYY'
+
+        self.register_listener('write', on_write)
+
+        item = self.add_item_fixture(artist='XXX')
+        item.write()
+
+        mediafile = MediaFile(item.path)
+        self.assertEqual(mediafile.artist, 'YYY')
+
+    def register_listener(self, event, func):
+        self.event_listener_plugin.register_listener(event, func)
 
 
 def suite():