|
1 | | -<div align="center"> |
| 1 | +<h1 align="center"> |
2 | 2 |
|
3 | | - # PyCustomRand |
| 3 | + PyCustomRand |
4 | 4 |
|
5 | 5 |  |
6 | 6 | [](https://github.com/n1xsi/pycustomrand/commits/main) |
7 | 7 | [](https://github.com/n1xsi/PyCustomRand/actions/workflows/python-app.yml) |
8 | 8 |
|
9 | | -</div> |
| 9 | +</h1> |
| 10 | + |
| 11 | +<div align="center"> |
10 | 12 |
|
11 | | -🌐 **Languages:** |
| 13 | +🌐**Readme languages:** |
12 | 14 | *🇷🇺 Русский* | <a href="README.en.md">🇬🇧 English</a> |
13 | 15 |
|
| 16 | +</div> |
| 17 | + |
14 | 18 | <br> |
15 | 19 |
|
16 | | -**PyCustomRand** — это Python-библиотека для генерации **псевдослучайных чисел**, основанная на алгоритме, использующем системное время с наносекундной точностью. |
| 20 | +**PyCustomRand** — это самописная Python-библиотека для генерации **псевдослучайных чисел**, основанная на алгоритме, использующем системное время с наносекундной точностью. |
17 | 21 |
|
18 | 22 | Данный авторский проект создан для изучения алгоритмов и альтернативных подходов к генерации случайных чисел и их округлении. |
19 | | -Меня не устраивало, что модуль `random` в Python генерирует недостаточно случайные числа ( *особенно при нескольких последовательных генерациях* ), а встроенный в Python модуль `round` довольно "грубо" округляет числа ( *`round(1.5)` = 2 и в то же время `round(2.5)` = 2* ), поэтому я решил написать *свою* библиотеку для генерации псевдослучайных чисел — более простую и с наибольшей энтропией. |
| 23 | +Меня не устраивало, что модуль `random` в Python генерирует недостаточно случайные числа ( *особенно при нескольких последовательных генерациях* ), а встроенный в Python модуль `round` довольно «грубо» округляет числа ( *`round(1.5)` = 2 и в то же время `round(2.5)` = 2* ), поэтому я решил написать *свою* библиотеку — более простую, с наибольшей энтропией и математическим округлением. |
20 | 24 |
|
21 | 25 | > [!WARNING] |
22 | 26 | > PyCustomRand *пока* **не является** криптографически стойкой библиотекой и **не предназначена** для использования в системах безопасности! |
|
26 | 30 | PyCustomRand писался как альтернатива этим двум встроенным модулям. Вот главные особенности и возможности библиотеки: |
27 | 31 |
|
28 | 32 | * Данная библиотека **проще** написана — весь код закомментирован, лёгок и понятен. В основе реализации генератора псевдослучайных чисел лежит *несложный* алгоритм, использующий системное время, поэтому библиотеку легко кастомизировать, расширять или дополнять под себя. |
29 | | -* В большинстве своём PyCustomRand выдаёт более *"энтропичный"* результат при нескольких генерациях подряд по сравнению со встроенным `random`-модулем. |
| 33 | +* В большинстве своём PyCustomRand выдаёт более *«энтропичный»* результат при нескольких генерациях подряд по сравнению со встроенным `random`-модулем. |
30 | 34 | * <details> |
31 | 35 | <summary>📊 Сравнение с диаграммами</summary> |
32 | 36 | |
@@ -65,10 +69,10 @@ PyCustomRand писался как альтернатива этим двум в |
65 | 69 | * Генерация вещественных чисел (`random`, `random_float`). |
66 | 70 | * Поддержка статистических распределений: Нормальное (Гаусс), Треугольное, Экспоненциальное, Биномиальное. |
67 | 71 | * Инструменты для последовательностей: выбор случайного элемента (`choice`), выборка с весами (`choices`), перемешивание (`shuffle`) и выборка уникальных элементов (`sample`). |
68 | | - * Инициализация ("посев") последовательности генератора псевдослучайных чисел (`set_seed`, `_get_next_seed_state`). |
| 72 | + * Инициализация («посев») последовательности генератора псевдослучайных чисел (`set_seed`, `_get_next_seed_state`). |
69 | 73 | </details> |
70 | 74 | * Также библиотека имеет дополнительные утилиты, полезные для разработки веба/игр: генерация UUID v4, случайных HEX-цветов (например, `#ff05a1`), случайных байт, случайных булевых значений (`True`/`False`) с настраиваемым шансом. |
71 | | -* Имеется собственный модуль округления — `true_round`. Функция округляет числа привычным математическим способом (0.5 всегда вверх по модулю), а также исправляет погрешности плавающей точки (например, "проблему 2.675"). |
| 75 | +* Имеется собственный модуль округления — `true_round`. Функция округляет числа привычным математическим способом (0.5 всегда вверх по модулю), а также исправляет погрешности плавающей точки (например, «проблему 2.675»). |
72 | 76 | * Код покрыт unit-тестами (чему соответствует badge в начале README), также имеется встроенный модуль диагностики (`check_distribution`), который позволяет в любой момент проверить равномерность распределения генератора. |
73 | 77 |
|
74 | 78 | Да, у проекта всё же имеются некоторые минусы: |
@@ -108,7 +112,7 @@ pip install pycustomrand |
108 | 112 |
|
109 | 113 | * `set_seed(seed=None)` |
110 | 114 | Устанавливает начальное состояние генератора. |
111 | | - * `seed`: Любой объект, который преобразуется в строку — число/строка/список и др. Если `None` — "посев" сбрасывается, и используется системное время (случайная последовательность). |
| 115 | + * `seed`: Любой объект, который преобразуется в строку — число/строка/список и др. Если `None` — «посев» сбрасывается, и используется системное время (случайная последовательность). |
112 | 116 |
|
113 | 117 | * `_get_next_seed_state(current_seed)` |
114 | 118 | Внутренняя функция для обновления состояния сида (LCG алгоритм). |
@@ -299,8 +303,8 @@ print(random_bool()) # Случайное значение True/False, н |
299 | 303 |
|
300 | 304 |
|
301 | 305 | ### 🎯 О модуле `true_round` |
302 | | -Модуль решает проблему "банковского округления" в Python 3, где `round(x.5)` округляется до ближайшего чётного числа. |
303 | | -`true_round` использует **честное математическое округление** (отсюда и название "true" — истинное/честное). |
| 306 | +Модуль решает проблему «банковского округления» в Python 3, где `round(x.5)` округляется до ближайшего чётного числа. |
| 307 | +`true_round` использует **честное математическое округление** (отсюда и название «true» — истинное/честное). |
304 | 308 |
|
305 | 309 | Для удобства модуль может быть импортирован напрямую из пакета (`from pycustomrand import true_round`). |
306 | 310 |
|
@@ -366,9 +370,9 @@ if __name__ == "__main__": |
366 | 370 | Результат в консоли показывает: |
367 | 371 | * На какой сейчас итерации находится диагностика (каждые 5 секунд); |
368 | 372 | * Полное время выполнения генерации; |
369 | | -* Таблицу с количеством попаданий в каждую "корзину" (диапазон); |
| 373 | +* Таблицу с количеством попаданий в каждую «корзину» (диапазон); |
370 | 374 | * Процентное отклонение от идеального распределения; |
371 | | -* Вердикт: "Отличное равномерное распределение" или предупреждение о перекосах. |
| 375 | +* Вердикт: «Отличное равномерное распределение» или предупреждение о перекосах. |
372 | 376 |
|
373 | 377 | <details> |
374 | 378 | <summary>📊 Пример результата диагностики</summary> |
@@ -416,7 +420,7 @@ PyCustomRand/ # Корень репозитория |
416 | 420 | ```bash |
417 | 421 | python -m unittest discover tests |
418 | 422 | ``` |
419 | | -5. "Запушьте" изменения (`git push origin feature/SomeFeature`); |
| 423 | +5. «Запушьте» изменения (`git push origin feature/SomeFeature`); |
420 | 424 | 6. Откройте **Pull Request**. |
421 | 425 |
|
422 | 426 | ## 📄 Лицензия |
|
0 commit comments