Make Discogs lookups visible, stoppable and resumable

A 1400-track lookup is an hour of work, and it showed nothing until the very
end: results were only applied when the whole run finished, and the cache was
only written in the final block. Stopping or crashing threw away every lookup
already paid for, and while it ran there was no way to tell it apart from a
hang.

Results now land in the Suggested column as they arrive, the status line
reports position, matches so far and rough time remaining, and Stop ends the
run keeping everything fetched. The cache is written every ten lookups, so a
stopped run resumes instead of restarting.

The estimate is also honest now: it counts only tracks that are not already
cached, and excludes ones with no artist or title, which could never match and
were previously costing 2.5 seconds each to ask about anyway.

An optional Discogs token can be saved to move from ~25 to ~60 requests per
minute. It is not required for anything.

Also imports urllib.error explicitly, which the 429 backoff path depended on
getting for free from urllib.request.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: sparkly-quasar

README.md

@@ -110,7 +110,14 @@ nothing to infer from, and it lands in `Unsorted`. The **Genres** tab is the way
 out: select a group and set it, or ask Discogs.
 
 Discogs needs no API token. Its free tier is rate limited, so lookups are paced
-at 2.5s and cached on disk — re-running never asks twice. Queries are cleaned
+at 2.5s and cached on disk — re-running never asks twice. A free personal token
+from discogs.com/settings/developer raises the rate to about one per second;
+paste it into the Genres tab if you're doing a big batch.
+
+A long run reports as it goes: results fill the Suggested column while it works,
+the status line shows how many are done and roughly how long is left, and Stop
+keeps everything already fetched. The cache is written throughout, so a stopped
+or crashed run resumes where it left off rather than starting over. Queries are cleaned
 first (`Track (Original Mix)_PN` → `Track`), which took the hit rate from 1-in-8
 to 6-in-10 on a real batch. Only artist and title are sent.
 

sortero/app.py

@@ -1288,14 +1288,35 @@ def build(self):
                    command=self.apply_manual).pack(side="left")
         ttk.Button(row2, text="Look up selected on Discogs",
                    command=self.lookup).pack(side="left", padx=(16, 0))
+        self.stop_btn = ttk.Button(row2, text="Stop", command=self.stop_lookup,
+                                   state="disabled")
+        self.stop_btn.pack(side="left", padx=4)
         ttk.Button(row2, text="Accept suggestions",
                    command=self.apply_suggested).pack(side="left", padx=6)
 
+        self.lookup_status = ttk.Label(self, text="", foreground="#1d5c3a",
+                                       font=("Helvetica", 12, "bold"))
+        self.lookup_status.pack(anchor="w", pady=(0, 4))
+
+        tok = ttk.Frame(self)
+        tok.pack(fill="x", pady=(0, 6))
+        ttk.Label(tok, text="Discogs token (optional)").pack(side="left")
+        self.token_var = tk.StringVar(value=settings.get("discogs_token") or "")
+        ttk.Entry(tok, textvariable=self.token_var, width=34,
+                  show="•").pack(side="left", padx=6)
+        ttk.Button(tok, text="Save", command=self._save_token).pack(side="left")
+        ttk.Label(tok, foreground="#666",
+                  text="  — works without one; a free token from discogs.com/settings/"
+                       "developer makes lookups about 2.5x faster"
+                  ).pack(side="left")
+
         f, self.tv = tree(self, ("Track", "Artist", "Genre", "Suggested", "Where"),
                           (300, 190, 150, 170, 200), height=15)
         f.pack(fill="both", expand=True)
         self.tv.bind("<<TreeviewSelect>>", lambda e: self._sync())
         self.rows, self.suggested = [], {}
+        self._stop = threading.Event()
+        self._looking = False
 
     def invalidate(self):
         vocab = sorted({lab for _, lab in organize.GENRE_RULES} |
@@ -1380,30 +1401,70 @@ def done(res):
 
         self.app.task.run(work, done, "Writing genres")
 
+    def _save_token(self):
+        settings.set("discogs_token", self.token_var.get().strip())
+        messagebox.showinfo(APP, "Saved. Lookups will run at the faster rate."
+                            if self.token_var.get().strip() else
+                            "Cleared. Lookups will use the slower anonymous rate.")
+
+    def stop_lookup(self):
+        self._stop.set()
+        self.lookup_status.configure(text="Stopping after the current track…")
+
+    def _tick(self):
+        """Refresh the table while a lookup runs, so results appear as they land."""
+        if not self._looking:
+            return
+        self.refresh()
+        self.after(4000, self._tick)
+
     def lookup(self):
-        recs = self._selected()
+        recs = [r for r in self._selected() if genres.worth_asking(r)]
+        skipped = len(self._selected()) - len(recs)
         if not recs:
-            messagebox.showinfo(APP, "Select the tracks you want looked up.")
+            messagebox.showinfo(APP, "Select the tracks you want looked up."
+                                     + (f"\n\n{skipped} have no artist or title to "
+                                        "search with — set those by hand instead."
+                                        if skipped else ""))
             return
-        mins = max(1, round(len(recs) * genres.MIN_INTERVAL / 60))
+        cache = genres.load_cache()
+        fresh = [r for r in recs if genres.key_for(r) not in cache]
+        mins = genres.eta_minutes(len(fresh))
         if not messagebox.askyesno(
                 APP, f"Look up {len(recs)} tracks on Discogs?\n\n"
-                     f"Discogs rate-limits free use, so this is paced and takes "
-                     f"roughly {mins} minute(s). Results are cached, so re-running "
-                     "never asks twice.\n\nArtist and title are sent to Discogs; "
-                     "nothing else leaves your machine."):
+                     f"{len(recs) - len(fresh)} are already cached and cost nothing; "
+                     f"{len(fresh)} need asking, which takes about {mins} minute(s) "
+                     "because Discogs rate-limits free use.\n\n"
+                     "Results appear in the Suggested column as they arrive, and you "
+                     "can Stop at any point — everything fetched is kept."
+                     + (f"\n\n{skipped} selected tracks have no artist or title and "
+                        "were left out." if skipped else "")
+                     + "\n\nOnly artist and title are sent to Discogs."):
             return
 
+        self._stop.clear()
+        self._looking = True
+        self.stop_btn.configure(state="normal")
+        self.lookup_status.configure(text=f"Asking Discogs about {len(recs)} tracks…")
+        self.after(2000, self._tick)
+        results = self.suggested          # worker fills this in as it goes
+
         def work(progress, log):
-            return genres.bulk_lookup(recs, progress=progress, log=log)
+            return genres.bulk_lookup(
+                recs, progress=progress, log=log,
+                on_result=lambda path, val: results.__setitem__(path, val),
+                should_stop=self._stop.is_set)
 
         def done(found):
-            self.suggested.update(found)
-            got = sum(1 for v in found.values() if v[0])
+            self._looking = False
+            self.stop_btn.configure(state="disabled")
+            got = sum(1 for v in self.suggested.values() if v[0])
+            self.lookup_status.configure(
+                text=f"Discogs finished — {got} tracks have a suggested genre.")
             self.refresh()
             messagebox.showinfo(
-                APP, f"Discogs matched {len(found)} tracks; {got} map to a genre "
-                     "Sortero recognises.\n\nReview the Suggested column, then "
+                APP, f"Looked up {len(found)} tracks; {got} map to a genre Sortero "
+                     "recognises.\n\nReview the Suggested column, then "
                      "'Accept suggestions'.")
 
         self.app.task.run(work, done, "Asking Discogs")

sortero/genres.py

@@ -9,17 +9,19 @@
 Discogs' search works without an API token, but the free tier is rate limited,
 so lookups are paced and cached on disk - re-running never re-asks.
 """
-import json, os, re, time, urllib.parse, urllib.request
+import json, os, re, time, urllib.error, urllib.parse, urllib.request
 
-from . import net, paths
+from . import net, paths, settings
 from .journal import Journal
 from .organize import canon_genre
 from .tagio import Track
 from .version import __version__
 
 UA = f"Sortero/{__version__} +https://github.com/sparkly-quasar/sortero"
 SEARCH = "https://api.discogs.com/database/search"
-MIN_INTERVAL = 2.5          # unauthenticated Discogs allows ~25 requests/minute
+ANON_INTERVAL = 2.5     # unauthenticated Discogs allows ~25 requests/minute
+TOKEN_INTERVAL = 1.0    # a free personal token raises it to ~60/minute
+MIN_INTERVAL = ANON_INTERVAL
 CACHE = "discogs-cache.json"
 
 _last_call = [0.0]
@@ -72,18 +74,38 @@ def key_for(rec):
     return f"{clean_artist(rec.artist)}|{clean_title(rec.title)}".lower()
 
 
+def worth_asking(rec):
+    """A query needs both halves; without them Discogs can only guess."""
+    return bool(clean_artist(rec.artist) and clean_title(rec.title))
+
+
 # ------------------------------------------------------------------ lookup
+def token():
+    return (settings.get("discogs_token") or "").strip()
+
+
+def interval():
+    return TOKEN_INTERVAL if token() else ANON_INTERVAL
+
+
+def eta_minutes(n):
+    return max(1, round(n * interval() / 60))
+
+
 def _throttle():
-    wait = MIN_INTERVAL - (time.time() - _last_call[0])
+    wait = interval() - (time.time() - _last_call[0])
     if wait > 0:
         time.sleep(wait)
     _last_call[0] = time.time()
 
 
 def _search(artist, title, timeout=25):
-    q = urllib.parse.urlencode({"artist": artist, "track": title,
-                                "type": "release", "per_page": "5"})
-    req = urllib.request.Request(f"{SEARCH}?{q}", headers={"User-Agent": UA})
+    params = {"artist": artist, "track": title, "type": "release", "per_page": "5"}
+    tok = token()
+    if tok:
+        params["token"] = tok
+    req = urllib.request.Request(f"{SEARCH}?{urllib.parse.urlencode(params)}",
+                                 headers={"User-Agent": UA})
     for attempt in range(3):
         _throttle()
         try:
@@ -125,27 +147,50 @@ def lookup(rec, cache=None):
     return None, raw
 
 
-def bulk_lookup(recs, detail="fine", progress=None, log=print):
-    """Look up many tracks. Returns {path: (suggestion, raw_styles)}."""
+def bulk_lookup(recs, detail="fine", progress=None, log=print,
+                on_result=None, should_stop=None, save_every=10):
+    """Look up many tracks.
+
+    Reports as it goes and saves the cache periodically, so a long run is both
+    visible and resumable - stopping halfway keeps everything already fetched.
+    Returns {path: (suggestion, raw_styles)}.
+    """
     cache = load_cache()
     out = {}
     total = len(recs) or 1
+    matched = 0
+    started = time.time()
+    done = 0
     try:
         for i, r in enumerate(recs):
+            if should_stop is not None and should_stop():
+                log(f"stopped after {i} of {total}")
+                break
             if progress:
                 progress(i, total)
             try:
                 g, raw = lookup(r, cache)
             except LookupError as e:
                 log(f"stopped: {e}")
                 break
+            done += 1
             if g or raw:
                 out[r.path] = (g, raw)
+                if on_result:
+                    on_result(r.path, (g, raw))
+                if g:
+                    matched += 1
+            if done % save_every == 0:
+                save_cache(cache)
+                rate = (time.time() - started) / max(done, 1)
+                left = int(rate * (total - i - 1) / 60)
+                log(f"Discogs {i+1}/{total} · {matched} with a genre · "
+                    f"~{left} min left")
     finally:
         save_cache(cache)
         if progress:
             progress(total, total)
-    log(f"looked up {len(out)} of {total} tracks")
+    log(f"looked up {len(out)} of {total} tracks ({matched} mapped to a genre)")
     return out
 
 

sortero/version.py

@@ -1 +1 @@
-__version__ = "0.7.0"
+__version__ = "0.7.1"