From 92061099feeeee644ae4536f1ca512051a69f72a Mon Sep 17 00:00:00 2001
From: Thomas Scholtes <thomas-scholtes@gmx.de>
Date: Tue, 11 Mar 2014 16:49:04 +0100
Subject: [PATCH] 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    | 11 +++++------
 beets/plugins.py     |  9 +++++++++
 docs/dev/plugins.rst |  4 +++-
 3 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/beets/importer.py b/beets/importer.py
index 00510e47d..6bce22fea 100644
--- a/beets/importer.py
+++ b/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():
diff --git a/beets/plugins.py b/beets/plugins.py
index 813084ca9..da4588a5c 100755
--- a/beets/plugins.py
+++ b/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):
diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst
index f21f41a38..418414806 100644
--- a/docs/dev/plugins.rst
+++ b/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).