PyCustomRand

PyCustomRand — это Python-библиотека для генерации псевдослучайных чисел, основанная на алгоритме, использующем системное время с наносекундной точностью.

Данный авторский проект создан для изучения алгоритмов и альтернативных подходов к генерации случайных чисел и их округлении. Меня не устраивало, что модуль random в Python генерирует недостаточно случайные числа ( особенно при нескольких последовательных генерациях ), а встроенный в Python модуль round довольно "грубо" округляет числа ( round(1.5) = 2 и в то же время round(2.5) = 2 ), поэтому я решил написать свою библиотеку для генерации псевдослучайных чисел — более простую и с наибольшей энтропией.

Warning

PyCustomRand не является криптографически стойкой библиотекой и не предназначена для использования в системах безопасности! Используйте secrets модуль.

📌 Зачем нужна эта библиотека, если есть уже встроенные в Python random и round?

PyCustomRand писался как альтернатива этим двум встроенным модулям. Вот главные особенности и возможности библиотеки:

• Данная библиотека проще написана — весь код закомментирован, лёгок и понятен. В основе реализации генератора псевдослучайных чисел лежит несложный алгоритм (использующий системное время) поэтому библиотеку легко кастомизировать/расширять/дополнять под себя.
• В большинстве своём PyCustomRand выдаёт более "энтропичный" результат при нескольких генерациях подряд по сравнению со встроенным random-модулем.
  • Сравнение с диаграммами

    PyCustomRand демонстрирует на 173% более высокую кучность распределения по сравнению со стандартной библиотекой random в тестах на 1,000,000 итераций.

    

    Данные для диаграммы брались из тестирования, которое проводилось с помощью встроенного модуля диагностики (check_distribution). По результатам PyCustomRand показал максимальное отклонение в 2.7 раза меньше, чем стандартный random (0.0267% против 0.0730%).

    PyCustomRand	Python Built-in

• Библиотека включает в себя все самые главные функции из оригинальной Python-библиотеки, но только местами улучшенные и упрощённые (например: random_integer может выдавать сгенерированный результат, делимый на заданное число из диапазона; результат функции random_float можно округлять и пр.)
  • Список функций

    • Генерация целых чисел (random_integer, randrange, gen_random_number).
    • Генерация вещественных чисел (random, random_float).
    • Поддержка статистических распределений: Нормальное (Гаусс), Треугольное, Экспоненциальное, Биномиальное.
    • Инструменты для последовательностей: выбор случайного элемента (choice), выборка с весами (choices), перемешивание (shuffle) и выборка уникальных элементов (sample).
    • Инициализация («посев») последовательности генератора псевдослучайных чисел (set_seed, _get_next_seed_state).
• Также библиотека имеет дополнительные утилиты, полезные для разработки веба/игр: генерация UUID v4, случайных HEX-цветов (например, #ff05a1), случайных байт, случайных булевых значений (True/False) с настраиваемым шансом.
• Имеется модуль собственного честного округления — true_round. Функция округляет числа привычным математическим способом (0.5 всегда вверх по модулю), а также исправляет погрешности плавающей точки (например, "проблему 2.675").
• Код покрыт unit-тестами (чему соответствует badge в начале README), также имеется встроенный модуль диагностики (check_distribution), который позволяет в любой момент проверить равномерность распределения генератора.

Да, у проекта всё же имеются некоторые минусы:

• Рандом, основанный на времени, всё же требует небольшого ожидания (time.sleep() на 0.1 микросекунду), соответственно, при огромнейших итерациях PyCustomRand будет уступать встроенному модулю random во времени.
• Некоторые функции библиотеки PyCustomRand (функции выборки, распределений) настолько просто написаны, что могут быть недостаточно оптимизированными для гигантских выборок (+ добавляется накапливающееся микро-ожидание из-за проблемы выше).

📦 Установка

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

pip install pycustomrand

➕ Альтернативные способы

• Клонирование репозитория:

git clone https://github.com/n1xsi/PyCustomRand.git

• Скачивание пакета напрямую в разделе Releases: https://github.com/n1xsi/PyCustomRand/releases

Пример использования

import pycustomrand as pcr 

# Генерация 8-значного случайного числа
random_number = pcr.gen_random_number(8)
print(f"Случайное число: {random_number}")

# Генерация float в диапазоне [0, 1)
random_float = pcr.random()
print(f"Случайный float: {random_float}")

# Выбор случайного элемента из списка
my_list = ['яблоко', 'банан', 'вишня']
random_choice = pcr.choice(my_list)
print(f"Случайный выбор: {random_choice}")

# Перемешивание списка
pcr.shuffle(my_list)
print(f"Перемешанный список: {my_list}")

📂 Структура репозитория

Проект имеет следующую файловую структуру:

PyCustomRand/                # Корень репозитория
├── .github/
│   └── workflows/
│       └── python-app.yml   # Конфигурация GitHub Actions: автоматический запуск тестов при каждом Push/PR
│
├── pycustomrand/            # Исходный код пакета
│   ├── __init__.py            # Точка входа: инициализация пакета и алиасы функций
│   ├── custom_round.py        # Реализация алгоритма математического округления (true_round)
│   ├── diagnostics.py         # Декоратор для проверки равномерности распределения чисел
│   └── random_generator.py    # Ядро библиотеки: класс PseudoRandom и вся логика генерации
│
├── tests/                   # Набор Unit-тестов
│   ├── __init__.py            # Пустой файл (чтобы тесты видели друг друга)
│   ├── test_random.py         # Тесты для генератора, seed, диапазонов и утилит
│   └── test_round.py          # Тесты для проверки корректности округления
│
├── .gitignore               # Правила исключения файлов из Git (venv, кэш, логи)
├── LICENSE                  # Текст лицензии MIT
├── pyproject.toml           # Конфигурационный файл сборки пакета для PyPI
└── README.md                # Документация проекта

Контрибуция

🤝 Приветствуется вклад в развитие проекта: любые поправки/импрувы.

Форк → Коммит → Pull Request