DESCRIPTION.

Retourne une sélection de valeurs, prise dans les éléments d'une collection donnée, pseudo-aléatoirement. 

SYNTAXE.

LST_Valeurs = random.sample ( collection , quota , poids )

Valeur = ⇨ variable qui recevra la valeur [ optionnel ]

random.sample ( ) ⇨ appel de la méthode [ OBLIGATOIRE ]

collection ⇨ objet collection [ OBLIGATOIRE ]

quota ⇨ nombre d'éléments dans le sous-ensemble [ optionnel ]

poids ⇨ pondération des éléments [ optionnel ]

REMARQUES.

collection doit être un objet valide contenant une collection de valeurs, tel que list ( ), tuple ( ), range ( ) ... Si collection est vide Python lèvera une exception. collection n'est pas un argument nommé, il doit donc toujours être le premier argument fourni à la méthode random.sample ( ).

quota doit être un int ( ) valide. quota n'est pas un argument nommé, il doit donc toujours être le deuxième argument fourni à la méthode random.sample ( ). Python lèvera une exception si quota : 

- n'est pas strictement positif ;  

- est supérieur au nombre d'éléments dans collection, c'est à dire à len ( collection ) ; 

- est absent.

poids est un argument nommé de la forme counts = sequence, où sequence doit être un objet valide contenant une collection de valeurs de type int ( ), avec autant d'éléments que collection. Chaque éléments de sequence corresponds au poids de pondération de l'élément de collection au même index. L'utilisation du paramètre poids implique un changement de collection de référence, où seront pigées les valeurs. Par exemple avec random.sample ( [ "A" , "B" , "C" ] , quota , counts = [ 3 , 7 , 4 ] ), collection de référence correspondra à [ "A" , "A" , "A" , "B" , "B" , "B" , "B" , "B" , "B" , "B" , "C" , "C" , "C" , "C" ]. soit 14 éléments au lieu de 3. Si sequence n'est pas exactement le même nombre d'éléments que collection, ou si tous ses éléments valent 0, Python lèvera une exception.

La méthode random.sample ( ) effectue un tirage sans remise, la valeur pigée est retirée de collection. Un élément de collection ne peut donc apparaitre qu'une seule fois dans la liste retournée, sauf si poids est présent. Toutefois, comme les éléments de collection n'ont pas besoin d'être hachables ou uniques, si des éléments de collection ont des valeurs identiques, chacun de ces éléments à la possibilité d'être tiré. Des valeurs identiques peuvent donc apparaitre dans la liste retournée si collection contient des doublons ou autres répétitions.

Les éléments de la liste retournée par la méthode random.sample ( ) restent classés dans ordre du tirage. Ce qui a pour conséquence que toutes les sous-tranches soient également des sélections aléatoires valides. Il sera donc possible d'établir des gagnant du première rang, puis du deuxième rang et ainsi de suite.

Voir la méthode random.choices ( ) effectuer un tirage avec remise.

EXEMPLE.

import random

print ( random.sample ( [ "John" , "Paula" , "Marie" , "Bob" ] , 3 ) ) retourne, par exemple, ['Paula', 'John', 'Bob'] 

LST_Tickets = list ( range ( 500 ) )

print ( random.sample ( LST_Tickets , 5 ) ) retourne, par exemple, [1, 128, 79, 8, 181]

Phrase = "Du débutant à l'expert, Python réalise tous vos programmes."

print ( random.sample ( Phrase , 15 ) ) retourne, par exemple, ['x', 'é', 'p', ' ', 'u', 'm', 'm', 'à', 'l', 'l', 'e', 't', "'", 't', 'r']

TPL_Lettres = ( "P" , "y" , "t" , "h" ,"o" , "n" )

LST_Poids = [ 9 , 2 , 4 , 7 , 9 , 5 ]

print ( random.sample ( TPL_Lettres , 10 , counts = LST_Poids ) ) retourne, ['P', 'n', 'o', 'h', 'h', 'h', 'o', 'n', 'P', 'o']

print ( random.sample ( TPL_Lettres , 123 , counts = LST_Poids ) ) retourneValueError: Sample larger than population or is negative

Dans ces deux derniers exemples, la collection prise en compte pour le tirage est constituée de 9 lettres P, 2 lettres y,  4 lettres t, 7 lettres h,  9 lettres o et 5 lettres n. Soit 9 + 2 + 4 + 7 + 9 + 5 = 36 lettres, ou éléments pour la collection de référence. Ce qui explique que : 

- on peut obtenir une sélection de 10 éléments, alors que le TPL_Lettres n'en contienne que 6 ;

- on ne peut pas obtenir une sélection de 123 éléments, car la collection de référence n'en contienne que 36.