Improve documentation

beets/library.py

@@ -1648,20 +1648,6 @@ class DefaultTemplateFunctions(object):
             return falseval
 
 
-def apply_item_changes(lib, item, move, pretend, write):
-    """Store, move and write the item according to the arguments.
-    """
-    if pretend:
-        return
-
-    # Move the item if it's in the library.
-    if move and lib.directory in util.ancestry(item.path):
-        item.move(with_album=False)
-
-    if write:
-        item.try_write()
-    item.store()
-
 # Get the name of tmpl_* functions in the above class.
 DefaultTemplateFunctions._func_names = \
     [s for s in dir(DefaultTemplateFunctions)

beets/plugins.py

@@ -206,7 +206,7 @@ class BeetsPlugin(object):
 
         ``descriptor`` must be an instance of ``mediafile.MediaField``.
         """
-        # Defer impor to prevent circular dependency
+        # Defer import to prevent circular dependency
         from beets import library
         mediafile.MediaFile.add_field(name, descriptor)
         library.Item._media_fields.add(name)
@@ -590,6 +590,36 @@ def get_distance(config, data_source, info):
     return dist
 
 
+def apply_item_changes(lib, item, move, pretend, write):
+    """Store, move, and write the item according to the arguments.
+
+    :param lib: beets library.
+    :type lib: beets.library.Library
+    :param item: Item whose changes to apply.
+    :type item: beets.library.Item
+    :param move: Move the item if it's in the library.
+    :type move: bool
+    :param pretend: Return without moving, writing, or storing the item's
+        metadata.
+    :type pretend: bool
+    :param write: Write the item's metadata to its media file.
+    :type write: bool
+    """
+    if pretend:
+        return
+
+    from beets import util
+
+    # Move the item if it's in the library.
+    if move and lib.directory in util.ancestry(item.path):
+        item.move(with_album=False)
+
+    if write:
+        item.try_write()
+
+    item.store()
+
+
 @six.add_metaclass(abc.ABCMeta)
 class MetadataSourcePlugin(object):
     def __init__(self):
@@ -633,12 +663,18 @@ class MetadataSourcePlugin(object):
         """Returns an artist string (all artists) and an artist_id (the main
         artist) for a list of artist object dicts.
 
-        :param artists: Iterable of artist dicts returned by API.
-        :type artists: list[dict]
-        :param id_key: Key or index corresponding to ``artist_id`` value.
+        For each artist, this function moves articles (such as 'a', 'an',
+        and 'the') to the front and strips trailing disambiguation numbers. It
+        returns a tuple of containing the space-separated string of all
+        normalized artists and the ``id`` of the main artist.
+
+        :param artists: Iterable of artist dicts or lists returned by API.
+        :type artists: list[dict] or list[list]
+        :param id_key: Key or index corresponding to ``artist_id``
+            value (the main artist).
         :type id_key: str or int
         :param name_key: Key or index corresponding to values to concatenate
-            for ``artist``.
+            for the artist string (all artists)
         :type name_key: str or int
         :return: Normalized artist string.
         :rtype: str

beetsplug/bpsync.py

@@ -17,7 +17,7 @@
 """
 from __future__ import division, absolute_import, print_function
 
-from beets.plugins import BeetsPlugin
+from beets.plugins import BeetsPlugin, apply_item_changes
 from beets import autotag, library, ui, util
 
 from .beatport import BeatportPlugin
@@ -97,7 +97,7 @@ class BPSyncPlugin(BeetsPlugin):
             trackinfo = self.beatport_plugin.track_for_id(item.mb_trackid)
             with lib.transaction():
                 autotag.apply_item_metadata(item, trackinfo)
-                library.apply_item_changes(lib, item, move, pretend, write)
+                apply_item_changes(lib, item, move, pretend, write)
 
     @staticmethod
     def is_beatport_track(item):
@@ -172,9 +172,7 @@ class BPSyncPlugin(BeetsPlugin):
                     changed |= item_changed
                     if item_changed:
                         any_changed_item = item
-                        library.apply_item_changes(
-                            lib, item, move, pretend, write
-                        )
+                        apply_item_changes(lib, item, move, pretend, write)
 
                 if pretend or not changed:
                     continue

beetsplug/mbsync.py

@@ -17,7 +17,7 @@
 """
 from __future__ import division, absolute_import, print_function
 
-from beets.plugins import BeetsPlugin
+from beets.plugins import BeetsPlugin, apply_item_changes
 from beets import autotag, library, ui, util
 from beets.autotag import hooks
 from collections import defaultdict
@@ -90,7 +90,7 @@ class MBSyncPlugin(BeetsPlugin):
             # Apply.
             with lib.transaction():
                 autotag.apply_item_metadata(item, track_info)
-                library.apply_item_changes(lib, item, move, pretend, write)
+                apply_item_changes(lib, item, move, pretend, write)
 
     def albums(self, lib, query, move, pretend, write):
         """Retrieve and apply info from the autotagger for albums matched by
@@ -162,9 +162,7 @@ class MBSyncPlugin(BeetsPlugin):
                     changed |= item_changed
                     if item_changed:
                         any_changed_item = item
-                        library.apply_item_changes(
-                            lib, item, move, pretend, write
-                        )
+                        apply_item_changes(lib, item, move, pretend, write)
 
                 if not changed:
                     # No change to any item.

docs/plugins/bpsync.rst

@@ -2,13 +2,13 @@ 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.
+from Beatport for albums and tracks that already have Beatport IDs.
+This plugins works similarly to :doc:`/plugins/mbsync`.
+
+If you have purchased music from 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
@@ -32,6 +32,3 @@ The command has a few command-line options:
 * 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.