Tidal Metadata Plugin (#6520)

## Description

This PR introduces tidal as metadatasource. It add both an minimal api
layer and the typical metadata source plugin capabilities.

### Details

The implementation provides a small API layer consisting of `TidalAPI`
for high-level album and track fetching, and `TidalSession` which
extends `requests.Session` with token authentication, automatic rate
limiting (~4 req/s via `RateLimitAdapter`), and pagination resolution
following the JSON:API spec.

Authentication is handled through an OAuth2 PKCE flow accessible via
`beet tidal --auth`, with automatic token refresh when the access token
expires.

Metadata parsing handles Tidal's JSON:API response format, extracting
album and track information including ISO 8601 duration conversion,
artist relationships, and copyright/label data.

## Input wanted

The API layer currently lacks comprehensive test coverage. Setting up
proper tests would require either mocking all outgoing requests or
creating a dedicated test token (which necessitates an account and might
require read/write to github secrets).

Are we comfortable with the current approach of unit testing the plugin
itself while mocking all requests?

## TODOs

- [x] Documentation
- [x] `candidate` and `item_candidates` lookup
- [x] It should be possible to optimize batched lookups
- [x] Add tests for candidates and item_candidates
- [x] Implement batching for more than 20 filters


## Refs

thanks to @jcjordyn130 for his initial implementations in #5637 and
#4641

Author: semohr

.github/CODEOWNERS

@@ -3,6 +3,7 @@
 
 # Specific ownerships:
 /beets/metadata_plugins.py @semohr
+/beetsplug/tidal/* @semohr
 
 /beetsplug/titlecase.py @henry-oberholtzer
 

beets/util/id_extractors.py

@@ -43,7 +43,7 @@
     # - https://github.com/snejus/beetcamp. Bandcamp album URLs usually look
     # like: https://nameofartist.bandcamp.com/album/nameofalbum
     "bandcamp": re.compile(r"(.+)"),
-    "tidal": re.compile(r"([^/]+)$"),
+    "tidal": re.compile(r"(?:^|tidal\.com/(?:browse/)?(?:album|track)/)(\d+)"),
 }
 
 

beetsplug/_utils/requests.py

@@ -2,6 +2,7 @@
 
 import atexit
 import threading
+import time
 from contextlib import contextmanager
 from functools import cached_property
 from http import HTTPStatus
@@ -103,6 +104,38 @@ def request(self, *args, **kwargs):
         return r
 
 
+class RateLimitAdapter(HTTPAdapter):
+    """HTTPAdapter that enforces minimum interval between requests.
+
+    Prevents server overload and 429 errors by sleeping when requests
+    come too fast. Thread-safe via lock.
+
+    Attributes:
+        rate_limit: Minimum seconds between requests. Default 0.25 (4/sec).
+
+    Override `_wait_time()` for custom strategies (token bucket, burst, etc.).
+    """
+
+    def __init__(self, rate_limit: float = 0.25, **kwargs):
+        super().__init__(**kwargs)
+        self.rate_limit = rate_limit
+        self._last_request_time = 0.0
+        self._lock = threading.Lock()
+
+    def _wait_time(self, elapsed: float) -> float:
+        """Return seconds to wait. Override for custom rate limiting."""
+        return max(0, self.rate_limit - elapsed)
+
+    def send(self, request: requests.PreparedRequest, *args, **kwargs):
+        with self._lock:
+            elapsed = time.monotonic() - self._last_request_time
+            wait = self._wait_time(elapsed)
+            if wait > 0:
+                time.sleep(wait)
+            self._last_request_time = time.monotonic()
+        return super().send(request, *args, **kwargs)
+
+
 class RequestHandler:
     """Manages HTTP requests with custom error handling and session management.