Implemented random_permutation() in place of shuffle() and adding docstring for the same.

random_permutation() utilizes permutation() of numpy and return a sequence.

Author: mohitbhasin

py5_docs/Reference/api_en/Sketch_random_permutation.txt

@@ -0,0 +1,24 @@
+@@ meta
+name = random_permutation()
+type = method
+category = math
+subcategory = random
+
+@@ signatures
+random_permutation(seq: Sequence[Any] -> Sequence[Any]
+
+@@ variables
+seq: Sequence[Any] - Sequence of objects for which random permutation is required.
+
+@@ description
+Generates a random permutation for the given sequence. Each time the `random_permutation()` is called, it generates and return a random permuted sequence of the given sequence.
+
+The returned value will always be a sequence such as a list. If the provided sequence is empty, an empty list will be returned.
+
+This function's randomness can be influenced by [](sketch_random_seed), and makes calls to numpy to select the random permutation.
+
+@@ example
+def setup():
+    words = ["apple", "bear", "cat", "dog"]
+    perm = py5.random_permutation(words)
+    py5.println(perm)  # Prints one of the permutation of words.

py5_resources/py5_module/py5/mixins/math.py

@@ -23,7 +23,7 @@
 import types
 import warnings
 from pathlib import Path
-from typing import Any, Union, overload
+from typing import Any, Union, overload, Sequence
 
 import numpy as np
 import numpy.typing as npt
@@ -352,9 +352,17 @@ def random_sample(
         else:
             return []
 
-    def shuffle(self, objects: list[Any]) -> list[Any]:
-        """$class_Sketch_shuffle"""
-        return self.random_sample(objects, len(objects), False)
+    def random_permutation(self, seq: Sequence[Any]) -> Sequence[Any]:
+        """$class_Sketch_random_permutation"""
+        if isinstance(seq, types.GeneratorType):
+            seq = list(seq)
+        indices = self._rng.permutation(range(len(seq)))
+        if not isinstance(seq, list):
+            try:
+                return seq[indices]
+            except:
+                pass
+        return [seq[idx] for idx in indices]
 
     @overload
     def random_gaussian(self) -> float: