Adrian Sampson avatar Adrian Sampson committed 6df6507

style tweaks & doc expansion (#98)

Comments (0)

Files changed (3)

beets/autotag/match.py

     """Given a sorted list of AlbumMatch or TrackMatch objects, return a
     recommendation based on the results' distances.
 
-    If the recommendation is higher than the configured maximum for albums with
-    missing/extra tracks or differing track lengths/numbers, the recommendation
-    will be downgraded to the match configured maximum.
+    If the recommendation is higher than the configured maximum for
+    certain situations, the recommendation will be downgraded to the
+    configured maximum.
     """
     if not results:
         # No candidates: no recommendation.
+        return recommendation.none
+
+    # Basic distance thresholding.
+    min_dist = results[0].distance
+    if min_dist < config['match']['strong_rec_thresh'].as_number():
+        # Strong recommendation level.
+        rec = recommendation.strong
+    elif min_dist <= config['match']['medium_rec_thresh'].as_number():
+        # Medium recommendation level.
+        rec = recommendation.medium
+    elif len(results) == 1:
+        # Only a single candidate.
+        rec = recommendation.low
+    elif results[1].distance - min_dist >= \
+            config['match']['rec_gap_thresh'].as_number():
+        # Gap between first two candidates is large.
+        rec = recommendation.low
+    else:
+        # No conclusion.
         rec = recommendation.none
-    else:
-        min_dist = results[0].distance
-        if min_dist < config['match']['strong_rec_thresh'].as_number():
-            # Strong recommendation level.
-            rec = recommendation.strong
-        elif min_dist <= config['match']['medium_rec_thresh'].as_number():
-            # Medium recommendation level.
-            rec = recommendation.medium
-        elif len(results) == 1:
-            # Only a single candidate.
-            rec = recommendation.low
-        elif results[1].distance - min_dist >= \
-                config['match']['rec_gap_thresh'].as_number():
-            # Gap between first two candidates is large.
-            rec = recommendation.low
-        else:
-            # No conclusion.
-            rec = recommendation.none
-        # Downgrade recommendation according to configured maximums.
-        if isinstance(results[0], hooks.AlbumMatch):
-            # Maximum recommendations.
-            max_rec = {}
-            for trigger in ('partial', 'tracklength', 'tracknumber'):
-                max_rec[trigger] = \
-                    config['match']['max_rec'][trigger].as_choice({
-                        'strong': recommendation.strong,
-                        'medium': recommendation.medium,
-                        'low': recommendation.low,
-                        'none': recommendation.none,
-                    })
-            # Partial match.
-            if rec > max_rec['partial'] and \
-                    (results[0].extra_items or results[0].extra_tracks):
-                rec = max_rec['partial']
-            downgraded = False
-            # Check track number and duration for each item.
-            for item, track_info in results[0].mapping.items():
-                # Track length differs.
-                if rec > max_rec['tracklength'] and item.length and \
-                        track_info.length and \
-                        abs(item.length - track_info.length) > \
-                        TRACK_LENGTH_GRACE:
-                    rec = max_rec['tracklength']
-                    downgraded = True
-                # Track number differs.
-                elif rec > max_rec['tracknumber'] and item.track not in \
-                        (track_info.index, track_info.medium_index):
-                    rec = max_rec['tracknumber']
-                    downgraded = True
-                if downgraded:
-                    break
+
+    # "Downgrades" in certain configured situations.
+    if isinstance(results[0], hooks.AlbumMatch):
+        # Load the configured recommendation maxima.
+        max_rec = {}
+        for trigger in 'partial', 'tracklength', 'tracknumber':
+            max_rec[trigger] = \
+                config['match']['max_rec'][trigger].as_choice({
+                    'strong': recommendation.strong,
+                    'medium': recommendation.medium,
+                    'low': recommendation.low,
+                    'none': recommendation.none,
+                })
+
+        # Partial match.
+        if rec > max_rec['partial'] and \
+                (results[0].extra_items or results[0].extra_tracks):
+            rec = max_rec['partial']
+
+        # Check track number and duration for each item.
+        for item, track_info in results[0].mapping.items():
+            # Track length differs.
+            if rec > max_rec['tracklength'] and \
+                    item.length and track_info.length and \
+                    abs(item.length - track_info.length) > TRACK_LENGTH_GRACE:
+                rec = max_rec['tracklength']
+                break
+
+            # Track number differs.
+            elif rec > max_rec['tracknumber'] and item.track not in \
+                    (track_info.index, track_info.medium_index):
+                rec = max_rec['tracknumber']
+                break
+
     return rec
 
 def _add_candidate(items, results, info):

docs/changelog.rst

 * :ref:`none_rec_action` lets you skip the prompt, and automatically choose an
   action, when there is no good candidate. Thanks to Tai Lee.
 * :ref:`max_rec` lets you define a maximum recommendation for albums with
-  missing/extra tracks or differing track lengths/numbers.
+  missing/extra tracks or differing track lengths/numbers. Thanks again to Tai
+  Lee.
 * :ref:`clutter` controls which files should be ignored when cleaning up empty
   directories. Thanks to Steinþór Pálsson.
 * :doc:`/plugins/lastgenre`: A new configuration option lets you choose to
 * Some changes to the way candidates are recommended for selection, thanks to
   Tai Lee:
 
-  * Partial album matches are downgraded to a "low" recommendation by default.
+  * According to the new :ref:`max_rec` configuration option, partial album
+    matches are downgraded to a "low" recommendation by default.
   * When a match isn't great but is either better than all the others or the
     only match, it is given a "low" (rather than "medium") recommendation.
   * There is no prompt default (i.e., input is required) when matches are

docs/reference/config.rst

 max_rec
 ~~~~~~~
 
-You can define a maximum recommendation for albums with missing/extra tracks or
-differing track lengths/numbers::
+As mentioned above, autotagger matches have *recommendations* that control how
+the UI behaves for a certain quality of match. The recommendation for a certain
+match is usually based on the distance calculation. But you can also control
+the recommendation for certain specific situations by defining *maximum*
+recommendations when (a) a match has missing/extra tracks; (b) the track number
+for at least one track differs; or (c) the track length for at least one track
+differs.
+
+To define maxima, use keys under ``max_rec:`` in the ``match`` section::
 
     match:
         max_rec:
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.