Merge pull request #594 from mohitbhasin/add-shuffle-function

Adding shuffle function to math.py

Author: hx2A

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()` method 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/data/sketch.csv

@@ -368,6 +368,7 @@ random_gaussian,randomGaussian,,method,math,random,PYTHON,implementation uses nu
 random_int,,,method,math,random,PYTHON,implementation uses numpy for performance reasons
 random_choice,,,method,math,random,PYTHON,implementation uses numpy for performance reasons
 random_sample,,,method,math,random,PYTHON,implementation uses numpy for performance reasons
+random_permutation,,,method,math,random,PYTHON,implementation uses numpy for performance reasons
 random_seed,randomSeed,,method,math,random,PYTHON,implementation uses numpy for performance reasons
 choice,choice,,method,math,random,SKIP,new method but functionality already provided by random_int
 np_random,,,dynamic variable,math,random,PYTHON,make numpy random number generator available to users

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,6 +352,18 @@ def random_sample(
         else:
             return []
 
+    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:
         """$class_Sketch_random_gaussian"""