codetta 0.8.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. codetta/CHANGELOG.md +153 -0
  2. codetta/__init__.py +8 -0
  3. codetta/__main__.py +5 -0
  4. codetta/cli/__init__.py +0 -0
  5. codetta/cli/__main__.py +59 -0
  6. codetta/cli/run.py +129 -0
  7. codetta/core/__init__.py +0 -0
  8. codetta/core/acoustid.py +225 -0
  9. codetta/core/activity.py +161 -0
  10. codetta/core/artwork.py +238 -0
  11. codetta/core/auth.py +362 -0
  12. codetta/core/avatar.py +92 -0
  13. codetta/core/changelog.py +51 -0
  14. codetta/core/connections.py +159 -0
  15. codetta/core/describe.py +69 -0
  16. codetta/core/engine.py +470 -0
  17. codetta/core/health.py +520 -0
  18. codetta/core/inbox.py +195 -0
  19. codetta/core/index.py +672 -0
  20. codetta/core/library.py +177 -0
  21. codetta/core/musicbrainz.py +662 -0
  22. codetta/core/notifications.py +77 -0
  23. codetta/core/onboarding.py +39 -0
  24. codetta/core/organize.py +490 -0
  25. codetta/core/plugins.py +183 -0
  26. codetta/core/presets.py +452 -0
  27. codetta/core/providers.py +203 -0
  28. codetta/core/rawtags.py +135 -0
  29. codetta/core/slskd.py +650 -0
  30. codetta/core/tagmap.py +538 -0
  31. codetta/core/undo.py +186 -0
  32. codetta/core/updates.py +132 -0
  33. codetta/plugins/__init__.py +63 -0
  34. codetta/plugins/builtin/__init__.py +3 -0
  35. codetta/plugins/builtin/tidy.py +70 -0
  36. codetta/web/__init__.py +0 -0
  37. codetta/web/app.py +2909 -0
  38. codetta/web/security.py +170 -0
  39. codetta/web/static/app.css +2684 -0
  40. codetta/web/static/app.js +5694 -0
  41. codetta/web/static/apple-touch-icon.png +0 -0
  42. codetta/web/static/fonts/LICENSE-Inter.txt +93 -0
  43. codetta/web/static/fonts/LICENSE-SchibstedGrotesk.txt +93 -0
  44. codetta/web/static/fonts/inter-cyrillic.woff2 +0 -0
  45. codetta/web/static/fonts/schibsted-grotesk.woff2 +0 -0
  46. codetta/web/static/icon.svg +1 -0
  47. codetta/web/static/icons/codetta-dark.png +0 -0
  48. codetta/web/static/icons/codetta-dark.svg +1 -0
  49. codetta/web/static/icons/codetta-dark.webp +0 -0
  50. codetta/web/static/icons/codetta-light.png +0 -0
  51. codetta/web/static/icons/codetta-light.svg +1 -0
  52. codetta/web/static/icons/codetta-light.webp +0 -0
  53. codetta/web/static/icons/codetta.png +0 -0
  54. codetta/web/static/icons/codetta.svg +1 -0
  55. codetta/web/static/icons/codetta.webp +0 -0
  56. codetta/web/static/index.html +473 -0
  57. codetta/web/static/theme.js +12 -0
  58. codetta-0.8.1.dist-info/METADATA +282 -0
  59. codetta-0.8.1.dist-info/RECORD +63 -0
  60. codetta-0.8.1.dist-info/WHEEL +5 -0
  61. codetta-0.8.1.dist-info/entry_points.txt +2 -0
  62. codetta-0.8.1.dist-info/licenses/LICENSE +661 -0
  63. codetta-0.8.1.dist-info/top_level.txt +1 -0
codetta/core/slskd.py ADDED
@@ -0,0 +1,650 @@
1
+ """Soulseek through the user's own slskd (https://github.com/slskd/slskd).
2
+
3
+ Codetta never speaks the Soulseek protocol itself: it asks the user's slskd
4
+ over its REST API (``/api/v0``, ``X-API-Key``) to search and download, and
5
+ slskd saves the files into its downloads folder, which is Codetta's inbox.
6
+ From there the inbox does what it always does (match, review, file).
7
+
8
+ A *job* is one request ("T-Pain Bartender"):
9
+
10
+ searching → downloading → fetched → arrived (in the inbox) → imported
11
+ ↑ failed / blocklisted: next candidate |
12
+ └────────────────────────────────────────┘
13
+ (no candidates left: nothing / failed; cancelled by the user)
14
+
15
+ Candidates are the folders other users share, ranked by how well their names
16
+ match the request, quality (lossless first by default), free upload slots,
17
+ queue length and speed. Folders the user blocklisted are never offered again.
18
+
19
+ State (settings incl. the API key, jobs, blocklist) lives in ``slskd.json``
20
+ in the config folder, readable by its owner only.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import json
26
+ import os
27
+ import re
28
+ import tempfile
29
+ import threading
30
+ import time
31
+ import urllib.error
32
+ import urllib.parse
33
+ import urllib.request
34
+ import uuid
35
+ from collections.abc import Callable
36
+ from datetime import datetime
37
+ from dataclasses import asdict, dataclass, field
38
+ from pathlib import Path
39
+
40
+ # Job statuses.
41
+ SEARCHING = "searching"
42
+ DOWNLOADING = "downloading"
43
+ FETCHED = "fetched" # slskd has every file: waiting for them to show up in the inbox
44
+ ARRIVED = "arrived" # in the inbox, being matched / waiting for a review
45
+ IMPORTED = "imported"
46
+ NOTHING = "nothing" # the search found nothing usable
47
+ FAILED = "failed"
48
+ CANCELLED = "cancelled"
49
+ ACTIVE = (SEARCHING, DOWNLOADING, FETCHED)
50
+
51
+ AUDIO = {"flac", "mp3", "m4a", "aac", "ogg", "opus", "wav", "aif", "aiff", "ape", "wv", "dsf", "alac", "wma"}
52
+ LOSSLESS = {"flac", "wav", "aif", "aiff", "ape", "wv", "dsf", "alac"}
53
+ MAX_CANDIDATES = 25
54
+ MAX_JOBS = 50
55
+ QUIET_SAVE_SECONDS = 30 # progress-only changes reach the disk at most this often
56
+ DONE = (IMPORTED, NOTHING, CANCELLED) # finished for good: their file lists aren't needed any more
57
+ STALL_SECONDS = 15 * 60 # a download that hasn't moved for this long gives way to the next candidate
58
+ ARRIVE_SECONDS = 10 * 60 # finished in slskd but not in the inbox after this long: something's mounted wrong
59
+ FAILED_STATES = ("Errored", "Rejected", "TimedOut", "Cancelled", "Aborted")
60
+
61
+
62
+ class SlskdError(Exception):
63
+ """slskd couldn't be reached or said no; the message is for people."""
64
+
65
+
66
+ # --- Settings -------------------------------------------------------------------------
67
+
68
+
69
+ @dataclass
70
+ class SlskdSettings:
71
+ url: str = "" # e.g. http://slskd:5030
72
+ api_key: str = ""
73
+ review: bool = True # False: confident downloads are filed without asking
74
+ lossless_only: bool = False # default: lossless first, lossy (min_bitrate and up) if no one has it
75
+ min_bitrate: int = 320 # kbps, for lossy files
76
+ search_seconds: int = 20
77
+
78
+ @property
79
+ def configured(self) -> bool:
80
+ return bool(self.url and self.api_key)
81
+
82
+
83
+ def clean_url(url: str) -> str:
84
+ url = url.strip().rstrip("/")
85
+ if url and not re.match(r"^[a-z][a-z0-9+.-]*://", url, re.I):
86
+ url = "http://" + url # "slskd:5030" -> "http://slskd:5030"; any other scheme is left for the caller to refuse
87
+ if url.endswith("/api/v0"):
88
+ url = url[: -len("/api/v0")]
89
+ return url
90
+
91
+
92
+ # --- Talking to slskd -------------------------------------------------------------------
93
+
94
+ Request = Callable[[str, str, dict, bytes | None], tuple[int, bytes]] # (method, url, headers, body) -> (status, body)
95
+
96
+
97
+ def http_request(method: str, url: str, headers: dict, body: bytes | None, timeout: float = 15) -> tuple[int, bytes]:
98
+ req = urllib.request.Request(url, data=body, method=method, headers=headers)
99
+ try:
100
+ with urllib.request.urlopen(req, timeout=timeout) as resp: # noqa: S310 (the admin's own server)
101
+ return resp.status, resp.read(20_000_000)
102
+ except urllib.error.HTTPError as exc:
103
+ return exc.code, exc.read(100_000) if exc.fp else b""
104
+ except (urllib.error.URLError, OSError, ValueError) as exc:
105
+ reason = getattr(exc, "reason", exc)
106
+ raise SlskdError(f"Couldn't reach slskd: {reason}") from exc
107
+
108
+
109
+ class SlskdClient:
110
+ def __init__(self, url: str, api_key: str, request: Request = http_request) -> None:
111
+ self.base = clean_url(url) + "/api/v0"
112
+ self.api_key = api_key
113
+ self.request = request
114
+
115
+ def call(self, method: str, path: str, body: object = None) -> object:
116
+ headers = {"X-API-Key": self.api_key, "Accept": "application/json"}
117
+ data = None
118
+ if body is not None:
119
+ data = json.dumps(body).encode()
120
+ headers["Content-Type"] = "application/json"
121
+ status, raw = self.request(method, self.base + path, headers, data)
122
+ if status in (401, 403):
123
+ raise SlskdError("slskd turned down the API key. Check it matches one in slskd's settings (web → authentication → api_keys).")
124
+ if status == 404:
125
+ raise SlskdError("slskd doesn't know that (404). Is the address right, and is slskd up to date?")
126
+ if status >= 400:
127
+ text = raw.decode("utf-8", "replace").strip()[:200]
128
+ raise SlskdError(f"slskd said {status}" + (f": {text}" if text else ""))
129
+ if not raw.strip():
130
+ return None
131
+ try:
132
+ return json.loads(raw)
133
+ except ValueError as exc:
134
+ raise SlskdError("slskd sent something that isn't JSON. Is the address pointing at slskd?") from exc
135
+
136
+ @staticmethod
137
+ def _user(username: str) -> str:
138
+ return urllib.parse.quote(username, safe="")
139
+
140
+ def version(self) -> str:
141
+ v = self.call("GET", "/application/version")
142
+ return v if isinstance(v, str) else str(v or "")
143
+
144
+ def application(self) -> dict:
145
+ return self.call("GET", "/application") or {}
146
+
147
+ def shares(self) -> dict:
148
+ return self.call("GET", "/shares") or {}
149
+
150
+ def options(self) -> dict:
151
+ return self.call("GET", "/options") or {}
152
+
153
+ def start_search(self, search_id: str, text: str, seconds: int) -> None:
154
+ self.call("POST", "/searches", {
155
+ "id": search_id, "searchText": text, "searchTimeout": max(5, seconds) * 1000,
156
+ "filterResponses": True, "responseLimit": 200, "fileLimit": 20000,
157
+ })
158
+
159
+ def search(self, search_id: str) -> dict:
160
+ return self.call("GET", f"/searches/{search_id}") or {}
161
+
162
+ def responses(self, search_id: str) -> list:
163
+ r = self.call("GET", f"/searches/{search_id}/responses")
164
+ return r if isinstance(r, list) else []
165
+
166
+ def delete_search(self, search_id: str) -> None:
167
+ try:
168
+ self.call("DELETE", f"/searches/{search_id}")
169
+ except SlskdError:
170
+ pass
171
+
172
+ def enqueue(self, username: str, files: list[dict]) -> None:
173
+ self.call("POST", f"/transfers/downloads/{self._user(username)}",
174
+ [{"filename": f["filename"], "size": f["size"]} for f in files])
175
+
176
+ def downloads(self, username: str) -> list[dict]:
177
+ """Every download from this user, flattened."""
178
+ try:
179
+ r = self.call("GET", f"/transfers/downloads/{self._user(username)}")
180
+ except SlskdError as exc:
181
+ if "404" in str(exc):
182
+ return [] # nothing from this user (any more)
183
+ raise
184
+ out = []
185
+ for d in (r or {}).get("directories") or []:
186
+ out.extend(t for t in d.get("files") or [] if isinstance(t, dict))
187
+ return out
188
+
189
+ def all_downloads(self) -> list[dict]:
190
+ """Every download slskd knows, one entry per (user, remote folder)."""
191
+ out = []
192
+ for u in self.call("GET", "/transfers/downloads") or []:
193
+ for d in (u or {}).get("directories") or []:
194
+ out.append({"username": u.get("username") or "", "directory": d.get("directory") or "",
195
+ "files": [t for t in d.get("files") or [] if isinstance(t, dict)]})
196
+ return out
197
+
198
+ def cancel(self, username: str, transfer_id: str) -> None:
199
+ try:
200
+ self.call("DELETE", f"/transfers/downloads/{self._user(username)}/{transfer_id}?remove=true")
201
+ except SlskdError:
202
+ pass
203
+
204
+
205
+ def _when(text: object) -> float | None:
206
+ """slskd's timestamps ("2026-11-18T18:50:01.1234567", UTC, with or without Z) -> epoch seconds."""
207
+ if not isinstance(text, str) or not text:
208
+ return None
209
+ m = re.match(r"(\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d)(\.\d+)?(Z|[+-]\d\d:?\d\d)?$", text.strip())
210
+ if not m:
211
+ return None
212
+ frac = (m.group(2) or ".0")[:7]
213
+ zone = m.group(3) or "+00:00"
214
+ try:
215
+ return datetime.fromisoformat(m.group(1) + frac + ("+00:00" if zone == "Z" else zone)).timestamp()
216
+ except ValueError:
217
+ return None
218
+
219
+
220
+ def transfer_progress(transfers: list[dict], now: float | None = None) -> dict | None:
221
+ """How far a folder's download has got, and roughly how long the rest takes:
222
+ the speed so far (bytes since the first file started) applied to what's left."""
223
+ if not transfers:
224
+ return None
225
+ now = time.time() if now is None else now
226
+ total = sum(int(t.get("size") or 0) for t in transfers)
227
+ done = sum(int(t.get("bytesTransferred") or 0) for t in transfers)
228
+ if total <= 0:
229
+ return None
230
+ starts = [s for t in transfers if (s := _when(t.get("startedAt"))) is not None]
231
+ finished = sum("Succeeded" in str(t.get("state") or "") for t in transfers)
232
+ eta = speed = None
233
+ if starts and 0 < done < total:
234
+ elapsed = max(1.0, now - min(starts))
235
+ speed = done / elapsed
236
+ eta = (total - done) / speed if speed > 0 else None
237
+ return {"progress": round(min(done / total, 1.0), 3), "eta": round(eta) if eta is not None else None,
238
+ "speed": round(speed) if speed else None, "files": len(transfers), "finished": finished}
239
+
240
+
241
+ def folder_progress(downloads: list[dict], names: set[str], now: float | None = None) -> dict | None:
242
+ """The download (one slskd folder) that these files came from, by file name."""
243
+ best = None
244
+ for d in downloads:
245
+ hit = len(names & {split_remote(t.get("filename") or "")[1] for t in d["files"]})
246
+ if hit and (best is None or hit > best[0]):
247
+ best = (hit, d)
248
+ return transfer_progress(best[1]["files"], now) if best else None
249
+
250
+
251
+ def check(client: SlskdClient) -> dict:
252
+ """What Account → Connections shows: reachable? shares? where downloads go?"""
253
+ out = {"ok": False, "version": "", "shared_folders": 0, "shared_files": 0, "downloads_dir": "",
254
+ "logged_in": None, "error": ""}
255
+ try:
256
+ out["version"] = client.version()
257
+ shares = client.shares()
258
+ for host_shares in shares.values() if isinstance(shares, dict) else []:
259
+ for s in host_shares or []:
260
+ if isinstance(s, dict) and not s.get("isExcluded"):
261
+ out["shared_folders"] += 1
262
+ out["shared_files"] += int(s.get("files") or 0)
263
+ try:
264
+ out["downloads_dir"] = ((client.options().get("directories") or {}).get("downloads")) or ""
265
+ except SlskdError:
266
+ pass # older slskd or a key without admin rights: not essential
267
+ try:
268
+ server = (client.application().get("server") or {})
269
+ out["logged_in"] = bool(server.get("isLoggedIn")) if "isLoggedIn" in server else None
270
+ except SlskdError:
271
+ pass
272
+ out["ok"] = True
273
+ except SlskdError as exc:
274
+ out["error"] = str(exc)
275
+ return out
276
+
277
+
278
+ # --- Ranking ------------------------------------------------------------------------------
279
+
280
+
281
+ def _ext(filename: str) -> str:
282
+ return filename.rsplit(".", 1)[-1].lower() if "." in filename else ""
283
+
284
+
285
+ def split_remote(filename: str) -> tuple[str, str]:
286
+ """Soulseek paths use backslashes (Windows sharers) or slashes."""
287
+ sep = "\\" if "\\" in filename else "/"
288
+ folder, _, name = filename.rpartition(sep)
289
+ return folder, name
290
+
291
+
292
+ def _words(text: str) -> list[str]:
293
+ return [w for w in re.split(r"[^\w*]+", text.lower()) if w.strip("*")]
294
+
295
+
296
+ def name_match(query: str, haystack: str) -> float:
297
+ """Share of the request's words found in the folder and file names.
298
+ ``*`` is a wildcard (``*-Pain`` → any word ending in "pain")."""
299
+ words = _words(query)
300
+ if not words:
301
+ return 0.0
302
+ hay = " ".join(_words(haystack))
303
+ hit = 0
304
+ for w in words:
305
+ pattern = r"\b" + ".*?".join(re.escape(p) for p in w.split("*")) + r"\b" if "*" in w else r"\b" + re.escape(w) + r"\b"
306
+ if "*" in w and w.startswith("*"):
307
+ pattern = pattern[2:] # "*ain" may sit in the middle of a word
308
+ if re.search(pattern, hay):
309
+ hit += 1
310
+ return hit / len(words)
311
+
312
+
313
+ def quality(files: list[dict]) -> tuple[int, str]:
314
+ """(rank, label): 3 lossless, 2 lossy at a good bitrate, 1 lossy unknown, 0 lossy low."""
315
+ exts = {_ext(f["filename"]) for f in files}
316
+ lossless = all(_ext(f["filename"]) in LOSSLESS or (_ext(f["filename"]) == "m4a" and f.get("bitDepth")) for f in files)
317
+ if lossless:
318
+ depth = max((f.get("bitDepth") or 0 for f in files), default=0)
319
+ rate = max((f.get("sampleRate") or 0 for f in files), default=0)
320
+ fmt = "/".join(sorted(e.upper() for e in exts))
321
+ return 3, f"{fmt} {depth}-bit/{rate / 1000:g} kHz" if depth and rate else fmt
322
+ rates = [f.get("bitRate") for f in files if f.get("bitRate")]
323
+ fmt = "/".join(sorted(e.upper() for e in exts))
324
+ if not rates:
325
+ return 1, fmt
326
+ low = min(rates)
327
+ vbr = any(f.get("isVariableBitRate") for f in files)
328
+ return 2, f"{fmt} {'VBR ~' if vbr else ''}{low} kbps"
329
+
330
+
331
+ def rank(responses: list[dict], query: str, settings: SlskdSettings, blocked: set[str]) -> list[dict]:
332
+ """Candidate folders, best first."""
333
+ cands = []
334
+ for r in responses:
335
+ user = r.get("username") or ""
336
+ if not user:
337
+ continue
338
+ folders: dict[str, list[dict]] = {}
339
+ for f in r.get("files") or []:
340
+ if not isinstance(f, dict) or _ext(f.get("filename") or "") not in AUDIO or f.get("isLocked"):
341
+ continue
342
+ folder, _ = split_remote(f["filename"])
343
+ folders.setdefault(folder, []).append(f)
344
+ for folder, files in folders.items():
345
+ if block_key(user, folder) in blocked or block_key(user, "") in blocked:
346
+ continue
347
+ q, label = quality(files)
348
+ if q < 3:
349
+ if settings.lossless_only:
350
+ continue
351
+ rates = [f.get("bitRate") for f in files if f.get("bitRate")]
352
+ if rates and min(rates) < settings.min_bitrate and not any(f.get("isVariableBitRate") for f in files):
353
+ q = 0
354
+ tail = "\\".join(re.split(r"[\\/]", folder)[-2:])
355
+ names = tail + " " + " ".join(split_remote(f["filename"])[1] for f in files)
356
+ match = name_match(query, names)
357
+ if match < 0.5:
358
+ continue
359
+ speed = int(r.get("uploadSpeed") or 0)
360
+ queue = int(r.get("queueLength") or 0)
361
+ free = bool(r.get("hasFreeUploadSlot"))
362
+ score = (match * 100 + q * 25 + (15 if free else 0) + min(speed / 1_000_000, 1) * 10
363
+ - min(queue, 50) / 5 + min(len(files), 12))
364
+ cands.append({
365
+ "username": user, "folder": folder, "name": re.split(r"[\\/]", folder)[-1] or folder,
366
+ "files": [{k: f.get(k) for k in ("filename", "size", "bitRate", "bitDepth", "sampleRate", "length",
367
+ "isVariableBitRate")} for f in sorted(files, key=lambda f: f["filename"])],
368
+ "tracks": len(files), "size": sum(int(f.get("size") or 0) for f in files),
369
+ "quality": label, "lossless": q == 3, "free_slot": free, "speed": speed, "queue": queue,
370
+ "match": round(match, 2), "score": round(score, 1),
371
+ })
372
+ cands.sort(key=lambda c: -c["score"])
373
+ return cands[:MAX_CANDIDATES]
374
+
375
+
376
+ def block_key(username: str, folder: str) -> str:
377
+ return f"{username}\n{folder}"
378
+
379
+
380
+ # --- Jobs -----------------------------------------------------------------------------------
381
+
382
+
383
+ @dataclass
384
+ class Job:
385
+ id: str
386
+ query: str
387
+ status: str = SEARCHING
388
+ created: float = 0.0
389
+ updated: float = 0.0
390
+ upgrade: str = "" # a library folder this download is meant to replace ("" = new music)
391
+ candidates: list[dict] = field(default_factory=list)
392
+ pick: int = -1 # index into candidates being downloaded
393
+ tried: list[int] = field(default_factory=list)
394
+ progress: float = 0.0 # 0..1 of the current pick
395
+ eta: float | None = None # seconds left, roughly (speed since the first file started)
396
+ moved: float = 0.0 # when the download last made progress
397
+ note: str = ""
398
+ inbox_key: str = "" # its album in the inbox, once it's there
399
+
400
+ @property
401
+ def current(self) -> dict | None:
402
+ return self.candidates[self.pick] if 0 <= self.pick < len(self.candidates) else None
403
+
404
+
405
+ def _slim(job: Job) -> None:
406
+ """A finished request keeps its summary, not every candidate's file list (most of its size)."""
407
+ if job.status in DONE and any("files" in c for c in job.candidates):
408
+ job.candidates = [{k: v for k, v in c.items() if k != "files"} for c in job.candidates]
409
+
410
+
411
+ class SoulseekStore:
412
+ """Settings, jobs and the blocklist, saved to slskd.json (owner-only: it holds the API key)."""
413
+
414
+ def __init__(self, file: Path, env_url: str | None = None, env_key: str | None = None) -> None:
415
+ self.file = file
416
+ self.lock = threading.RLock()
417
+ self.settings = SlskdSettings()
418
+ self.jobs: dict[str, Job] = {}
419
+ self.blocked: set[str] = set()
420
+ self.env_url, self.env_key = (clean_url(env_url) if env_url else None), (env_key or None)
421
+ self._load()
422
+
423
+ def _load(self) -> None:
424
+ try:
425
+ data = json.loads(self.file.read_text("utf-8"))
426
+ except (OSError, ValueError):
427
+ data = {}
428
+ if not isinstance(data, dict):
429
+ data = {}
430
+ s = data.get("settings") if isinstance(data.get("settings"), dict) else {}
431
+ known = SlskdSettings.__dataclass_fields__
432
+ try:
433
+ self.settings = SlskdSettings(**{k: v for k, v in s.items() if k in known})
434
+ except TypeError:
435
+ self.settings = SlskdSettings()
436
+ for j in (data.get("jobs") or {}).values() if isinstance(data.get("jobs"), dict) else []:
437
+ try:
438
+ job = Job(**{k: v for k, v in j.items() if k in Job.__dataclass_fields__})
439
+ except TypeError:
440
+ continue
441
+ self.jobs[job.id] = job
442
+ self.blocked = {b for b in data.get("blocked") or [] if isinstance(b, str)}
443
+ self._saved = 0.0
444
+ for job in self.jobs.values():
445
+ _slim(job)
446
+
447
+ @property
448
+ def url(self) -> str:
449
+ return self.env_url or self.settings.url
450
+
451
+ @property
452
+ def api_key(self) -> str:
453
+ return self.env_key or self.settings.api_key
454
+
455
+ @property
456
+ def configured(self) -> bool:
457
+ return bool(self.url and self.api_key)
458
+
459
+ def save(self) -> None:
460
+ with self.lock:
461
+ data = {"settings": asdict(self.settings), "jobs": {k: asdict(j) for k, j in self.jobs.items()},
462
+ "blocked": sorted(self.blocked)}
463
+ self.file.parent.mkdir(parents=True, exist_ok=True)
464
+ fd, tmp = tempfile.mkstemp(prefix=".slskd-", dir=self.file.parent)
465
+ try:
466
+ os.fchmod(fd, 0o600)
467
+ with os.fdopen(fd, "w", encoding="utf-8") as f:
468
+ json.dump(data, f, ensure_ascii=False)
469
+ os.replace(tmp, self.file)
470
+ self._saved = time.time()
471
+ except BaseException:
472
+ Path(tmp).unlink(missing_ok=True)
473
+ raise
474
+
475
+ def add_job(self, query: str, upgrade: str = "") -> Job:
476
+ with self.lock:
477
+ now = time.time()
478
+ job = Job(id=str(uuid.uuid4()), # slskd wants a standard GUID (with dashes)
479
+ query=query, created=now, updated=now, moved=now, upgrade=upgrade)
480
+ self.jobs[job.id] = job
481
+ # Forget the oldest finished jobs.
482
+ done = sorted((j for j in self.jobs.values() if j.status not in ACTIVE + (ARRIVED,)), key=lambda j: j.updated)
483
+ for j in done[: max(0, len(self.jobs) - MAX_JOBS)]:
484
+ del self.jobs[j.id]
485
+ self.save()
486
+ return job
487
+
488
+ def update(self, job: Job, quiet: bool = False, **changes) -> Job:
489
+ """Change a job and save. ``quiet``: only progress moved, so the file is
490
+ written at most every QUIET_SAVE_SECONDS (a download ticks every few seconds)."""
491
+ with self.lock:
492
+ for k, v in changes.items():
493
+ setattr(job, k, v)
494
+ job.updated = time.time()
495
+ _slim(job)
496
+ if not quiet or job.updated - self._saved >= QUIET_SAVE_SECONDS:
497
+ self.save()
498
+ return job
499
+
500
+ def active(self) -> list[Job]:
501
+ with self.lock:
502
+ return [j for j in self.jobs.values() if j.status in ACTIVE]
503
+
504
+
505
+ class Soulseek:
506
+ """Moves jobs along. ``tick()`` is called every few seconds by a background
507
+ thread while any job is active. ``locate(job)`` (from the app) finds the
508
+ finished download in the inbox and returns its album key, or None."""
509
+
510
+ def __init__(self, store: SoulseekStore, request: Request = http_request,
511
+ notify: Callable[[str, str, dict | None], None] | None = None,
512
+ clock: Callable[[], float] = time.time) -> None:
513
+ self.store = store
514
+ self.request = request
515
+ self.notify = notify or (lambda title, body, action: None)
516
+ self.clock = clock
517
+
518
+ def client(self) -> SlskdClient:
519
+ if not self.store.configured:
520
+ raise SlskdError("Connect your slskd first (Account → Connections).")
521
+ return SlskdClient(self.store.url, self.store.api_key, self.request)
522
+
523
+ def search(self, query: str, upgrade: str = "") -> Job:
524
+ query = " ".join(query.split())
525
+ if sum(c.isalnum() for c in query) < 2:
526
+ raise SlskdError("Type at least two letters or numbers to search Soulseek.")
527
+ client = self.client()
528
+ job = self.store.add_job(query, upgrade)
529
+ try:
530
+ client.start_search(job.id, query, self.store.settings.search_seconds)
531
+ except SlskdError as exc:
532
+ self.store.update(job, status=FAILED, note=str(exc))
533
+ raise
534
+ return job
535
+
536
+ def tick(self, locate: Callable[[Job], str | None]) -> None:
537
+ for job in self.store.active():
538
+ try:
539
+ if job.status == SEARCHING:
540
+ self._tick_search(job)
541
+ elif job.status == DOWNLOADING:
542
+ self._tick_download(job)
543
+ elif job.status == FETCHED:
544
+ self._tick_fetched(job, locate)
545
+ except SlskdError as exc:
546
+ self.store.update(job, note=f"{exc} (trying again)")
547
+
548
+ def _tick_search(self, job: Job) -> None:
549
+ client = self.client()
550
+ state = client.search(job.id)
551
+ elapsed = self.clock() - job.created
552
+ if not state.get("isComplete") and "Completed" not in str(state.get("state") or "") \
553
+ and elapsed < self.store.settings.search_seconds + 30:
554
+ n = int(state.get("responseCount") or 0)
555
+ self.store.update(job, quiet=True, note=f"Asking Soulseek… {n} {'user has' if n == 1 else 'users have'} answered")
556
+ return
557
+ cands = rank(client.responses(job.id), job.query, self.store.settings, self.store.blocked)
558
+ client.delete_search(job.id)
559
+ if not cands:
560
+ note = ("No one shares a lossless copy that matches." if self.store.settings.lossless_only else
561
+ "No one shares anything that matches. Try fewer words, or a * wildcard for a filtered name.")
562
+ self.store.update(job, status=NOTHING, note=note)
563
+ self.notify(f"Soulseek: nothing for “{job.query}”", note, {"open": "soulseek"})
564
+ return
565
+ self.store.update(job, candidates=cands)
566
+ self.start(job, 0)
567
+
568
+ def start(self, job: Job, index: int) -> None:
569
+ """Download candidate ``index``."""
570
+ cand = job.candidates[index]
571
+ self.client().enqueue(cand["username"], cand["files"])
572
+ tried = job.tried + ([index] if index not in job.tried else [])
573
+ self.store.update(job, status=DOWNLOADING, pick=index, tried=tried, progress=0.0, eta=None, moved=self.clock(),
574
+ inbox_key="", note=f"Downloading {cand['name']} from {cand['username']}")
575
+
576
+ def next_candidate(self, job: Job, reason: str) -> bool:
577
+ """Move on to the best candidate not tried yet. False if there's none."""
578
+ for i in range(len(job.candidates)):
579
+ c = job.candidates[i]
580
+ if i not in job.tried and block_key(c["username"], c["folder"]) not in self.store.blocked:
581
+ try:
582
+ self.start(job, i)
583
+ return True
584
+ except SlskdError:
585
+ job.tried.append(i)
586
+ self.store.update(job, status=FAILED, note=f"{reason} No other candidates left: search again, maybe with other words.")
587
+ self.notify(f"Soulseek: couldn't get “{job.query}”", job.note, {"open": "soulseek"})
588
+ return False
589
+
590
+ def _transfers(self, job: Job) -> list[dict]:
591
+ cand = job.current
592
+ wanted = {f["filename"] for f in cand["files"]}
593
+ return [t for t in self.client().downloads(cand["username"]) if t.get("filename") in wanted]
594
+
595
+ def cancel_transfers(self, job: Job) -> None:
596
+ if job.current is None:
597
+ return
598
+ client = self.client()
599
+ for t in self._transfers(job):
600
+ if "Completed" not in str(t.get("state")):
601
+ client.cancel(job.current["username"], str(t.get("id")))
602
+
603
+ def _tick_download(self, job: Job) -> None:
604
+ cand = job.current
605
+ transfers = self._transfers(job)
606
+ total = sum(int(f.get("size") or 0) for f in cand["files"]) or 1
607
+ done = sum(int(t.get("bytesTransferred") or 0) for t in transfers)
608
+ states = [str(t.get("state") or "") for t in transfers]
609
+ now = self.clock()
610
+ if any(any(s in st for s in FAILED_STATES) for st in states):
611
+ self.cancel_transfers(job)
612
+ self.next_candidate(job, f"{cand['username']} couldn't send {cand['name']}.")
613
+ return
614
+ if len(transfers) == len(cand["files"]) and all("Succeeded" in st for st in states):
615
+ self.store.update(job, status=FETCHED, progress=1.0, moved=now, note="Downloaded: moving into your inbox")
616
+ return
617
+ progress = min(done / total, 0.999)
618
+ if progress > job.progress:
619
+ est = transfer_progress(transfers + [{"size": f["size"]} for f in cand["files"]
620
+ if f["filename"] not in {t.get("filename") for t in transfers}], now)
621
+ self.store.update(job, quiet=True, progress=progress, moved=now, eta=est["eta"] if est else None,
622
+ note=f"Downloading {cand['name']} from {cand['username']}")
623
+ elif now - job.moved > STALL_SECONDS:
624
+ self.cancel_transfers(job)
625
+ queued = any("Queued" in st for st in states)
626
+ self.next_candidate(job, f"{cand['username']} {'kept you waiting in their queue' if queued else 'stopped sending'}.")
627
+ elif any("Queued" in st for st in states) and job.progress == 0:
628
+ place = min((t.get("placeInQueue") for t in transfers if t.get("placeInQueue")), default=None)
629
+ self.store.update(job, quiet=True, note=f"Waiting in {cand['username']}'s queue" + (f" (place {place})" if place else ""))
630
+
631
+ def _tick_fetched(self, job: Job, locate: Callable[[Job], str | None]) -> None:
632
+ key = locate(job)
633
+ if key:
634
+ self.store.update(job, status=ARRIVED, inbox_key=key, note="In your inbox: matching it")
635
+ return
636
+ if self.clock() - job.moved > ARRIVE_SECONDS:
637
+ self.store.update(job, status=FAILED, note=(
638
+ "slskd finished the download, but it never showed up in Codetta's inbox. "
639
+ "Is slskd's downloads folder mounted at /inbox (and set as the inbox)?"))
640
+ self.notify(f"Soulseek: “{job.query}” didn't reach the inbox", job.note, {"open": "soulseek"})
641
+
642
+ def blocklist(self, username: str, folder: str) -> None:
643
+ with self.store.lock:
644
+ self.store.blocked.add(block_key(username, folder))
645
+ self.store.save()
646
+
647
+
648
+ def basenames(job: Job) -> list[str]:
649
+ cand = job.current
650
+ return [split_remote(f["filename"])[1] for f in cand.get("files", [])] if cand else []