From ce90b2aae5540146df250f2c59d3ca6c04d399aa Mon Sep 17 00:00:00 2001 From: Rahul Ahuja Date: Sat, 5 Oct 2019 15:07:20 -0700 Subject: [PATCH] Improve documentation --- beets/library.py | 14 ------------- beets/plugins.py | 46 ++++++++++++++++++++++++++++++++++++----- beetsplug/bpsync.py | 8 +++---- beetsplug/mbsync.py | 8 +++---- docs/plugins/bpsync.rst | 17 +++++++-------- 5 files changed, 54 insertions(+), 39 deletions(-) diff --git a/beets/library.py b/beets/library.py index fd48a2ab8..59791959d 100644 --- a/beets/library.py +++ b/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) diff --git a/beets/plugins.py b/beets/plugins.py index 738b48b5e..c688b058f 100644 --- a/beets/plugins.py +++ b/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 diff --git a/beetsplug/bpsync.py b/beetsplug/bpsync.py index 70eb9094a..aefb1517b 100644 --- a/beetsplug/bpsync.py +++ b/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 diff --git a/beetsplug/mbsync.py b/beetsplug/mbsync.py index 18474e6ca..a2b3bc4aa 100644 --- a/beetsplug/mbsync.py +++ b/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. diff --git a/docs/plugins/bpsync.rst b/docs/plugins/bpsync.rst index e43e33e5a..8c576e816 100644 --- a/docs/plugins/bpsync.rst +++ b/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.