Add documentation, fix circular import

beets/plugins.py

@@ -26,7 +26,7 @@ from functools import wraps
 
 
 import beets
-from beets import library, logging, ui, util
+from beets import logging
 import mediafile
 import six
 

beetsplug/bpsync.py

@@ -13,7 +13,7 @@
 # The above copyright notice and this permission notice shall be
 # included in all copies or substantial portions of the Software.
 
-"""Update library's tags using MusicBrainz.
+"""Update library's tags using Beatport.
 """
 from __future__ import division, absolute_import, print_function
 
@@ -176,17 +176,16 @@ class BPSyncPlugin(BeetsPlugin):
                             lib, item, move, pretend, write
                         )
 
-                if not changed:
+                if not changed or pretend:
                     # No change to any item.
                     continue
 
-                if not pretend:
+                # Update album structure to reflect an item in it.
-                    # Update album structure to reflect an item in it.
+                for key in library.Album.item_keys:
-                    for key in library.Album.item_keys:
+                    album[key] = any_changed_item[key]
-                        album[key] = any_changed_item[key]
+                album.store()
-                    album.store()
 
-                    # Move album art (and any inconsistent items).
+                # Move album art (and any inconsistent items).
-                    if move and lib.directory in util.ancestry(items[0].path):
+                if move and lib.directory in util.ancestry(items[0].path):
-                        self._log.debug(u'moving album {}', album)
+                    self._log.debug(u'moving album {}', album)
-                        album.move()
+                    album.move()

docs/changelog.rst

@@ -75,6 +75,11 @@ New features:
   :bug:`2080`
 * :doc:`/plugins/beatport`: Fix default assignment of the musical key.
   :bug:`3377`
+* :doc:`/plugins/bpsync`: Add `bpsync` plugin to sync metadata changes
+  from the Beatport database.
+* :doc:`/plugins/beatport`: Fix assignment of `genre` and rename `musical_key`
+    to `initial_key`.
+  :bug:`3387`
 
 Fixes:
 

docs/plugins/bpsync.rst

@@ -0,0 +1,37 @@
+BPSync Plugin
+=============
+
+This plugin provides the ``bpsync`` command, which lets you fetch metadata
+from Beatport for albums and tracks that already have Beatport IDs. This
+is useful for updating tags as they are fixed in the Beatport database, or
+when you change your mind about some config options that change how tags are
+written to files. If you have a music library that is already nicely tagged by
+a program that also uses Beatport, this can speed up the initial import if you
+just import "as-is" and then use ``bpsync`` to get up-to-date tags that are written
+to the files according to your beets configuration.
+
+
+Usage
+-----
+
+Enable the ``bpsync`` plugin in your configuration (see :ref:`using-plugins`)
+and then run ``beet bpsync QUERY`` to fetch updated metadata for a part of your
+collection (or omit the query to run over your whole library).
+
+This plugin treats albums and singletons (non-album tracks) separately. It
+first processes all matching singletons and then proceeds on to full albums.
+The same query is used to search for both kinds of entities.
+
+The command has a few command-line options:
+
+* To preview the changes that would be made without applying them, use the
+  ``-p`` (``--pretend``) flag.
+* By default, files will be moved (renamed) according to their metadata if
+  they are inside your beets library directory. To disable this, use the
+  ``-M`` (``--nomove``) command-line option.
+* If you have the ``import.write`` configuration option enabled, then this
+  plugin will write new metadata to files' tags. To disable this, use the
+  ``-W`` (``--nowrite``) option.
+* To customize the output of unrecognized items, use the ``-f``
+  (``--format``) option. The default output is ``format_item`` or
+  ``format_album`` for items and albums, respectively.

docs/plugins/index.rst

@@ -142,6 +142,7 @@ Metadata
 * :doc:`absubmit`: Analyse audio with the `streaming_extractor_music`_ program and submit the metadata to the AcousticBrainz server
 * :doc:`acousticbrainz`: Fetch various AcousticBrainz metadata
 * :doc:`bpm`: Measure tempo using keystrokes.
+* :doc:`bpsync`: Fetch updated metadata from Beatport.
 * :doc:`edit`: Edit metadata from a text editor.
 * :doc:`embedart`: Embed album art images into files' metadata.
 * :doc:`fetchart`: Fetch album cover art from various sources.
@@ -154,7 +155,7 @@ Metadata
 * :doc:`lastgenre`: Fetch genres based on Last.fm tags.
 * :doc:`lastimport`: Collect play counts from Last.fm.
 * :doc:`lyrics`: Automatically fetch song lyrics.
-* :doc:`mbsync`: Fetch updated metadata from MusicBrainz
+* :doc:`mbsync`: Fetch updated metadata from MusicBrainz.
 * :doc:`metasync`: Fetch metadata from local or remote sources
 * :doc:`mpdstats`: Connect to `MPD`_ and update the beets library with play
   statistics (last_played, play_count, skip_count, rating).