PyCustomRand

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

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

Warning

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

✨ Основные возможности библиотеки

• 🕰 Собственная реализация генератора псевдослучайных чисел (PRNG): уникальный алгоритм, использующий системное время с точностью до наносекунд + линейный конгруэнтный метод (LCG).
• 🎯 Наличие честного округления (true_round): функция округляет числа привычным математическим способом (0.5 всегда вверх по модулю), а также исправляет погрешности плавающей точки (например, "проблему 2.675").
• 🔢 Имеется полный набор функций для работы с числами и последовательностями, основанных на оригинальной Python-библиотеке:
  • Генерация целых чисел (random_integer, randrange, gen_random_number).
  • Генерация вещественных чисел (random, random_float).
  • Поддержка статистических распределений: Нормальное (Гаусс), Треугольное, Экспоненциальное, Биномиальное.
  • Инструменты для последовательностей: выбор случайного элемента (choice), выборка с весами (choices), перемешивание (shuffle) и выборка уникальных элементов (sample).
• 🛠 Присутствуют готовые утилиты для разработчиков: генерация UUID v4, генерация случайных HEX-цветов (например, #ff05a1), генерация случайных байт (random_bytes), случайные булевы значения (True/False) с настраиваемым шансом.
• 📦 Zero-Dependency: библиотека написана на чистом Python и не требует установки сторонних зависимостей. Работает везде, где есть Python.
• ✅ Надёжность: код покрыт unit-тестами, а встроенный модуль диагностики (check_distribution) позволяет в любой момент проверить равномерность распределения генератора.

📦 Установка

Установка библиотеки происходит через стандартный менеджер пакетов для 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