pycustomrand 0.0.1__tar.gz

pycustomrand-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 nixsi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pycustomrand-0.0.1/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: pycustomrand
+Version: 0.0.1
+Summary: Библиотека для генерации псевдослучайных чисел на основе времени
+Author-email: Ivan <vanyalebedev45@gmail.com>
+Project-URL: Homepage, https://github.com/n1xsi/PyCustomRand
+Project-URL: Bug Tracker, https://github.com/n1xsi/PyCustomRand/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PyCustomRand
+
+[![Python](https://img.shields.io/badge/Made%20with-Python-blue.svg)](https://www.python.org/)
+[![Last Commit](https://img.shields.io/github/last-commit/n1xsi/pycustomrand.svg)](https://github.com/n1xsi/pycustomrand/commits/main)
+
+> [!WARNING]
+> *Библиотека находится на стадии разработки*.
+> 
+> Также PyCustomRand **не является** криптографически стойкой библиотекой и **не предназначена** для использования в системах безопасности ❗
+
+**PyCustomRand** — это небольшая Python-библиотека для генерации **псевдослучайных чисел**, основанная на алгоритме, использующем системное время с наносекундной точностью (time-based).
+Проект также включает в себя кастомную реализацию математического (а не банковского) округления.
+
+Это авторский проект создан для изучения алгоритмов и альтернативных подходов к генерации случайных чисел.
+Меня не устраивало, что модуль `random` в Python генерирует недостаточно случайные числа ( *особенно при нескольких последовательных генерациях* ), а встроенный в Python модуль `round` довольно "грубо" округляет числа ( *`round(1.5)` = 2 и в то же время `round(2.5)` = 2* ), поэтому я решил написать *свою* библиотеку для генерации псевдослучайных чисел — более простую и с наибольшей энтропией.
+
+## Основные возможности
+Все функции PyCustomRand основаны на [оригинальной](https://docs.python.org/3/library/random.html) Python-библиотеке:
+*   Генерация случайных целых чисел заданной длины;
+*   Генерация случайных чисел с плавающей точкой в диапазоне `[0, 1)`;
+*   Выбор случайного элемента из списка;
+*   Перемешивание списка;
+*   А также: округление кастомной функцией `true_round`.
+
+и т.д.
+
+## Установка
+*Пока что* установка через `pip` не поддерживается. Чтобы использовать библиотеку, **склонируйте** репозиторий:
+
+```bash
+git clone https://github.com/n1xsi/PyCustomRand.git
+```
+
+## Пример использования
+```python
+from pycustomrand import PseudoRandom
+
+# Генерация 8-значного случайного числа
+random_number = PseudoRandom.get_random_number(8)
+print(f"Случайное число: {random_number}")
+
+# Генерация float в диапазоне [0, 1)
+random_float = PseudoRandom.random()
+print(f"Случайный float: {random_float}")
+
+# Выбор случайного элемента из списка
+my_list = ['яблоко', 'банан', 'вишня']
+random_choice = PseudoRandom.choice(my_list)
+print(f"Случайный выбор: {random_choice}")
+
+# Перемешивание списка
+PseudoRandom.shuffle(my_list)
+print(f"Перемешанный список: {my_list}")
+```
+
+## Планы на будущее
+- [ ] Написание тестов.
+- [ ] Публикация в PyPI.
+- [ ] Доработка README.
+
+## Контрибуция
+🤝 Приветствуется вклад в развитие проекта: любые поправки/импрувы.
+
+> **Форк → Коммит → Pull Request**

pycustomrand-0.0.1/README.md

@@ -0,0 +1,64 @@
+# PyCustomRand
+
+[![Python](https://img.shields.io/badge/Made%20with-Python-blue.svg)](https://www.python.org/)
+[![Last Commit](https://img.shields.io/github/last-commit/n1xsi/pycustomrand.svg)](https://github.com/n1xsi/pycustomrand/commits/main)
+
+> [!WARNING]
+> *Библиотека находится на стадии разработки*.
+> 
+> Также PyCustomRand **не является** криптографически стойкой библиотекой и **не предназначена** для использования в системах безопасности ❗
+
+**PyCustomRand** — это небольшая Python-библиотека для генерации **псевдослучайных чисел**, основанная на алгоритме, использующем системное время с наносекундной точностью (time-based).
+Проект также включает в себя кастомную реализацию математического (а не банковского) округления.
+
+Это авторский проект создан для изучения алгоритмов и альтернативных подходов к генерации случайных чисел.
+Меня не устраивало, что модуль `random` в Python генерирует недостаточно случайные числа ( *особенно при нескольких последовательных генерациях* ), а встроенный в Python модуль `round` довольно "грубо" округляет числа ( *`round(1.5)` = 2 и в то же время `round(2.5)` = 2* ), поэтому я решил написать *свою* библиотеку для генерации псевдослучайных чисел — более простую и с наибольшей энтропией.
+
+## Основные возможности
+Все функции PyCustomRand основаны на [оригинальной](https://docs.python.org/3/library/random.html) Python-библиотеке:
+*   Генерация случайных целых чисел заданной длины;
+*   Генерация случайных чисел с плавающей точкой в диапазоне `[0, 1)`;
+*   Выбор случайного элемента из списка;
+*   Перемешивание списка;
+*   А также: округление кастомной функцией `true_round`.
+
+и т.д.
+
+## Установка
+*Пока что* установка через `pip` не поддерживается. Чтобы использовать библиотеку, **склонируйте** репозиторий:
+
+```bash
+git clone https://github.com/n1xsi/PyCustomRand.git
+```
+
+## Пример использования
+```python
+from pycustomrand import PseudoRandom
+
+# Генерация 8-значного случайного числа
+random_number = PseudoRandom.get_random_number(8)
+print(f"Случайное число: {random_number}")
+
+# Генерация float в диапазоне [0, 1)
+random_float = PseudoRandom.random()
+print(f"Случайный float: {random_float}")
+
+# Выбор случайного элемента из списка
+my_list = ['яблоко', 'банан', 'вишня']
+random_choice = PseudoRandom.choice(my_list)
+print(f"Случайный выбор: {random_choice}")
+
+# Перемешивание списка
+PseudoRandom.shuffle(my_list)
+print(f"Перемешанный список: {my_list}")
+```
+
+## Планы на будущее
+- [ ] Написание тестов.
+- [ ] Публикация в PyPI.
+- [ ] Доработка README.
+
+## Контрибуция
+🤝 Приветствуется вклад в развитие проекта: любые поправки/импрувы.
+
+> **Форк → Коммит → Pull Request**

pycustomrand-0.0.1/pycustomrand/__init__.py

@@ -0,0 +1,68 @@
+# Делает класс PseudoRandom доступным при импорте пакета
+from .random_generator import PseudoRandom
+
+# Версия пакета
+__version__ = "0.0.1"
+
+
+# -------------------- Алиасы --------------------
+
+# Основные функции
+set_seed = PseudoRandom.set_seed
+gen_random_number = PseudoRandom.gen_random_number
+random = PseudoRandom.random
+
+# Целые числа
+randrange = PseudoRandom.randrange
+random_integer = PseudoRandom.random_integer
+randint = PseudoRandom.random_integer
+
+# Числа с плавающей точкой
+random_float = PseudoRandom.random_float
+
+# Байтовые функции
+random_bytes = PseudoRandom.random_bytes
+
+# Последовательности
+choice = PseudoRandom.choice
+choices = PseudoRandom.choices
+shuffle = PseudoRandom.shuffle
+sample = PseudoRandom.sample
+
+# Распределения
+triangular = PseudoRandom.triangular
+gauss = PseudoRandom.gauss
+expovariate = PseudoRandom.expovariate
+binomial = PseudoRandom.binomialvariate
+
+# Утилиты
+random_bool = PseudoRandom.random_bool
+random_uuid4 = PseudoRandom.random_uuid4
+random_color_hex = PseudoRandom.random_color_hex
+
+# ------------------------------------------------
+
+# Для "from pycustomrand import *"
+__all__ = [
+    "PseudoRandom",
+    "true_round",
+    "random",
+    "set_seed",
+    "gen_random_number",
+    "randrange",
+    "random_integer",
+    "randint",
+    "random_float",
+    "random_bytes",
+    "choice",
+    "choices",
+    "shuffle",
+    "sample",
+    "triangular",
+    "gauss",
+    "expovariate",
+    "binomial",
+    "random_bool",
+    "random_uuid4",
+    "random_color_hex"
+]

pycustomrand-0.0.1/pycustomrand/custom_round.py

@@ -0,0 +1,45 @@
+def cascade_round(digits: list[int], index: int) -> None:
+    """Вспомогательная функция для каскадного округления цифр в списке digits, начиная с позиции index."""
+    # Если цифра на текущей позиции равна 10: устанавливаем её в 0 и увеличиваем предыдущую цифру на 1
+    if digits[index] == 10:
+        digits[index] = 0
+        if index - 1 >= 0:
+            digits[index - 1] += 1
+
+
+def true_round(number: int | float, length: int = 0) -> int | float:
+    """Функция для честного округления числа number до заданного количества знаков после запятой length."""
+    # Если пришёл int - сразу возвращаем int
+    if isinstance(number, int):
+        return number
+
+    # Получение цифр после запятой заданного числа
+    number_parts = str(number).split('.')
+    # Определение знака числа
+    sign = -1 if number_parts[0][0] == '-' else 1
+    # Создаём список цифр из числа (digits[0] - целая часть со знаком, digits[1] - дробная)
+    digits = [abs(int(number_parts[0]))] + list(map(int, number_parts[1]))
+
+    # Начало прохода: по цифрам в обратном порядке, начиная с той, что после нужного знака округления
+    start = len(digits) - 1 - (1 if length == 0 else 0)
+    # Конец прохода: до первой цифры после запятой включительно (или до конца числа, если length == 0)
+    end = length - 1 - (-2 if length == 0 else -1)
+
+    # Проход по цифрам в обратном порядке (логика округления)
+    for i in range(start, end, -1):
+        # Если цифра на текущей позиции >= 5, то +1 к предыдущей цифре (правило округления)
+        if digits[i] >= 5:
+            digits[i-1] += 1
+            digits[i] = 0
+            # Обработка каскадного округления
+            cascade_round(digits, i - 1)
+    # Доп. обработка каскадного округления после цикла (на случай, если первая цифра после запятой стала 10)
+    cascade_round(digits, 1)
+
+    # Если кол-во знаков после запятой (length) не было задано
+    if length == 0:
+        # Тогда округляем до целого числа (+1 к числу, если первая цифра после запятой >= 5)
+        return (int(digits[0]) + (1 if digits[1] >= 5 else 0)) * sign
+    else:
+        # Иначе формируем и возвращаем число с заданным кол-вом знаков после запятой
+        return float(f"{digits[0]}.{''.join(map(str, digits[1:length + 1]))}") * sign

pycustomrand-0.0.1/pycustomrand/diagnostics.py

@@ -0,0 +1,71 @@
+from collections import defaultdict
+from functools import wraps
+from time import time
+
+
+def check_distribution(count: int = 1000, buckets: int = 10):
+    """
+    Декоратор для проверки равномерности распределения генератора.
+
+    count - сколько раз запустить генератор.
+    buckets - на сколько частей разбить диапазон [0, 1).
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            print(f"===== Запуск анализа распределения ({count} итераций) =====")
+            start_time = time()
+            previous_time = start_time
+
+            # Словарь для подсчета попаданий
+            stats = defaultdict(int)
+
+            for i in range(count):
+                # Каждые 5 секунд вывод текущей итерации
+                current_time = time()
+                if current_time - previous_time > 5:
+                    print(f"Нынешняя итерация: {i}")
+                    previous_time = current_time
+
+                val = func(*args, **kwargs)
+                # Превращение числа 0.0-1.0 в номер корзины (0, 1, ..., buckets-1)
+                # int() для корзин равного размера
+                bucket_index = int(val * buckets)
+
+                # Защита от граничного случая, если выпадет ровно 1.0
+                if bucket_index == buckets:
+                    bucket_index -= 1
+
+                stats[bucket_index] += 1
+
+            elapsed = time() - start_time
+            print(f"Генерация завершена за {elapsed:.4f} сек.\n")
+
+            # Анализ результатов
+            expected_percent = 100 / buckets
+            print(f"{'Корзина':<10} | {'Кол-во':<10} | {'%':<10} | {'Отклонение':<10}")
+            print("=" * 50)
+
+            max_diff = 0
+
+            for k in sorted(stats.keys()):
+                v = stats[k]
+                percent = (v / count) * 100
+                diff = abs(percent - expected_percent)
+                if diff > max_diff:
+                    max_diff = diff
+
+                print(f"{k:<10} | {v:<10} | {percent:<10.2f}% | {diff:<10.2f}%")
+
+            print("=" * 50)
+            print(f"Максимальное отклонение: {max_diff:.4f}%")
+            if max_diff < 1.0:
+                print(">> РЕЗУЛЬТАТ: Отличное равномерное распределение!")
+            else:
+                print(">> РЕЗУЛЬТАТ: Есть перекосы (вероятно, мала выборка или проблема в алгоритме).")
+
+            # Возврат последнего сгенерированного числа, чтобы не ломать логику программы
+            return val
+
+        return wrapper
+    return decorator

pycustomrand-0.0.1/pycustomrand/random_generator.py

@@ -0,0 +1,296 @@
+from .custom_round import true_round
+from math import sqrt, log, cos, pi
+from time import sleep, time_ns
+from typing import Any
+
+
+class PseudoRandom:
+    # Переменная класса для хранения seed генератора псевдослучайных чисел
+    _seed = None
+
+    # -------------------- Основные функции генерации случайных чисел --------------------
+
+    @classmethod
+    def set_seed(cls, seed: Any = None) -> None:
+        """
+        Установка нового значения seed.
+
+        seed - любой объект, который преобразуется в строку. Если None - сброс на время (time_ns()).
+        """
+        if seed is not None:
+            cls._seed = sum(map(ord, str(seed)))
+        else:
+            cls._seed = None
+
+    @staticmethod
+    def _get_next_seed_state(current_seed: int) -> int:
+        """
+        Вспомогательная функция - меняет состояние зерна с помощью линейного конгруэнтного метода.
+        (Константы взяты из Borland C/C++ runtime library.)
+        """
+        return (current_seed * 22695477 + 1) & 0xFFFFFFFF
+
+    @classmethod
+    def gen_random_number(cls, length: int = 1) -> int:
+        """Генерация псевдослучайного числа заданной длины."""
+        number = ''
+        while len(number) != length:
+            # Определение источника энтропии (время или seed)
+            if cls._seed is not None:
+                is_seeded = True
+                current_entropy = cls._seed
+                # Обновление seed для следующей итерации (цифры), иначе результат будет одинаковым
+                cls._seed = cls._get_next_seed_state(cls._seed)
+            else:
+                is_seeded = False
+                current_entropy = time_ns()
+
+            # Генерация псевдослучайного числа на основе текущей энтропии и "волшебных" математических операций
+            calc_base = int((current_entropy * 1.71) / 0.8)
+            reversed_base = int(str(calc_base)[::-1])
+            magic_result = ((reversed_base ** 0.5) * 7) / 9
+
+            # Добавление последней цифры результата
+            number += str(int(magic_result))[-1]
+
+            # Если нет seed, нужна задержка, чтобы время изменилось (т.к. entropy - время)
+            if not is_seeded:
+                sleep(0.0001)
+
+        return int(number)
+
+    @staticmethod
+    def random() -> float:
+        """Возвращает случайное число с плавающей точкой в диапазоне [0.0, 1.0)."""
+        raw_int = PseudoRandom.gen_random_number(16)
+        raw_str = str(raw_int).zfill(16)
+        return float("0." + raw_str)
+
+    # -------------------- Числовые функции --------------------
+
+    @staticmethod
+    def randrange(start: int, stop: int = None, step: int = 1) -> int:
+        """
+        Возвращает случайное число из диапазона [start, stop).
+        Верхняя граница НЕ включается. Можно указывать один аргумент.
+
+        Примеры:
+        randrange(10) -> от 0 до 9
+        randrange(1, 10) -> от 1 до 9
+        randrange(0, 10, 2) -> чётное число от 0 до 8
+        """
+        if stop is None:
+            # Если передан один аргумент, например randrange(10), то считаем его за stop, а start за 0
+            stop = start
+            start = 0
+
+        range_object = range(start, stop, step)
+
+        if not range_object:
+            raise ValueError("Пустой диапазон для генерации")
+
+        return range_object[int(PseudoRandom.random() * len(range_object))]
+
+    @staticmethod
+    def random_integer(start: int, end: int = None, step: int = 1) -> int:
+        """
+        Возвращает случайное число из диапазона [start, end].
+        Включительны и обязательны обе границы.
+
+        step (опциональный аргумент) - число должно делиться на step (относительно start)
+        """
+        if step == 0:
+            raise ValueError("Step (шаг) не может быть равен 0")
+
+        # Длина диапазона
+        width = end - start
+
+        # Количество шагов = (разница / шаг) + 1
+        n_steps = int(width / step) + 1
+
+        if n_steps <= 0:
+            raise ValueError("Неверные границы диапазона для заданного шага")
+
+        # Выбор случайного индекса шага
+        random_step_index = int(PseudoRandom.random() * n_steps)
+
+        return start + (random_step_index * step)
+
+    # -------------------- Функции для чисел с плавающей точкой --------------------
+
+    @staticmethod
+    def random_float(start: int | float, end: int | float, digits: int = None) -> float:
+        """
+        Возвращает случайноe число с плавающей точкой из диапазона [start, end)
+        или [start, end] в зависимости от округления (при наличии digits).
+
+        start, end - могут быть как целыми числами, так и числами с плавающей точкой.
+        digits - количество знаков после запятой в возвращаемом числе. Если None - без округления.
+        """
+        result = (end-start) * (PseudoRandom.random()) + start
+        if digits is not None:
+            return true_round(result, digits)
+        return result
+
+    @staticmethod
+    def triangular(low: float = 0.0, high: float = 1.0, mode: float = None) -> float:
+        """
+        Возвращает случайное число с треугольным распределением в диапазоне [low, high].
+        Чаще всего выпадает значение около mode (вершина треугольника).
+        """
+        uniform = PseudoRandom.random()
+        cutoff = 0.5 if mode is None else (mode - low) / (high - low)
+        if uniform > cutoff:
+            uniform = 1.0 - uniform
+            cutoff = 1.0 - cutoff
+            low, high = high, low
+        return low + (high - low) * (uniform * cutoff) ** 0.5
+
+    @staticmethod
+    def gauss(mu: float = 0.0, sigma: float = 1.0) -> float:
+        """
+        Возвращает случайное число с нормальным (гауссовым) распределением.
+        Алгоритм Бокса-Мюллера.
+
+        mu - среднее значение, центр колокола (математическое ожидание).
+        sigma - стандартное отклонение, ширина колокола.
+        """
+        u1 = PseudoRandom.random()
+        u2 = PseudoRandom.random()
+        z0 = sqrt(-2.0 * log(u1)) * cos(2.0 * pi * u2)
+        return z0 * sigma + mu
+
+    @staticmethod
+    def expovariate(lambd: float = 1.0) -> float:
+        """
+        Возвращает случайное число с экспоненциальным распределением.
+
+        lambd - параметр интенсивности (должен быть не 0).
+        """
+        return -log(1 - PseudoRandom.random()) / lambd
+
+    # -------------------- Байтовые функции --------------------
+
+    @staticmethod
+    def random_bytes(count: int) -> bytes:
+        """Возвращает случайные байты в количестве count."""
+        return bytes([PseudoRandom.random_integer(0, 255) for _ in range(count)])
+
+    # -------------------- Функции для последовательностей --------------------
+
+    @staticmethod
+    def choice(array: list[Any]) -> Any:
+        """Возвращает случайно выбранный элемент из массива."""
+        if not array:
+            return None
+        index = PseudoRandom.randrange(len(array))
+        return array[index]
+
+    @staticmethod
+    def choices(array: list[Any], k: int, weights: list[int] = None) -> list[Any]:
+        """
+        Возвращает список из k случайных элементов из массива (с повторениями).
+
+        weights - список с весами для каждого элемента массива (соответствует по индексу).
+        Если None - все элементы считаются равными (по 1 весу).
+        """
+        if weights is None:
+            weights = [1] * len(array)
+
+        if len(array) != len(weights):
+            raise ValueError("Длина массива и длина weights должны быть равны")
+
+        weighted_array = []
+        for item, weight in zip(array, weights):
+            weighted_array.extend([item] * weight)
+
+        return [PseudoRandom.choice(weighted_array) for _ in range(k)]
+
+    @staticmethod
+    def shuffle(array: list[Any]) -> None:
+        """Перемешивает массив на месте."""
+        for i in range(len(array) - 1, 0, -1):
+            j = PseudoRandom.randrange(i + 1)
+            array[i], array[j] = array[j], array[i]
+
+    @staticmethod
+    def sample(array: list[Any], k: int, counts: list[int] = None) -> list[Any]:
+        """
+        Возвращает список из k уникальных случайных элементов из массива.
+
+        counts - список с количеством повторений для каждого элемента массива (соответствует по индексу).
+        Если None - все элементы считаются равными (по 1 повторению).
+        """
+        if counts is None:
+            counts = [1] * len(array)
+
+        if len(array) != len(counts):
+            raise ValueError("Длина массива и длина counts должны быть равны")
+
+        weighted_array = []
+        for item, count in zip(array, counts):
+            weighted_array.extend([item] * count)
+
+        if k > len(set(weighted_array)):
+            raise ValueError("k не может быть больше количества уникальных элементов в массиве с учётом counts")
+
+        result = []
+        while len(result) < k:
+            choice = PseudoRandom.choice(weighted_array)
+            if choice not in result:
+                result.append(choice)
+
+        return result
+
+    # -------------------- Дискретные функции --------------------
+
+    @staticmethod
+    def binomialvariate(n: int = 1, p: float = 0.5) -> int:
+        """
+        Возвращает случайное число, распределённое по биномиальному закону.
+        Простейшая реализация, неоптимизированная.
+
+        n - количество испытаний (целое число >= 0).
+        p - вероятность успеха в каждом испытании (0.0 <= p <= 1.0).
+        """
+        if n < 0:
+            raise ValueError("Количество испытаний n не может быть отрицательным")
+        if not (0.0 <= p <= 1.0):
+            raise ValueError("Вероятность p должна быть в диапазоне [0, 1]")
+
+        return sum([PseudoRandom.random() < p for _ in range(n)])
+
+    # -------------------- Вспомогательные функции --------------------
+
+    @staticmethod
+    def random_bool(true_chance: float = 0.5) -> bool:
+        """Возвращает True/False с вероятностью true_chance."""
+        return PseudoRandom.random() < true_chance
+
+    @staticmethod
+    def random_uuid4() -> str:
+        """
+        Возвращает случайный UUID версии 4
+
+        Пример: 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+        """
+        # Генерирация 32 hex-цифры
+        chars = [hex(PseudoRandom.random_integer(0, 15))[2:]
+                 for _ in range(32)]
+
+        # Согласно стандарту UUID v4:
+        chars[12] = '4'  # 13-й символ всегда '4'
+        # 17-й символ должен быть одним из '8', '9', 'a', 'b'
+        chars[16] = hex(PseudoRandom.choice([8, 9, 10, 11]))[2:]
+
+        return f"{''.join(chars[:8])}-{''.join(chars[8:12])}-{''.join(chars[12:16])}-{''.join(chars[16:20])}-{''.join(chars[20:])}"
+
+    @staticmethod
+    def random_color_hex() -> str:
+        """
+        Возвращает случайный цвет в формате hex.
+
+        Пример: '#ff0000'
+        """
+        val = PseudoRandom.random_integer(0, 0xFFFFFF)
+        return f"#{hex(val)[2:].zfill(6)}"

pycustomrand-0.0.1/pycustomrand.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: pycustomrand
+Version: 0.0.1
+Summary: Библиотека для генерации псевдослучайных чисел на основе времени
+Author-email: Ivan <vanyalebedev45@gmail.com>
+Project-URL: Homepage, https://github.com/n1xsi/PyCustomRand
+Project-URL: Bug Tracker, https://github.com/n1xsi/PyCustomRand/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# PyCustomRand
+
+[![Python](https://img.shields.io/badge/Made%20with-Python-blue.svg)](https://www.python.org/)
+[![Last Commit](https://img.shields.io/github/last-commit/n1xsi/pycustomrand.svg)](https://github.com/n1xsi/pycustomrand/commits/main)
+
+> [!WARNING]
+> *Библиотека находится на стадии разработки*.
+> 
+> Также PyCustomRand **не является** криптографически стойкой библиотекой и **не предназначена** для использования в системах безопасности ❗
+
+**PyCustomRand** — это небольшая Python-библиотека для генерации **псевдослучайных чисел**, основанная на алгоритме, использующем системное время с наносекундной точностью (time-based).
+Проект также включает в себя кастомную реализацию математического (а не банковского) округления.
+
+Это авторский проект создан для изучения алгоритмов и альтернативных подходов к генерации случайных чисел.
+Меня не устраивало, что модуль `random` в Python генерирует недостаточно случайные числа ( *особенно при нескольких последовательных генерациях* ), а встроенный в Python модуль `round` довольно "грубо" округляет числа ( *`round(1.5)` = 2 и в то же время `round(2.5)` = 2* ), поэтому я решил написать *свою* библиотеку для генерации псевдослучайных чисел — более простую и с наибольшей энтропией.
+
+## Основные возможности
+Все функции PyCustomRand основаны на [оригинальной](https://docs.python.org/3/library/random.html) Python-библиотеке:
+*   Генерация случайных целых чисел заданной длины;
+*   Генерация случайных чисел с плавающей точкой в диапазоне `[0, 1)`;
+*   Выбор случайного элемента из списка;
+*   Перемешивание списка;
+*   А также: округление кастомной функцией `true_round`.
+
+и т.д.
+
+## Установка
+*Пока что* установка через `pip` не поддерживается. Чтобы использовать библиотеку, **склонируйте** репозиторий:
+
+```bash
+git clone https://github.com/n1xsi/PyCustomRand.git
+```
+
+## Пример использования
+```python
+from pycustomrand import PseudoRandom
+
+# Генерация 8-значного случайного числа
+random_number = PseudoRandom.get_random_number(8)
+print(f"Случайное число: {random_number}")
+
+# Генерация float в диапазоне [0, 1)
+random_float = PseudoRandom.random()
+print(f"Случайный float: {random_float}")
+
+# Выбор случайного элемента из списка
+my_list = ['яблоко', 'банан', 'вишня']
+random_choice = PseudoRandom.choice(my_list)
+print(f"Случайный выбор: {random_choice}")
+
+# Перемешивание списка
+PseudoRandom.shuffle(my_list)
+print(f"Перемешанный список: {my_list}")
+```
+
+## Планы на будущее
+- [ ] Написание тестов.
+- [ ] Публикация в PyPI.
+- [ ] Доработка README.
+
+## Контрибуция
+🤝 Приветствуется вклад в развитие проекта: любые поправки/импрувы.
+
+> **Форк → Коммит → Pull Request**

pycustomrand-0.0.1/pycustomrand.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+pycustomrand/__init__.py
+pycustomrand/custom_round.py
+pycustomrand/diagnostics.py
+pycustomrand/random_generator.py
+pycustomrand.egg-info/PKG-INFO
+pycustomrand.egg-info/SOURCES.txt
+pycustomrand.egg-info/dependency_links.txt
+pycustomrand.egg-info/top_level.txt
+tests/test_random.py
+tests/test_round.py

pycustomrand-0.0.1/pycustomrand.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pycustomrand-0.0.1/pycustomrand.egg-info/top_level.txt

@@ -0,0 +1 @@
+pycustomrand

pycustomrand-0.0.1/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pycustomrand"
+version = "0.0.1"
+authors = [
+  { name="Ivan", email="vanyalebedev45@gmail.com" },
+]
+description = "Библиотека для генерации псевдослучайных чисел на основе времени"
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/n1xsi/PyCustomRand"
+"Bug Tracker" = "https://github.com/n1xsi/PyCustomRand/issues"

pycustomrand-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pycustomrand-0.0.1/tests/test_random.py

@@ -0,0 +1,68 @@
+from pycustomrand.random_generator import PseudoRandom
+import unittest
+
+
+class TestPseudoRandom(unittest.TestCase):
+
+    def setUp(self):
+        """Выполняется перед каждым тестом"""
+        # Сброс сида перед каждым тестом (для чистоты)
+        PseudoRandom.set_seed(None)
+
+    def test_reproducibility_with_seed(self):
+        """Главный тест: проверка работы Seed"""
+        seed_value = "TestSeed123"
+
+        # Запуск 1
+        PseudoRandom.set_seed(seed_value)
+        val1 = PseudoRandom.random()
+        val2 = PseudoRandom.random_integer(0, 100)
+
+        # Запуск 2 (с тем же сидом)
+        PseudoRandom.set_seed(seed_value)
+        val1_again = PseudoRandom.random()
+        val2_again = PseudoRandom.random_integer(0, 100)
+
+        self.assertEqual(val1, val1_again, "Seed не работает: float значения разные")
+        self.assertEqual(val2, val2_again, "Seed не работает: integer значения разные")
+
+    def test_randrange_bounds(self):
+        """Проверка границ randrange"""
+        for _ in range(100):
+            val = PseudoRandom.randrange(0, 5)
+            self.assertGreaterEqual(val, 0)
+            self.assertLess(val, 5)  # Строго меньше 5
+
+    def test_random_integer_bounds(self):
+        """Проверка границ random_integer (включительно)"""
+        found_max = False
+        for _ in range(200):
+            val = PseudoRandom.random_integer(1, 3)
+            self.assertGreaterEqual(val, 1)
+            self.assertLessEqual(val, 3)
+            if val == 3:
+                found_max = True
+        # Надежда на то, что за 200 попыток хоть раз выпадет 3 (верхняя граница)
+        self.assertTrue(found_max, "Верхняя граница random_integer не достигается")
+
+    def test_choice_error(self):
+        """Проверка, что пустой массив возвращает None"""
+        self.assertIsNone(PseudoRandom.choice([]))
+
+    def test_random_bytes_length(self):
+        """Проверка длины байтов"""
+        b = PseudoRandom.random_bytes(10)
+        self.assertEqual(len(b), 10)
+        self.assertIsInstance(b, bytes)
+
+    def test_uuid4_format(self):
+        """Проверка формата UUID (если ты добавил эту функцию)"""
+        if hasattr(PseudoRandom, 'uuid4'):
+            uuid = PseudoRandom.uuid4()
+            self.assertEqual(len(uuid), 36)
+            self.assertEqual(uuid[14], '4')  # Версия UUID всегда 4
+            self.assertIn(uuid[19], ['8', '9', 'a', 'b'])  # Вариант UUID
+
+
+if __name__ == '__main__':
+    unittest.main()

pycustomrand-0.0.1/tests/test_round.py

@@ -0,0 +1,107 @@
+from pycustomrand.custom_round import true_round
+import unittest
+
+
+class TestTrueRound(unittest.TestCase):
+
+    # -------------------- Базовые тесты --------------------
+
+    def test_integers(self):
+        """Проверка: целые числа не должны меняться."""
+        self.assertEqual(true_round(5), 5)
+        self.assertEqual(true_round(0), 0)
+        self.assertEqual(true_round(100), 100)
+
+    def test_basic_rounding_down(self):
+        """Проверка: округление вниз."""
+        self.assertEqual(true_round(1.1), 1)
+        self.assertEqual(true_round(1.4), 1)
+        self.assertEqual(true_round(1.4999), 2)
+
+    def test_basic_rounding_up(self):
+        """Проверка: округление вверх (числа > 0.5)."""
+        self.assertEqual(true_round(1.6), 2)
+        self.assertEqual(true_round(1.9), 2)
+        self.assertEqual(true_round(0.99), 1)
+
+    def test_rounding_half_up(self):
+        """
+        ГЛАВНАЯ ПРОВЕРКА: Округление 0.5
+        В стандартном Python round(2.5) == 2 (банковское округление).
+        Функция true_round должна давать 3 (математическое округление).
+        """
+        self.assertEqual(true_round(0.5), 1)
+        self.assertEqual(true_round(1.5), 2)
+        self.assertEqual(true_round(2.5), 3)
+        self.assertEqual(true_round(3.5), 4)
+
+    def test_precision_1_digit(self):
+        """Проверка: округление до 1 знака"""
+        self.assertEqual(true_round(0.14, 1), 0.1)
+        self.assertEqual(true_round(0.15, 1), 0.2)
+        self.assertEqual(true_round(0.16, 1), 0.2)
+
+    def test_precision_cascade(self):
+        """
+        Проверка каскадного округления.
+        Пример: 1.99 при округлении до 1 знака должно стать 2.0
+        """
+        self.assertEqual(true_round(1.99, 1), 2.0)
+        self.assertEqual(true_round(9.99, 1), 10.0)
+
+        # Проверка сложного случая: 0.445 -> 0.45 -> 0.5 (при округлении до 1 знака)
+        self.assertEqual(true_round(0.445, 1), 0.5)
+
+    # -------------------- Продвинутые тесты --------------------
+
+    def test_float_representation_fix(self):
+        """
+        Тест на 'проблему 2.675'.
+        Стандартный round(2.675, 2) дает 2.67.
+        Математическое округление должно давать 2.68.
+        """
+        self.assertEqual(true_round(2.675, 2), 2.68)
+        self.assertEqual(true_round(1.005, 2), 1.01)
+
+    def test_heavy_cascade(self):
+        """
+        Тест 'Эффект Домино'.
+        9.999 при округлении до 2 знаков должно стать 10.0
+        """
+        # 9.999 -> 9.9(9+1) -> 9.(9+1)0 -> (9+1).00 -> 10.0
+        self.assertEqual(true_round(9.999, 2), 10.0)
+
+        # 89.999 -> 90.0
+        self.assertEqual(true_round(89.999, 2), 90.0)
+
+    def test_small_numbers(self):
+        """Работа с очень маленькими числами."""
+        # 0.0005 -> округляем до 3 знаков -> 0.001
+        self.assertEqual(true_round(0.0005, 3), 0.001)
+
+        # 0.0004 -> округляем до 3 знаков -> 0.0
+        self.assertEqual(true_round(0.0004, 3), 0.0)
+
+    def test_rounding_to_zero_length(self):
+        """
+        Явное указание length=0.
+        Должно работать так же, как без указания length.
+        """
+        self.assertEqual(true_round(5.6, 0), 6)
+        self.assertIsInstance(true_round(5.6, 0), int)
+
+    def test_negative_numbers(self):
+        """
+        Отрицательные числа.
+        Математически: -1.5 округляется до -2 (по модулю).
+        """
+        self.assertEqual(true_round(-1.5), -2)
+        self.assertEqual(true_round(-1.1), -1)
+
+
+if __name__ == '__main__':
+    # Запуск конкретного теста:
+    # unittest.main(defaultTest='TestTrueRound.test_negative_numbers')
+
+    # Запуск всех тестов:
+    unittest.main()