Add populate feature to Player.play

.github/workflows/coverage_and_lint.yml

@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.x"]
+        python-version: ["3.10", "3.x"]
 
     name: "Type Coverage and Linting @ ${{ matrix.python-version }}"
     steps:
@@ -34,22 +34,14 @@ jobs:
       - name: "Install Python deps @ ${{ matrix.python-version }}"
         id: install-deps
         run: |
-          pip install -U -r requirements.txt
+          pip install -Ur requirements.txt
       - name: "Run Pyright @ ${{ matrix.python-version }}"
         uses: jakebailey/pyright-action@v1
         with:
           no-comments: ${{ matrix.python-version != '3.x' }}
           warnings: false
 
-      - name: Lint
+      - name: Lint with Ruff
         if: ${{ always() && steps.install-deps.outcome == 'success' }}
-        uses: github/super-linter/slim@v4
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          DEFAULT_BRANCH: main
-          VALIDATE_ALL_CODEBASE: false
-          VALIDATE_PYTHON_BLACK: true
-          VALIDATE_PYTHON_ISORT: true
-          LINTER_RULES_PATH: /
-          PYTHON_ISORT_CONFIG_FILE: pyproject.toml
-          PYTHON_BLACK_CONFIG_FILE: pyproject.toml
+        uses: chartboost/ruff-action@v1
+

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wavelink"
-version = "3.2.1"
+version = "3.3.0"
 authors = [
   { name="PythonistaGuild, EvieePy", email="[email protected]" },
 ]
@@ -38,14 +38,68 @@ dependencies = {file = ["requirements.txt"]}
 [tool.setuptools.package-data]
 wavelink = ["py.typed"]
 
-[tool.black]
+[tool.ruff]
 line-length = 120
+indent-width = 4
+exclude = ["venv", "docs/"]
 
-[tool.isort]
-profile = "black"
+[tool.ruff.lint]
+select = [
+    "C4",
+    "E",
+    "F",
+    "G",
+    "I",
+    "PTH",
+    "RUF",
+    "SIM",
+    "TCH",
+    "UP",
+    "W",
+    "PERF",
+    "ANN",
+]
+ignore = [
+    "F402",
+    "F403",
+    "F405",
+    "PERF203",
+    "RUF001",
+    "RUF009",
+    "SIM105",
+    "UP034",
+    "UP038",
+    "ANN101",
+    "ANN102",
+    "ANN401",
+    "UP031",
+    "PTH123",
+    "E203", 
+    "E501",
+]
+
+[tool.ruff.lint.isort]
+split-on-trailing-comma = true
+combine-as-imports = true
+lines-after-imports = 2
+
+[tool.ruff.lint.flake8-annotations]
+allow-star-arg-any = true
+
+[tool.ruff.lint.flake8-quotes]
+inline-quotes = "double"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
 
 [tool.pyright]
 ignore = ["test*.py", "examples/*.py", "docs/*"]
-pythonVersion = "3.10"
+useLibraryCodeForTypes = true
 typeCheckingMode = "strict"
+reportImportCycles = false
 reportPrivateUsage = false
+pythonVersion = "3.10"
+

requirements.txt

@@ -1,4 +1,5 @@
 aiohttp>=3.7.4,<4
 discord.py>=2.0.1
 yarl>=1.9.2
-async_timeout
+async_timeout
+typing_extensions

wavelink/__init__.py

@@ -25,7 +25,7 @@
 __author__ = "PythonistaGuild, EvieePy"
 __license__ = "MIT"
 __copyright__ = "Copyright 2019-Present (c) PythonistaGuild, EvieePy"
-__version__ = "3.2.1"
+__version__ = "3.3.0"
 
 
 from .enums import *

wavelink/player.py

@@ -262,11 +262,13 @@ async def _do_partial(self, *, history: bool = True) -> None:
 
             await self.play(track, add_history=history)
 
-    async def _do_recommendation(self):
+    async def _do_recommendation(self, *, populate_track: wavelink.Playable | None = None, max_population: int | None = None,):
         assert self.guild is not None
         assert self.queue.history is not None and self.auto_queue.history is not None
+
+        max_population_: int = max_population if max_population else self._auto_cutoff
 
-        if len(self.auto_queue) > self._auto_cutoff + 1:
+        if len(self.auto_queue) > self._auto_cutoff + 1 and not populate_track:
             # We still do the inactivity start here since if play fails and we have no more tracks...
             # we should eventually fire the inactivity event...
             self._inactivity_start()
@@ -285,6 +287,9 @@ async def _do_recommendation(self):
         _previous: deque[str] = self.__previous_seeds._queue  # type: ignore
         seeds: list[Playable] = [t for t in choices if t is not None and t.identifier not in _previous]
         random.shuffle(seeds)
+
+        if populate_track:
+            seeds.insert(0, populate_track)
 
         spotify: list[str] = [t.identifier for t in seeds if t.source == "spotify"]
         youtube: list[str] = [t.identifier for t in seeds if t.source == "youtube"]
@@ -370,10 +375,13 @@ async def _search(query: str | None) -> T_a:
 
             track._recommended = True
             added += await self.auto_queue.put_wait(track)
+
+            if added >= max_population_:
+                break
 
         logger.debug(f'Player "{self.guild.id}" added "{added}" tracks to the auto_queue via AutoPlay.')
 
-        if not self._current:
+        if not self._current and not populate_track:
             try:
                 now: Playable = self.auto_queue.get()
                 self.auto_queue.history.put(now)
@@ -724,6 +732,8 @@ async def play(
         paused: bool | None = None,
         add_history: bool = True,
         filters: Filters | None = None,
+        populate: bool = False,
+        max_populate: int = 5,
     ) -> Playable:
         """Play the provided :class:`~wavelink.Playable`.
 
@@ -756,6 +766,23 @@ async def play(
         filters: Optional[:class:`~wavelink.Filters`]
             An Optional[:class:`~wavelink.Filters`] to apply when playing this track. Defaults to ``None``.
             If this is ``None`` the currently set filters on the player will be applied.
+        populate: bool
+            Whether the player should find and fill AutoQueue with recommended tracks based on the track provided.
+            Defaults to ``False``.
+
+            Populate will only search for recommended tracks when the current tracks has been accepted by Lavalink. 
+            E.g. if this method does not raise an error.
+
+            You should consider when you use the ``populate`` keyword argument as populating the AutoQueue on every 
+            request could potentially lead to a large amount of tracks being populated.
+        max_populate: int
+            The maximum amount of tracks that should be added to the AutoQueue when the ``populate`` keyword argument is
+            set to ``True``. This is NOT the exact amount of tracks that will be added. You should set this to a lower
+            amount to avoid the AutoQueue from being overfilled.
+
+            This argument has no effect when ``populate`` is set to ``False``.
+
+            Defaults to ``5``.
 
 
         Returns
@@ -772,6 +799,11 @@ async def play(
             Added the ``add_history`` keyword-only argument.
 
             Added the ``filters`` keyword-only argument.
+
+
+        .. versionchanged:: 3.3.0
+
+            Added the ``populate`` keyword-only argument.
         """
         assert self.guild is not None
 
@@ -820,6 +852,9 @@ async def play(
         if add_history:
             assert self.queue.history is not None
             self.queue.history.put(track)
+
+        if populate:
+            await self._do_recommendation(populate_track=track, max_population=max_populate)
 
         return track