chore: enhance comments

2026-04-06 08:20:23 +02:00
parent 2d70231502
commit c5abbff14c
30 changed files with 65 additions and 80 deletions
@@ -1,4 +1,4 @@
-Copyright 2026 Uyanide me@uyani.de
+Copyright 2026 Uyanide pywang0608@foxmail.com
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
@@ -1,4 +1,10 @@
-from lrx_cli.cli import run
+"""
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-06 08:19:54
 Description: The entry point.
 """
 from .cli import run
 if __name__ == "__main__":
    run()
@@ -1,5 +1,6 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-06 08:21:01
 Description: Credential authenticators for third-party provider APIs
 """
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 03:18:14
-Description: Base class for credential authenticators
+Description: Base class for credential authenticators.
 """
 from abc import ABC, abstractmethod
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 03:36:44
-Description:
+Description: A dummy authenticator that does nothing and always reports as configured.
 """
 from .base import BaseAuthenticator
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 03:27:56
-Description: Musixmatch authenticator — token management, 401 retry, and cooldown
+Description: Musixmatch authenticator — token management, 401 retry, and cooldown.
 """
 import time
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 03:47:30
-Description: QQ Music API authenticator - currently only a proxy
+Description: QQ Music API authenticator - currently only a proxy.
 """
 from typing import Optional
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 03:18:14
-Description: Spotify authenticator — TOTP-based access token via SP_DC cookie
+Description: Spotify authenticator — TOTP-based access token via SP_DC cookie.
 """
 import hashlib
@@ -134,9 +134,7 @@ class SpotifyAuthenticator(BaseAuthenticator):
            return db_token
        if not credentials.SPOTIFY_SP_DC:
-            logger.error(
+            logger.error("Spotify: SPOTIFY_SP_DC env var not set — cannot authenticate")
                "Spotify: settings.SPOTIFY_SP_DC env var not set — cannot authenticate"
            )
            return None
        headers = {
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 10:18:03
-Description: SQLite-based lyric cache with per-source storage and TTL expiration
+Description: SQLite-based lyric cache with per-source storage and TTL expiration.
 """
 import json
@@ -79,7 +79,7 @@ class CacheEngine:
        self._init_db()
    def _init_db(self) -> None:
-        """Create or migrate the cache table."""
+        """Create or migrate the cache and credentials tables."""
        with sqlite3.connect(self.db_path) as conn:
            conn.execute("""
                CREATE TABLE IF NOT EXISTS cache (
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-26 02:04:39
-Description: CLI interface
+Description: CLI interface.
 """
 import sys
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 10:17:56
-Description: Global configuration constants and logger setup
+Description: Global configuration constants and logger setup.
 """
 import os
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 11:09:53
-Description: Core orchestrator — coordinates fetchers with cache-aware fallback
+Description: Core orchestrator — coordinates fetchers with cache-aware fallback.
 """
 import asyncio
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-31 06:11:27
-Description: Enricher that reads metadata from audio file tags (mutagen)
+Description: Enricher that reads metadata from audio file tags.
 """
 from typing import Optional
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-31 06:08:16
-Description: Base class for metadata enrichers
+Description: Base class for metadata enrichers.
 """
 from abc import ABC, abstractmethod
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-31 06:08:44
-Description: Enricher that parses metadata from the audio file path
+Description: Enricher that parses metadata from the audio file path.
 """
 import re
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 02:13:49
-Description: Musixmatch metadata enricher (matcher.track.get by Spotify track ID)
+Description: Musixmatch metadata enricher (matcher.track.get by Spotify track ID).
 """
 from typing import Optional
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 02:33:26
-Description: Fetcher pipeline — registry and types
+Description: Fetcher pipeline — registry and types.
 """
 from typing import Literal, Optional
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 02:33:26
-Description: Base fetcher class and common interfaces
+Description: Base fetcher class and common interfaces.
 """
 from abc import ABC, abstractmethod
@@ -1,10 +1,8 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-28 05:57:46
-Description: Cache-search fetcher — cross-album fuzzy lookup in the local cache
+Description: Cache-search fetcher — cross-album fuzzy lookup in the local cache.
 """
 """
             Searches existing cache entries by artist + title with fuzzy normalization,
             ignoring album and source. Useful when the same track appears on different
             albums or is played from different players.
@@ -1,10 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-26 02:08:41
-Description: Local fetcher — reads lyrics from .lrc sidecar files or embedded audio metadata
+Description: Local fetcher — reads lyrics from .lrc sidecar files or embedded audio metadata.
 """
 """
             Priority:
               1. Same-directory .lrc file (e.g. /path/to/track.lrc)
               2. Embedded lyrics in audio metadata (FLAC, MP3 USLT/SYLT tags)
@@ -1,10 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 05:23:38
-Description: LRCLIB fetcher — queries lrclib.net for synced/plain lyrics
+Description: LRCLIB fetcher — queries lrclib.net for synced/plain lyrics.
 """
 """
             Requires complete track metadata (artist, title, album, duration).
 """
@@ -1,12 +1,8 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 05:30:50
-Description: LRCLIB search fetcher — fuzzy search via lrclib.net /api/search
+Description: LRCLIB search fetcher — fuzzy search via lrclib.net /api/search.
 """
 """
             Used when metadata is incomplete (no album or duration) but title is available.
 Selects the best match by duration when track length is known.
 """
 import asyncio
@@ -1,10 +1,8 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-04 15:28:34
-Description: Musixmatch fetchers (desktop API, usertoken auth)
+Description: Musixmatch fetchers (desktop API, anonymous or usertoken auth).
 """
 """
             Uses the Musixmatch desktop API (apic-desktop.musixmatch.com).
             Token and all HTTP calls are managed by MusixmatchAuthenticator.
@@ -24,9 +22,7 @@ from ..lrc import LRCData
 from ..models import CacheStatus, LyricResult, TrackMeta
 from ..config import TTL_NETWORK_ERROR, TTL_NOT_FOUND
-_MUSIXMATCH_MACRO_URL = (
+_MUSIXMATCH_MACRO_URL = "https://apic-desktop.musixmatch.com/ws/1.1/macro.subtitles.get"
    "https://apic-desktop.musixmatch.com/ws/1.1/macro.subtitles.get"
 )
 _MUSIXMATCH_SEARCH_URL = "https://apic-desktop.musixmatch.com/ws/1.1/track.search"
 # Macro-specific params (format/app_id injected by authenticator)
@@ -1,15 +1,10 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 11:04:51
-Description: Netease Cloud Music fetcher
+Description: Netease Cloud Music fetcher.
 """
 """
             Uses the public cloudsearch API for searching and the song/lyric API for
             retrieving lyrics. No authentication required.
 Search results are filtered by duration when the track has a known length
 to avoid returning lyrics for the wrong version of a song.
 """
 import asyncio
@@ -1,14 +1,12 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-31 01:54:02
-Description: QQ Music fetcher via self-hosted API proxy
+Description: QQ Music fetcher via self-hosted API proxy.
 """
 """
             Requires a running qq-music-api instance.
             The base URL is read from the QQ_MUSIC_API_URL environment variable.
-Search → pick best match by duration → fetch LRC lyrics.
+             Search → pick best match → fetch LRC lyrics.
 """
 import asyncio
@@ -1,5 +1,7 @@
 """
-Shared candidate-selection logic for search-based fetchers.
+Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-04 11:32:23
 Description: Shared candidate-selection logic for search-based fetchers.
             Each fetcher maps its API-specific results to SearchCandidate, then calls
             select_best() which scores candidates by metadata similarity, duration
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 21:54:01
-Description: Shared LRC time-tag utilities (definitely overengineered)
+Description: Shared LRC time-tag utilities (definitely overengineered).
 """
 import re
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 04:09:36
-Description: Data models
+Description: Data models.
 """
 from __future__ import annotations
@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 04:44:15
-Description: MPRIS integration for fetching track metadata
+Description: MPRIS integration for fetching track metadata.
 """
 import asyncio
@@ -1,6 +1,7 @@
 """
-Shared text normalization utilities for fuzzy matching.
+Author: Uyanide pywang0608@foxmail.com
-
+Date: 2026-04-02 05:24:27
 Description: Shared text normalization utilities for fuzzy matching.
             Used by cache key generation, cache search, and candidate selection scoring.
 """
`@@ -1,4 +1,4 @@`
	`Copyright 2026 Uyanide me@uyani.de`	`Copyright 2026 Uyanide pywang0608@foxmail.com`

	`Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:`	`Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:`