# Bibliothèque `randomy` (clone de `random` de Python) — v1.0.0

Source : https://docs.berkios.online/modules/randomy/ · Section : Modules · Documentation officielle BERKIOS (https://docs.berkios.online)


30 commandes pour BERKIOS CODE qui reprennent le module `random` de Python : `seed`, `randint`, `randrange`, `choice`, `choices`, `sample`, `shuffle`, `uniform`, les lois de probabilité (`gauss`, `normalvariate`, `gammavariate`, `betavariate`, `binomialvariate`…), `getrandbits`, `randbytes`, `getstate` / `setstate`.
Chaque commande existe sous son **nom Python**, en **français**, en **espagnol** et en **swahili** ; la forme qualifiée `randomy.<nom>` fonctionne aussi.
Aucune permission n'est demandée. Les commandes sont de simples macros vers les 50 commandes intégrées de la catégorie **« Génération aléatoire »** (voir la leçon formation/08) : le moteur est dans `studio/src/model/random-engine.ts`.

## Même graine, mêmes tirages qu'en Python

Le moteur est un Mersenne Twister MT19937 qui suit les algorithmes de CPython 3.12/3.13. Avec la même graine, les suites sont identiques :

```text
quand clic
  randomy.seed 42
  randomy.random "$a"        # 0.6394267984578837, comme random.seed(42); random.random()
  seed 5
  randint "$de" 1 6          # 5, 3, 6, 3, 6, 6… comme random.seed(5); [random.randint(1, 6) …]
  seed 9
  shuffle "$liste"           # mélange identique à random.shuffle après random.seed(9)
```

Vérifié contre CPython 3.13 (`studio/tests/random-commands.test.ts`, `library-randomy.test.ts`) pour : `random`, `getrandbits`, `randbytes`, `randint`, `randrange`, `choice`, `choices` (avec poids), `sample`, `shuffle`, `gauss`, `binomialvariate`, graines entières, négatives, très grandes et textuelles (SHA-512).

### Règles de graine
- Une valeur **entière** (`seed 42`, `seed "42"`) est lue comme l'entier Python ; tout autre texte (`seed "bonjour"`) est lu comme une chaîne Python (version 2 de `random.seed`). Les deux n'ont pas la même suite, comme en Python.
- Un nombre décimal (`seed 1.5`) est traité comme du texte (Python utiliserait `hash(1.5)`). Écart connu.
- `seed` sans valeur prend de l'entropie du système.
- Le générateur est **global** (comme l'instance cachée de `random`) : il est partagé par tous les composants d'une session d'aperçu et n'est pas enregistré dans le projet. Pour rejouer une suite plus tard, mémorisez `getstate` (avec `stocker`) puis `setstate`.

## Conventions BERKIOS
- Le **résultat** est le premier argument : `randint "$r" 1 6` au lieu de `r = random.randint(1, 6)`.
- Une **liste** s'écrit `a, b, c` (éléments séparés par des virgules) ; `choices` accepte des poids dans le même format : `choices "$r" "a, b, c" 5 "1, 2, 7"`.
- Les erreurs correspondent aux `ValueError` de Python (intervalle vide, échantillon plus grand que la population, poids invalides…) et arrêtent le script avec un message.
- **`random` est déjà une commande intégrée** de BERKIOS CODE (entier de 1 à 100). Pour le `random()` de Python, écrivez `randomy.random "$r"` ou son nom français `hasard`.

## Commandes

| Noms (python · fr · es · sw) | Syntaxe | Effet |
|---|---|---|
| `seed · graine · semilla · mbegu` | `seed ["valeur"]` | Fixe la graine : une même graine (entier ou texte) redonne la même suite de tirages, comme random.seed de Python. Sans valeur, graine du système. |
| `getstate · lire-etat · obtener-estado · pata-hali` | `getstate "Résultat"` | Écrit l'état complet du générateur (random.getstate) pour le restaurer avec setstate. |
| `setstate · fixer-etat · fijar-estado · weka-hali` | `setstate "Etat"` | Restaure un état produit par getstate (random.setstate) : les tirages suivants sont rejoués à l'identique. |
| `random · hasard · aleatorio · nasibu` | `randomy.random "Résultat"` | Nombre décimal dans [0, 1[ (random.random). « random » existe déjà dans BERKIOS CODE : écrivez randomy.random, ou utilisez hasard. |
| `getrandbits · bits-hasard · bits-aleatorios · biti-nasibu` | `getrandbits "Résultat" k` | Entier de k bits aléatoires, 1 ≤ k ≤ 8192 (random.getrandbits). |
| `randbytes · octets-hasard · bytes-aleatorios · baiti-nasibu` | `randbytes "Résultat" n` | n octets aléatoires écrits en hexadécimal (random.randbytes). |
| `randint · entier-hasard · entero-aleatorio · kamili-nasibu` | `randint "Résultat" a b` | Entier de a à b, bornes incluses (random.randint). |
| `randrange · plage-hasard · rango-aleatorio · masafa-nasibu` | `randrange "Résultat" fin  \|  "Résultat" début fin [pas]` | Entier pris dans range(début, fin, pas), fin exclue (random.randrange). |
| `randbelow · sous-hasard · menor-aleatorio · chini-nasibu` | `randbelow "Résultat" n` | Entier de 0 à n − 1 (comme secrets.randbelow, mais reproductible avec seed). |
| `choice · choix · elegir · chagua` | `choice "Résultat" "a, b, c"` | Un élément de la liste, au hasard (random.choice). |
| `choices · choix-plusieurs · elegir-varios · chagua-nyingi` | `choices "Résultat" "a, b, c" k ["poids"]` | k éléments tirés avec remise, poids facultatifs (random.choices). |
| `sample · echantillon · muestra · sampuli` | `sample "Résultat" "a, b, c" k` | k éléments distincts de la liste (random.sample). |
| `shuffle · melanger · barajar · changanya` | `shuffle "Liste"` | Mélange la liste en place (random.shuffle). |
| `uniform · uniforme · uniforme-aleatorio · sawia` | `uniform "Résultat" a b` | Nombre décimal entre a et b (random.uniform). |
| `triangular · triangulaire · triangular-aleatorio · pembetatu` | `triangular "Résultat" [bas] [haut] [mode]` | Loi triangulaire (random.triangular). |
| `gauss · gaussienne · gaussiana · gauss-nasibu` | `gauss "Résultat" [mu] [sigma]` | Loi normale par Box-Muller (random.gauss). |
| `normalvariate · loi-normale · normal-aleatoria · kawaida-nasibu` | `normalvariate "Résultat" [mu] [sigma]` | Loi normale par Kinderman-Monahan (random.normalvariate). |
| `lognormvariate · loi-lognormale · lognormal-aleatoria · lognormal-nasibu` | `lognormvariate "Résultat" mu sigma` | Loi log-normale (random.lognormvariate). |
| `expovariate · loi-exponentielle · exponencial-aleatoria · kielelezo-nasibu` | `expovariate "Résultat" [lambda]` | Loi exponentielle (random.expovariate). |
| `gammavariate · loi-gamma · gamma-aleatoria · gamma-nasibu` | `gammavariate "Résultat" alpha beta` | Loi gamma (random.gammavariate). |
| `betavariate · loi-beta · beta-aleatoria · beta-nasibu` | `betavariate "Résultat" alpha beta` | Loi bêta (random.betavariate). |
| `paretovariate · loi-pareto · pareto-aleatoria · pareto-nasibu` | `paretovariate "Résultat" alpha` | Loi de Pareto (random.paretovariate). |
| `weibullvariate · loi-weibull · weibull-aleatoria · weibull-nasibu` | `weibullvariate "Résultat" alpha beta` | Loi de Weibull (random.weibullvariate). |
| `vonmisesvariate · loi-vonmises · vonmises-aleatoria · vonmises-nasibu` | `vonmisesvariate "Résultat" mu kappa` | Loi de von Mises (random.vonmisesvariate). |
| `binomialvariate · loi-binomiale · binomial-aleatoria · binomu-nasibu` | `binomialvariate "Résultat" [n] [p]` | Nombre de succès sur n essais (random.binomialvariate, Python 3.12). |
| `token_hex · jeton-hex · token-hexadecimal · tokeni-hex` | `token_hex "Résultat" [octets]` | Jeton hexadécimal cryptographique (secrets.token_hex), non reproductible. |
| `randlist · liste-hasard · lista-aleatoria · orodha-nasibu` | `randlist "Résultat" n a b` | Liste de n entiers entre a et b : [randint(a, b) for _ in range(n)]. |
| `permutation · permuter · permutar · badilisha-mpangilio` | `permutation "Résultat" n` | Les entiers de 1 à n dans un ordre aléatoire : sample(range(1, n + 1), n). |
| `roll · lancer · lanzar · rusha` | `roll "Résultat" "2d6+3"` | Lance des dés en notation NdF±M et écrit le total. |
| `coinflip · pile-face · cara-o-cruz · sarafu` | `coinflip "Résultat"` | « pile » ou « face » : choice(["pile", "face"]). |

## Sécurité
`random` de Python n'est pas cryptographique, et Randomy non plus : **ne l'utilisez pas pour des mots de passe ni des jetons**. `token_hex` est l'exception : il appelle le générateur cryptographique du système (comme le module `secrets`), jamais la graine. Même chose pour `entier-securise`, `jeton-aleatoire` et `mot-de-passe-aleatoire` parmi les commandes intégrées.

## Limites
- Traductions espagnoles et swahilies écrites sans relecture par des locuteurs natifs : à relire avant diffusion large.
- Les dernières décimales des lois continues peuvent différer d'un ulp de CPython selon la bibliothèque mathématique de la plateforme (les tests tolèrent 1e-12).
- Ces commandes tournent dans l'**aperçu du Studio**. Le port Dart (application Flutter générée) n'est pas fait : voir `RELEASE_NOTES_v0.7.288_randomy_50_commandes_aleatoires.md`.
- `binomialvariate` suppose Python ≥ 3.12 ; `gauss` et `expovariate` suivent la version 3.12 (le paramètre `lambd` d'`expovariate` est facultatif, valeur 1).