Skip to content

Commit 5b7b47f

Browse files
authored
docs: rework the first section of README + expand it with library purpose and features
Added a section explaining the purpose and advantages of the PyCustomRand library compared to built-in Python modules.
1 parent 6f5e78c commit 5b7b47f

File tree

1 file changed

+13
-11
lines changed

1 file changed

+13
-11
lines changed

README.md

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -17,17 +17,19 @@
1717
> PyCustomRand **не является** криптографически стойкой библиотекой и **не предназначена** для использования в системах безопасности!
1818
> Используйте [secrets](https://docs.python.org/3/library/secrets.html#module-secrets) модуль.
1919
20-
## ✨ Основные возможности библиотеки
21-
* 🕰 Собственная реализация генератора псевдослучайных чисел (PRNG): уникальный алгоритм, использующий системное время с точностью до наносекунд + линейный конгруэнтный метод (LCG).
22-
* 🎯 Наличие честного округления (`true_round`): функция округляет числа привычным математическим способом (0.5 всегда вверх по модулю), а также исправляет погрешности плавающей точки (например, "проблему 2.675").
23-
* 🔢 Имеется полный набор функций для работы с числами и последовательностями, основанных на [оригинальной](https://docs.python.org/3/library/random.html) Python-библиотеке:
24-
* Генерация целых чисел (`random_integer`, `randrange`, `gen_random_number`).
25-
* Генерация вещественных чисел (`random`, `random_float`).
26-
* Поддержка статистических распределений: Нормальное (Гаусс), Треугольное, Экспоненциальное, Биномиальное.
27-
* Инструменты для последовательностей: выбор случайного элемента (`choice`), выборка с весами (`choices`), перемешивание (`shuffle`) и выборка уникальных элементов (`sample`).
28-
* 🛠 Присутствуют готовые утилиты для разработчиков: генерация UUID v4, генерация случайных HEX-цветов (например, `#ff05a1`), генерация случайных байт (`random_bytes`), случайные булевы значения (`True`/`False`) с настраиваемым шансом.
29-
* 📦 Zero-Dependency: библиотека написана на чистом Python и не требует установки сторонних зависимостей. Работает везде, где есть Python.
30-
* ✅ Надёжность: код покрыт unit-тестами, а встроенный модуль диагностики (`check_distribution`) позволяет в любой момент проверить равномерность распределения генератора.
20+
## 📌 Зачем нужна эта библиотека, если есть уже встроенные в Python `random` и `round`?
21+
PyCustomRand писался как альтернатива этим двум встроенным модулям. Вот главные особенности и возможности библиотеки:
22+
23+
* Данная библиотека **проще** написана — весь код закомментирован, лёгок и понятен. В основе реализации генератора псевдослучайных чисел лежит несложный алгоритм (использующий системное время) поэтому библиотеку легко кастомизировать/расширять/дополнять под себя.
24+
* В большинстве своём PyCustomRand выдаёт более *"энтропичный"* результат.
25+
* Библиотека включает в себя все самые главные функции из [оригинальной](https://docs.python.org/3/library/random.html) Python-библиотеки, но только местами улучшенные и упрощённые (например: у `random_integer` (аналог `randint`) можно выбрать, чтобы сгенерированный результат делился на число; результат функции `random_float` можно округлять и пр.)
26+
* Также библиотека имеет дополнительные утилиты, полезные для разработки веба/игр: генерация UUID v4, случайных HEX-цветов (например, `#ff05a1`), случайных байт, случайных булевых значений (`True`/`False`) с настраиваемым шансом.
27+
* Имеется модуль собственного честного округления - `true_round`. Функция округляет числа привычным математическим способом (0.5 всегда вверх по модулю), а также исправляет погрешности плавающей точки (например, "проблему 2.675").
28+
* Код покрыт unit-тестами (чему соответствует badge в начале README), также имеется встроенный модуль диагностики (`check_distribution`), который позволяет в любой момент проверить равномерность распределения генератора.
29+
30+
Да, у проекта всё же имеются некоторые минусы:
31+
* Рандом, основанный на времени, всё же требует небольшого ожидания (`sleep(0.0000001)`), соответственно, при огромнейших циклах итераций PyCustomRand будет уступать встроенному модулю `random` во времени.
32+
* Некоторые функции настолько просто написаны (буквально "в лоб"), что неоптимизированны для гигантских выборок (+ добавляется ожидание из-за проблемы выше).
3133

3234
## 📦 Установка
3335
Установка библиотеки происходит через стандартный менеджер пакетов для Python:

0 commit comments

Comments
 (0)