Add BeforeWriteError for plugins

The idea is that plugins may want to prevent beets from writing a file (for
example if an integrity check failed).

beets/importer.py

@@ -895,13 +895,12 @@ def manipulate_files(session):
             if config['import']['write'] and task.should_write_tags():
                 try:
                     item.write()
-                except mediafile.UnreadableFileError as exc:
-                    log.error(u'error while writing ({0}): {0}'.format(
-                        exc,
-                        util.displayable_path(item.path)
+                except (mediafile.UnreadableFileError,
+                        util.FilesystemError,
+                        plugins.BeforeWriteError) as exc:
+                    log.error(u'could not write {0}: {1}'.format(
+                        util.displayable_path(item.path), exc
                     ))
-                except util.FilesystemError as exc:
-                    exc.log(log)
 
         # Save new paths.
         with session.lib.transaction():

beets/plugins.py

@@ -30,6 +30,15 @@ LASTFM_KEY = '2dc3914abf35f0d9c92d97d8f8e42b43'
 log = logging.getLogger('beets')
 
 
+class BeforeWriteError(Exception):
+    """May be raised by plugins in a ``write`` event handler to abort
+    prevent writing the item's file.
+
+    Beets will catch this exception during a call to ``item.write()``
+    and display it to the user as an error.
+    """
+
+
 # Managing the plugins themselves.
 
 class BeetsPlugin(object):

docs/dev/plugins.rst

@@ -141,7 +141,9 @@ currently available are:
   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).
+  written to disk (i.e., just before the file on disk is opened). Event
+  handlers may raise ``plugins.BeforeWriteError`` to prevent beets from
+  writing the file and display an error to the user.
 
 * *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).