fluxwave 0.1.0__py3-none-any.whl

fluxwave/__init__.py

@@ -0,0 +1,268 @@
+"""FluxWave — modern async Lavalink wrapper for Python Discord bots."""
+
+from ._libraries import library as discord_library
+from ._meta import (  # noqa: F401
+    __author__,
+    __license__,
+    __url__,
+    __version__,
+    __version_info__,
+)
+from .autoplay import AutoPlayMode, RecommendationProvider, SearchRecommendationProvider
+from .backoff import Backoff
+from .cache import LFUCache
+from .events import (
+    EventDispatcher,
+    EventPayload,
+    EventType,
+    ExtraEvent,
+    InactivePlayerEvent,
+    NodeClosedEvent,
+    NodeDisconnectedEvent,
+    NodeReadyEvent,
+    PlayerUpdateEvent,
+    PluginEvent,
+    RawWebSocketEvent,
+    StatsUpdateEvent,
+    TrackEndEvent,
+    TrackExceptionEvent,
+    TrackStartEvent,
+    TrackStuckEvent,
+    WebSocketClosedEvent,
+    close_listeners,
+    dispatch,
+    listen,
+    remove_listener,
+)
+from .exceptions import (
+    AuthorizationError,
+    ChannelTimeoutError,
+    FluxWaveError,
+    InvalidChannelError,
+    InvalidNodeError,
+    LavalinkError,
+    LavalinkErrorResponse,
+    MultipleDiscordLibrariesError,
+    NodeConnectionError,
+    NodeError,
+    NoDiscordLibraryError,
+    PlayerError,
+    QueueEmpty,
+    QueueError,
+    QueueFull,
+    TrackLoadError,
+    UnsupportedLavalinkVersion,
+)
+from .filters import (
+    ChannelMixFilter,
+    DistortionFilter,
+    EqualizerFilter,
+    Filters,
+    KaraokeFilter,
+    LowPassFilter,
+    PluginFiltersComponent,
+    RotationFilter,
+    TimescaleFilter,
+    TremoloFilter,
+    VibratoFilter,
+)
+from .formatting import QueuePage, format_duration, paginate_queue, progress_bar
+from .metrics import WrapperMetrics, metrics
+from .node import (
+    DEFAULT_REGION_GROUPS,
+    Node,
+    NodePool,
+    NodeSelectionStrategy,
+    NodeStatus,
+    calculate_shard_id,
+    parse_voice_region,
+)
+from .persistence import FileStore, MemoryStore, PersistedState, PersistenceBackend, capture
+from .player import FluxPlayer, Player
+from .plugins import (
+    LavaSrcClient,
+    LyricsClient,
+    PluginClient,
+    PluginHelpers,
+    SponsorBlockClient,
+)
+from .pool import Pool
+from .queue import Queue, QueueMode
+from .rest import PlayerUpdate, RestClient, SessionUpdate
+from .results import EnqueueResult, LyricsLine, LyricsResult
+from .routeplanner import RoutePlannerStatus
+from .router import SourceRoute, SourceRouter
+from .search import SearchQuery, SearchSource, build_search_query
+from .tracing import EventTracer, TraceCategory, TraceEvent, tracer
+from .tracks import (
+    Album,
+    Artist,
+    ExtrasNamespace,
+    LavalinkPlayer,
+    LoadError,
+    LoadResult,
+    LoadType,
+    NodeInfo,
+    PlayerState,
+    Playlist,
+    Stats,
+    Track,
+    TrackInfo,
+    VoiceState,
+)
+from .versioning import (
+    LavalinkVersion,
+    LavalinkVersionCheck,
+    LavalinkVersionWarning,
+    check_lavalink_version,
+    parse_lavalink_version,
+)
+from .watchdog import VoiceWatchdog, WatchdogConfig, WatchdogStats
+from .websocket import WebSocketClient
+
+__all__ = (
+    "DEFAULT_REGION_GROUPS",
+    # models
+    "Album",
+    "Artist",
+    # exceptions
+    "AuthorizationError",
+    # autoplay
+    "AutoPlayMode",
+    "Backoff",
+    # filters
+    "ChannelMixFilter",
+    "ChannelTimeoutError",
+    "DistortionFilter",
+    # results
+    "EnqueueResult",
+    "EqualizerFilter",
+    # events
+    "EventDispatcher",
+    "EventPayload",
+    # tracing
+    "EventTracer",
+    "EventType",
+    "ExtraEvent",
+    "ExtrasNamespace",
+    # persistence backends
+    "FileStore",
+    "Filters",
+    # player
+    "FluxPlayer",
+    "FluxWaveError",
+    "InactivePlayerEvent",
+    "InvalidChannelError",
+    "InvalidNodeError",
+    "KaraokeFilter",
+    # cache
+    "LFUCache",
+    # plugins
+    "LavaSrcClient",
+    "LavalinkError",
+    "LavalinkErrorResponse",
+    "LavalinkPlayer",
+    "LavalinkVersion",
+    "LavalinkVersionCheck",
+    "LavalinkVersionWarning",
+    "LoadError",
+    "LoadResult",
+    "LoadType",
+    "LowPassFilter",
+    "LyricsClient",
+    "LyricsLine",
+    "LyricsResult",
+    # persistence
+    "MemoryStore",
+    "MultipleDiscordLibrariesError",
+    "NoDiscordLibraryError",
+    # node
+    "Node",
+    "NodeClosedEvent",
+    "NodeConnectionError",
+    "NodeDisconnectedEvent",
+    "NodeError",
+    "NodeInfo",
+    "NodePool",
+    "NodeReadyEvent",
+    "NodeSelectionStrategy",
+    "NodeStatus",
+    "PersistedState",
+    "PersistenceBackend",
+    "Player",
+    "PlayerError",
+    "PlayerState",
+    # REST
+    "PlayerUpdate",
+    "PlayerUpdateEvent",
+    "Playlist",
+    "PluginClient",
+    "PluginEvent",
+    "PluginFiltersComponent",
+    "PluginHelpers",
+    # pool
+    "Pool",
+    # queue
+    "Queue",
+    "QueueEmpty",
+    "QueueError",
+    "QueueFull",
+    "QueueMode",
+    "QueuePage",
+    "RawWebSocketEvent",
+    "RecommendationProvider",
+    "RestClient",
+    "RotationFilter",
+    "RoutePlannerStatus",
+    # search
+    "SearchQuery",
+    "SearchRecommendationProvider",
+    "SearchSource",
+    "SessionUpdate",
+    # routing
+    "SourceRoute",
+    "SourceRouter",
+    "SponsorBlockClient",
+    "Stats",
+    "StatsUpdateEvent",
+    "TimescaleFilter",
+    "TraceCategory",
+    "TraceEvent",
+    "Track",
+    "TrackEndEvent",
+    "TrackExceptionEvent",
+    "TrackInfo",
+    "TrackLoadError",
+    "TrackStartEvent",
+    "TrackStuckEvent",
+    "TremoloFilter",
+    "UnsupportedLavalinkVersion",
+    "VibratoFilter",
+    "VoiceState",
+    # watchdog (voice resilience)
+    "VoiceWatchdog",
+    "WatchdogConfig",
+    "WatchdogStats",
+    "WebSocketClient",
+    "WebSocketClosedEvent",
+    # metrics
+    "WrapperMetrics",
+    # meta
+    "__version__",
+    "build_search_query",
+    "calculate_shard_id",
+    "capture",
+    "check_lavalink_version",
+    "close_listeners",
+    "discord_library",
+    "dispatch",
+    "format_duration",
+    "listen",
+    "metrics",
+    "paginate_queue",
+    "parse_lavalink_version",
+    "parse_voice_region",
+    "progress_bar",
+    "remove_listener",
+    "tracer",
+)

fluxwave/__main__.py

@@ -0,0 +1,70 @@
+"""Command line helpers for FluxWave."""
+
+from __future__ import annotations
+
+import argparse
+import platform
+import subprocess
+import sys
+
+import fluxwave
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the FluxWave command line interface."""
+
+    parser = argparse.ArgumentParser(prog="fluxwave")
+    parser.add_argument(
+        "--version",
+        action="store_true",
+        help="Show FluxWave version and debug information.",
+    )
+
+    args = parser.parse_args(argv)
+    if args.version:
+        print(debug_info())
+        return 0
+
+    parser.print_help()
+    return 0
+
+
+def debug_info() -> str:
+    """Return version, Python, platform, and Java diagnostic information."""
+
+    python_info = "\n        - ".join(sys.version.splitlines())
+    java_info = "\n        - ".join(_java_version().splitlines())
+    return f"""fluxwave: {fluxwave.__version__}
+
+Python:
+        - {python_info}
+System:
+        - {platform.platform()}
+Java:
+        - {java_info}
+"""
+
+
+def _java_version() -> str:
+    try:
+        completed = subprocess.run(
+            ["java", "-version"],
+            check=False,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        return "Java executable not found"
+
+    output = (completed.stderr or completed.stdout).strip()
+    if not output:
+        return "Version not found"
+
+    if completed.returncode != 0:
+        return f"Command failed with exit code {completed.returncode}: {output}"
+
+    return output
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

fluxwave/_libraries.py

@@ -0,0 +1,100 @@
+"""Discord-library compatibility layer.
+
+FluxWave works with any discord.py-compatible library: discord.py, py-cord,
+nextcord, and disnake.  This module detects which one is installed at import
+time and re-exports the small set of names FluxWave needs, so the rest of the
+package never imports a specific library directly.
+
+discord.py and py-cord both provide the top-level ``discord`` module and share
+the same public API, so they are detected as a single ``discord`` backend.
+
+The re-exported names are resolved dynamically, so type checkers see them as
+``Any`` here. ``player.py`` imports the concrete discord.py types under
+``TYPE_CHECKING`` for accurate static analysis while binding these at runtime.
+
+Environment variables
+---------------------
+``FLUXWAVE_DISCORD_LIBRARY``
+    Force a backend (``discord``, ``nextcord``, or ``disnake``) when more than
+    one is installed, or to override auto-detection.
+``FLUXWAVE_IGNORE_LIBRARY_CHECK``
+    Skip the "no/multiple libraries" guard and fall back to the first match
+    (or ``discord``).  Mainly useful for documentation builds.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+from os import getenv
+from typing import TYPE_CHECKING, Any
+
+from .exceptions import MultipleDiscordLibrariesError, NoDiscordLibraryError
+
+if TYPE_CHECKING:
+    from types import ModuleType
+
+__all__ = (
+    "Client",
+    "Connectable",
+    "Guild",
+    "Snowflake",
+    "VoiceProtocol",
+    "library",
+    "version_info",
+)
+
+SUPPORTED_LIBRARIES = ("discord", "nextcord", "disnake")
+
+_ALIASES = {
+    "discord.py": "discord",
+    "discordpy": "discord",
+    "py-cord": "discord",
+    "pycord": "discord",
+}
+
+
+def _detect_library() -> str:
+    forced = getenv("FLUXWAVE_DISCORD_LIBRARY")
+    if forced:
+        choice = forced.strip().lower()
+        choice = _ALIASES.get(choice, choice)
+        if choice not in SUPPORTED_LIBRARIES:
+            msg = (
+                f"FLUXWAVE_DISCORD_LIBRARY={forced!r} is not supported; choose one of "
+                f"{', '.join(SUPPORTED_LIBRARIES)}."
+            )
+            raise NoDiscordLibraryError(msg)
+        if importlib.util.find_spec(choice) is None:
+            msg = f"FLUXWAVE_DISCORD_LIBRARY={forced!r} is set but {choice!r} is not installed."
+            raise NoDiscordLibraryError(msg)
+        return choice
+
+    found = [name for name in SUPPORTED_LIBRARIES if importlib.util.find_spec(name) is not None]
+
+    if getenv("FLUXWAVE_IGNORE_LIBRARY_CHECK"):
+        return found[0] if found else "discord"
+    if not found:
+        raise NoDiscordLibraryError
+    if len(found) > 1:
+        raise MultipleDiscordLibrariesError(found)
+    return found[0]
+
+
+library: str = _detect_library()
+
+_module: ModuleType = importlib.import_module(library)
+_abc: ModuleType = importlib.import_module(f"{library}.abc")
+
+Client: Any = _module.Client
+Guild: Any = _module.Guild
+VoiceProtocol: Any = _module.VoiceProtocol
+version_info: Any = _module.version_info
+
+Connectable: Any = _abc.Connectable
+Snowflake: Any = _abc.Snowflake
+
+if getattr(version_info, "major", 0) < 2:
+    _found_major = getattr(version_info, "major", "?")
+    _msg = f"FluxWave requires {library} v2.0 or newer, but found {_found_major}.x."
+    raise NoDiscordLibraryError(_msg)

fluxwave/_meta.py

@@ -0,0 +1,7 @@
+"""Package metadata."""
+
+__version__ = "0.1.0"
+__version_info__: tuple[int, int, int, str, int] = (0, 1, 0, "final", 0)
+__author__ = "FluxWave Contributors"
+__license__ = "MIT"
+__url__ = "https://github.com/NobitaDeveloper/fluxwave"

fluxwave/autoplay.py

@@ -0,0 +1,162 @@
+"""Autoplay and recommendation primitives."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Protocol
+
+from .search import Search, SearchSource
+from .tracks import Track
+
+
+class SearchNode(Protocol):
+    """Node subset needed by the default recommendation provider."""
+
+    async def search(
+        self,
+        query: str,
+        *,
+        source: SearchSource | str | None = SearchSource.YOUTUBE,
+        use_cache: bool = True,
+    ) -> Search:
+        """Search for tracks."""
+        ...
+
+
+class AutoPlayMode(StrEnum):
+    """How a player should use generated recommendations."""
+
+    DISABLED = "disabled"
+    PARTIAL = "partial"
+    ENABLED = "enabled"
+    disabled = "disabled"
+    partial = "partial"
+    enabled = "enabled"
+
+
+class RecommendationProvider(Protocol):
+    """Interface for source-specific recommendation providers."""
+
+    async def recommendations(
+        self,
+        seed: Track,
+        *,
+        limit: int = 5,
+    ) -> list[Track]:
+        """Return recommendation tracks for a seed track."""
+        ...
+
+
+@dataclass(slots=True)
+class SearchRecommendationProvider:
+    """Simple recommendation provider using Lavalink search sources."""
+
+    node: SearchNode
+    source: SearchSource | str | None = None
+
+    async def recommendations(
+        self,
+        seed: Track,
+        *,
+        limit: int = 5,
+    ) -> list[Track]:
+        tracks: list[Track] = []
+        seen = {_track_key(seed)}
+        for query, source in _queries_for_track(seed, limit=limit, source=self.source):
+            result = await self.node.search(query, source=source)
+            if not isinstance(result, list):
+                continue
+
+            for track in result:
+                key = _track_key(track)
+                if key in seen:
+                    continue
+
+                seen.add(key)
+                tracks.append(track.as_recommended())
+                if len(tracks) >= limit:
+                    return _rank_recommendations(seed, tracks)
+
+        return _rank_recommendations(seed, tracks)
+
+
+def _source_for_track(track: Track) -> SearchSource | str | None:
+    if track.source == "spotify":
+        return None
+    if track.source == "youtube":
+        return None
+    if track.source == "soundcloud":
+        return SearchSource.SOUNDCLOUD
+    return SearchSource.YOUTUBE
+
+
+def _query_for_track(track: Track, *, limit: int) -> str:
+    if track.source == "spotify":
+        return f"sprec:seed_tracks={track.identifier}&limit={limit}"
+
+    if track.source == "youtube":
+        return f"https://music.youtube.com/watch?v={track.identifier}&list=RD{track.identifier}"
+
+    album = track.plugin_info.get("album") or track.plugin_info.get("albumName")
+    if isinstance(album, str) and album:
+        return f"{track.author} {album}"
+
+    return f"{track.author} {track.title}"
+
+
+def _queries_for_track(
+    track: Track,
+    *,
+    limit: int,
+    source: SearchSource | str | None,
+) -> list[tuple[str, SearchSource | str | None]]:
+    selected_source = source if source is not None else _source_for_track(track)
+    queries: list[tuple[str, SearchSource | str | None]] = [
+        (_query_for_track(track, limit=limit), selected_source)
+    ]
+
+    title_author = f"{track.author} {track.title}"
+    if track.source in {"spotify", "youtube"}:
+        queries.append((title_author, SearchSource.YOUTUBE_MUSIC))
+        queries.append((title_author, SearchSource.YOUTUBE))
+    elif track.source == "soundcloud":
+        queries.append((title_author, SearchSource.SOUNDCLOUD))
+        queries.append((title_author, SearchSource.YOUTUBE))
+    else:
+        queries.append((title_author, SearchSource.YOUTUBE_MUSIC))
+        queries.append((title_author, SearchSource.SOUNDCLOUD))
+
+    deduped: list[tuple[str, SearchSource | str | None]] = []
+    seen: set[tuple[str, str | None]] = set()
+    for query, query_source in queries:
+        key = (query, str(query_source) if query_source is not None else None)
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append((query, query_source))
+
+    return deduped
+
+
+def _track_key(track: Track) -> str:
+    title = " ".join(track.title.casefold().split())
+    author = " ".join(track.author.casefold().split())
+    return f"{track.source or ''}:{track.identifier}:{title}:{author}"
+
+
+def _rank_recommendations(seed: Track, tracks: list[Track]) -> list[Track]:
+    return sorted(tracks, key=lambda track: _recommendation_score(seed, track), reverse=True)
+
+
+def _recommendation_score(seed: Track, track: Track) -> float:
+    score = 1.0
+    if track.source == seed.source:
+        score += 0.3
+    if track.author.casefold() == seed.author.casefold():
+        score += 0.4
+    if seed.title.casefold() in track.title.casefold():
+        score -= 0.2
+    if track.recommended:
+        score += 0.1
+    return score

fluxwave/backoff.py

@@ -0,0 +1,51 @@
+"""Jittered reconnect backoff helpers."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class Backoff:
+    """Randomized exponential backoff for reconnect loops."""
+
+    base: float = 0.5
+    maximum_time: float = 30.0
+    maximum_tries: int | None = None
+    jitter: bool = True
+    _retries: int = field(default=1, init=False)
+    _last_wait: float = field(default=0.0, init=False)
+    _random: Callable[[float, float], float] = field(
+        default_factory=lambda: random.Random().uniform,
+        init=False,
+        repr=False,
+    )
+
+    def calculate(self) -> float:
+        """Return the next delay and advance internal retry state."""
+
+        if self.base <= 0:
+            return 0.0
+
+        exponent = min(float(self._retries * self._retries), self.maximum_time)
+        ceiling = min(self.maximum_time, self.base * 2 * exponent)
+        wait = self._random(0.0, ceiling) if self.jitter else ceiling
+
+        if self.jitter and wait <= self._last_wait:
+            wait = min(self.maximum_time, self._last_wait * 2 if self._last_wait else ceiling)
+
+        self._last_wait = wait
+        if self.maximum_tries is not None and self._retries >= self.maximum_tries:
+            self.reset()
+        else:
+            self._retries += 1
+
+        return wait
+
+    def reset(self) -> None:
+        """Reset retry counters."""
+
+        self._retries = 1
+        self._last_wait = 0.0