feat(play): Add -R/--randomize option to play plugin

Author: amiv1

beetsplug/play.py

@@ -14,6 +14,7 @@
 
 """Send the results of a query to the configured music player as a playlist."""
 
+import random
 import shlex
 import subprocess
 from os.path import relpath
@@ -91,6 +92,12 @@ def commands(self):
             action="store",
             help="add additional arguments to the command",
         )
+        play_command.parser.add_option(
+            "-R",
+            "--randomize",
+            action="store_true",
+            help="randomize the order of tracks in the playlist",
+        )
         play_command.parser.add_option(
             "-y",
             "--yes",
@@ -131,6 +138,9 @@ def _play_command(self, lib, opts, args):
         if relative_to:
             paths = [relpath(path, relative_to) for path in paths]
 
+        if opts.randomize:
+            random.shuffle(paths)
+
         if not selection:
             ui.print_(ui.colorize("text_warning", f"No {item_type} to play."))
             return

docs/changelog.rst

@@ -9,9 +9,11 @@ below!
 Unreleased
 ----------
 
-..
-    New features
-    ~~~~~~~~~~~~
+New features
+~~~~~~~~~~~~
+
+- :doc:`plugins/play`: Added ``-R``/``--randomize`` flag to shuffle the
+  playlist order before passing it to the player.
 
 ..
     Bug fixes

docs/plugins/play.rst

@@ -120,6 +120,13 @@ The ``--yes`` (or ``-y``) flag to the ``play`` command will skip the warning
 message if you choose to play more items than the **warning_threshold** value
 usually allows.
 
+The ``--randomize`` (or ``-R``) flag shuffles the order of tracks in the
+playlist before passing it to the player:
+
+::
+
+    $ beet play --randomize my query
+
 Note on the Leakage of the Generated Playlists
 ----------------------------------------------
 

test/plugins/test_play.py

@@ -145,6 +145,22 @@ def test_skip_warning_threshold_bypass(self, open_mock):
             expected_playlist=expected_playlist,
         )
 
+    def test_randomize(self, open_mock):
+        self.other_item = self.add_item(title="anotherTitle")
+
+        with patch("beetsplug.play.random.shuffle") as shuffle_mock:
+            self.run_command("play", "-R", "NiceTitle")
+
+        shuffle_mock.assert_called_once()
+
+    def test_no_randomize_by_default(self, open_mock):
+        self.other_item = self.add_item(title="anotherTitle")
+
+        with patch("beetsplug.play.random.shuffle") as shuffle_mock:
+            self.run_command("play", "NiceTitle")
+
+        shuffle_mock.assert_not_called()
+
     def test_command_failed(self, open_mock):
         open_mock.side_effect = OSError("some reason")