From 4205d1a7b9d08accb05d5c5aec35a95fb33fc18e Mon Sep 17 00:00:00 2001
From: Thomas Scholtes <thomas-scholtes@gmx.de>
Date: Tue, 11 Mar 2014 19:18:19 +0100
Subject: [PATCH] Plugins can change task.choice_flag in import_task_choice
 handler

---
 beets/importer.py    | 17 ++++++++++++-----
 docs/dev/plugins.rst |  4 ++--
 2 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/beets/importer.py b/beets/importer.py
index 23a9c2405..00510e47d 100644
--- a/beets/importer.py
+++ b/beets/importer.py
@@ -659,9 +659,16 @@ def initial_lookup(session):
 
 def user_query(session):
     """A coroutine for interfacing with the user about the tagging
-    process. lib is the Library to import into and logfile may be
-    a file-like object for logging the import process. The coroutine
-    accepts and yields ImportTask objects.
+    process.
+
+    The coroutine accepts an ImportTask objects. It uses the
+    session's ``choose_match`` method to determine the ``action`` for
+    this task. Depending on the action additional stages are exectuted
+    and the processed task is yielded.
+
+    It emits the ``import_task_choice`` event for plugins. Plugins have
+    acces to the choice via the ``taks.choice_flag`` property and may
+    choose to change it.
     """
     recent = set()
     task = None
@@ -677,7 +684,7 @@ def user_query(session):
         plugins.send('import_task_choice', session=session, task=task)
 
         # As-tracks: transition to singleton workflow.
-        if choice is action.TRACKS:
+        if task.choice_flag is action.TRACKS:
             # Set up a little pipeline for dealing with the singletons.
             def emitter(task):
                 for item in task.items:
@@ -693,7 +700,7 @@ def user_query(session):
             continue
 
         # As albums: group items by albums and create task for each album
-        if choice is action.ALBUMS:
+        if task.choice_flag is action.ALBUMS:
             def emitter(task):
                 yield task
 
diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst
index 1791adf6d..f21f41a38 100644
--- a/docs/dev/plugins.rst
+++ b/docs/dev/plugins.rst
@@ -154,8 +154,8 @@ currently available are:
 
 * *import_task_choice*: called after a decision has been made about an import
   task. This event can be used to initiate further interaction with the user.
-  Use ``task.choice_flag`` to determine the action to be taken. Parameters:
-  ``task`` and ``session``.
+  Use ``task.choice_flag`` to determine or change the action to be
+  taken. Parameters: ``task`` and ``session``.
 
 * *import_task_files*: called after an import task finishes manipulating the
   filesystem (copying and moving files, writing metadata tags). Parameters: