click-extended 1.0.0__py3-none-any.whl → 1.0.2__py3-none-any.whl

click_extended/decorators/random/random_bool.py

@@ -0,0 +1,49 @@
+"""Parent node for generating a random boolean."""
+
+import random
+from typing import Any
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class RandomBool(ParentNode):
+    """Parent node for generating a random boolean."""
+
+    def load(self, context: Context, *args: Any, **kwargs: Any) -> bool:
+        if kwargs.get("seed") is not None:
+            random.seed(kwargs["seed"])
+
+        return bool(random.random() < min(1.0, max(0.0, kwargs["weight"])))
+
+
+def random_bool(
+    name: str,
+    weight: float = 0.5,
+    seed: int | None = None,
+) -> Decorator:
+    """
+    Generate a random boolean.
+
+    Type: `ParentNode`
+
+    Args:
+        name (str):
+            The name of the parent node.
+        weight (float):
+            The probability of returning `True` (0.0 to 1.0).
+            Defaults to 0.5 (50% chance). The value is clamped and will always
+            be in the range 0.0 to 1.0.
+        seed (int | None):
+            Optional seed for reproducible randomness.
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return RandomBool.as_decorator(
+        name=name,
+        weight=weight,
+        seed=seed,
+    )

click_extended/decorators/random/random_choice.py

@@ -0,0 +1,63 @@
+"""Parent node to choose a random value from an iterable."""
+
+import random
+from typing import Any, Sequence
+
+from click_extended.classes import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class RandomChoice(ParentNode):
+    """Get a random choice from an iterable."""
+
+    def load(self, context: Context, *args: Any, **kwargs: Any) -> Any:
+        if kwargs.get("seed") is not None:
+            random.seed(kwargs["seed"])
+
+        iterable: Sequence[str | int | float | bool] = kwargs.get(
+            "iterable", []
+        )
+        weights: Sequence[float] | None = kwargs.get("weights")
+
+        if weights:
+            if len(weights) != len(iterable):
+                raise ValueError(
+                    f"The length of weights ({len(weights)}) must match "
+                    f"iterable length ({len(iterable)})"
+                )
+            return random.choices(iterable, weights=weights, k=1)[0]
+        return random.choice(iterable)
+
+
+def random_choice(
+    name: str,
+    iterable: Sequence[str | int | float | bool],
+    weights: Sequence[float] | None = None,
+    seed: int | None = None,
+) -> Decorator:
+    """
+    Select a random element from an iterable with the option to add weights.
+
+    Type: `ParentNode`
+
+    Args:
+        name (str):
+            The name of the parent node.
+        iterable (Sequence[str|int|float|bool]):
+            The iterable to choose from.
+        weights (Sequence[float] | None, optional):
+            A sequence of floating point numbers representing the weights.
+        seed (int | None, None):
+            The seed to use for reproducibility.
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return RandomChoice.as_decorator(
+        name=name,
+        iterable=iterable,
+        weights=weights,
+        seed=seed,
+    )

click_extended/decorators/random/random_datetime.py

@@ -0,0 +1,140 @@
+"""Parent node for generating a random datetime."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+
+import random
+from datetime import datetime, timedelta
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class RandomDateTime(ParentNode):
+    """Parent node for generating a random datetime."""
+
+    def _parse_datetime(self, value: str | datetime) -> datetime:
+        """Parse a datetime string or return datetime as-is."""
+        if isinstance(value, datetime):
+            return value
+
+        value_lower = value.lower()
+
+        if value_lower == "now":
+            return datetime.now()
+
+        if value_lower == "today":
+            return datetime.now().replace(
+                hour=0, minute=0, second=0, microsecond=0
+            )
+
+        if value_lower == "tomorrow":
+            today = datetime.now().replace(
+                hour=0, minute=0, second=0, microsecond=0
+            )
+            return today + timedelta(days=1, hours=23, minutes=59, seconds=59)
+
+        if value_lower == "yesterday":
+            today = datetime.now().replace(
+                hour=0, minute=0, second=0, microsecond=0
+            )
+            return today - timedelta(days=1)
+
+        formats = [
+            "%Y-%m-%d %H:%M:%S",  # YYYY-MM-DD HH:MM:SS
+            "%Y-%m-%d",  # YYYY-MM-DD
+            "%H:%M:%S",  # HH:MM:SS (today's date)
+        ]
+
+        for fmt in formats:
+            try:
+                return datetime.strptime(value, fmt)
+            except ValueError:
+                continue
+
+        raise ValueError(
+            f"Unable to parse datetime '{value}'. "
+            f"Supported formats: YYYY-MM-DD HH:MM:SS, YYYY-MM-DD, HH:MM:SS, "
+            f"or special keywords: 'now', 'today', 'tomorrow'"
+        )
+
+    def load(self, context: Context, *args: Any, **kwargs: Any) -> datetime:
+        if kwargs.get("seed") is not None:
+            random.seed(kwargs["seed"])
+
+        start = self._parse_datetime(kwargs["start_date"])
+        end = self._parse_datetime(kwargs["end_date"])
+
+        if start >= end:
+            raise ValueError("start_date must be before end_date")
+
+        start_timestamp = start.timestamp()
+        end_timestamp = end.timestamp()
+        random_timestamp = random.uniform(start_timestamp, end_timestamp)
+
+        result = datetime.fromtimestamp(random_timestamp)
+
+        timezone = kwargs.get("timezone")
+        if timezone:
+            try:
+                tz = ZoneInfo(timezone)
+                result = result.replace(tzinfo=tz)
+            except Exception as e:
+                raise ValueError(f"Invalid timezone '{timezone}' ({e})") from e
+
+        return result
+
+
+def random_datetime(
+    name: str,
+    start_date: str | datetime,
+    end_date: str | datetime,
+    timezone: str | None = None,
+    seed: int | None = None,
+) -> Decorator:
+    """
+    Generate a random datetime.
+
+    Type: `ParentNode`
+
+    Args:
+        name (str):
+            The name of the parent node.
+        start_date (str | datetime):
+            The datetime to start at.
+            If a string is provided, the following formats are supported:
+                - YYYY-MM-DD HH:MM:SS
+                - YYYY-MM-DD
+                - HH:MM:SS
+                - Special keywords: 'now', 'today', 'tomorrow', 'yesterday'
+        end_date (str | datetime):
+            The datetime to end at.
+            If a string is provided, the following formats are supported:
+                - YYYY-MM-DD HH:MM:SS
+                - YYYY-MM-DD
+                - HH:MM:SS
+                - Special keywords: 'now', 'today', 'tomorrow', 'yesterday'
+        timezone (str | None, optional):
+            The timezone to use (e.g., 'UTC', 'US/Eastern', 'Europe/London').
+            If None, the datetime will be timezone-naive.
+        seed (int | None, optional):
+            Optional seed for reproducible randomness.
+
+    Returns:
+        Decorator:
+            The decorator function.
+
+    Raises:
+        ValueError:
+            If the timezone is invalid or start_date is after end_date.
+    """
+    return RandomDateTime.as_decorator(
+        name=name,
+        start_date=start_date,
+        end_date=end_date,
+        timezone=timezone,
+        seed=seed,
+    )

click_extended/decorators/random/random_float.py

@@ -0,0 +1,62 @@
+"""Parent node for generating a random floating point value."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+
+import random
+from typing import Any
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class RandomFloat(ParentNode):
+    """Parent node for generating random floating point values."""
+
+    def load(self, context: Context, *args: Any, **kwargs: Any) -> float:
+        if kwargs.get("seed") is not None:
+            random.seed(kwargs["seed"])
+
+        if kwargs["max_value"] < kwargs["min_value"]:
+            raise ValueError("min_value can not be larger than max_value.")
+
+        value = random.uniform(kwargs["min_value"], kwargs["max_value"])
+        return float(round(value, kwargs["decimals"]))
+
+
+def random_float(
+    name: str,
+    min_value: float = 0.0,
+    max_value: float = 1.0,
+    decimals: int = 3,
+    seed: int | None = None,
+) -> Decorator:
+    """
+    Generate a random floating point values.
+
+    Type: `ParentNode`
+
+    Args:
+        name (str):
+            The name of the parent node.
+        min_value (float):
+            The lower value in the range. Defaults to 0.0.
+        max_value (float):
+            The upper value in the range. Defaults to 1.0.
+        decimals (int):
+            The number of decimal places to round to. Defaults to 3.
+        seed (int | None):
+            Optional seed for reproducible randomness.
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return RandomFloat.as_decorator(
+        name=name,
+        min_value=min_value,
+        max_value=max_value,
+        decimals=decimals,
+        seed=seed,
+    )

click_extended/decorators/random/random_integer.py

@@ -0,0 +1,56 @@
+"""Parent node for generating a random integer."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+
+import random
+from typing import Any
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class RandomInteger(ParentNode):
+    """Parent node for generating random integers."""
+
+    def load(self, context: Context, *args: Any, **kwargs: Any) -> int:
+        if kwargs.get("seed") is not None:
+            random.seed(kwargs["seed"])
+
+        if kwargs["max_value"] < kwargs["min_value"]:
+            raise ValueError("min_value can not be larger than max_value.")
+        return random.randint(kwargs["min_value"], kwargs["max_value"])
+
+
+def random_integer(
+    name: str,
+    min_value: int = 0,
+    max_value: int = 100,
+    seed: int | None = None,
+) -> Decorator:
+    """
+    Generate a random integers.
+
+    Type: `ParentNode`
+
+    Args:
+        name (str):
+            The name of the parent node.
+        min_value (int):
+            The lower value in the range. Defaults to 0.
+        max_value (int):
+            The upper value in the range. Defaults to 100.
+        seed (int | None):
+            Optional seed for reproducible randomness.
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return RandomInteger.as_decorator(
+        name=name,
+        min_value=min_value,
+        max_value=max_value,
+        seed=seed,
+    )

click_extended/decorators/random/random_prime.py

@@ -0,0 +1,196 @@
+"""Parent node for generating a random prime number."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+
+import math
+import random
+from typing import Any
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class RandomPrime(ParentNode):
+    """Parent node for generating a random prime number."""
+
+    _SMALL_PRIMES = [
+        2,
+        3,
+        5,
+        7,
+        11,
+        13,
+        17,
+        19,
+        23,
+        29,
+        31,
+        37,
+        41,
+        43,
+        47,
+        53,
+        59,
+        61,
+        67,
+        71,
+        73,
+        79,
+        83,
+        89,
+        97,
+        101,
+        103,
+        107,
+        109,
+        113,
+        127,
+        131,
+        137,
+        139,
+        149,
+        151,
+        157,
+        163,
+        167,
+        173,
+        179,
+        181,
+        191,
+        193,
+        197,
+        199,
+        211,
+        223,
+        227,
+        229,
+        233,
+        239,
+        241,
+        251,
+        257,
+        263,
+        269,
+        271,
+        277,
+        281,
+        283,
+        293,
+        307,
+        311,
+        313,
+        317,
+        331,
+        337,
+        347,
+        349,
+        353,
+        359,
+        367,
+        373,
+        379,
+        383,
+        389,
+        397,
+        401,
+        409,
+        419,
+        421,
+        431,
+        433,
+        439,
+        443,
+        449,
+        457,
+        461,
+        463,
+        467,
+        479,
+        487,
+        491,
+        499,
+        503,
+        509,
+        521,
+        523,
+        541,
+    ]
+
+    def _calculate_prime(self, k: int) -> int:
+        """Calculate the k:th prime number (1-indexed)."""
+        if k <= 0:
+            raise ValueError("k must be positive")
+
+        if k <= len(self._SMALL_PRIMES):
+            return self._SMALL_PRIMES[k - 1]
+
+        # For larger k, use sieve with better upper bound estimation
+        # Using Rosser's theorem: p_n < n(ln(n) + ln(ln(n))) for n >= 6
+        if k < 6:
+            n = 30
+        else:
+            log_k = math.log(k)
+            log_log_k = math.log(log_k)
+            n = int(k * (log_k + log_log_k) * 1.3)  # 30% buffer
+
+        sieve = [True] * (n + 1)
+        sieve[0] = sieve[1] = False
+
+        for p in range(2, int(math.sqrt(n)) + 1):
+            if sieve[p]:
+                start = p * p
+                step = p if p == 2 else p * 2
+                for i in range(start, n + 1, step):
+                    sieve[i] = False
+
+        primes: list[int] = []
+        for i in range(2, n + 1):
+            if sieve[i]:
+                primes.append(i)
+                if len(primes) == k:
+                    return primes[k - 1]
+
+        raise ValueError(
+            f"Unable to calculate {k}th prime with buffer size {n}"
+        )
+
+    def load(self, context: Context, *args: Any, **kwargs: Any) -> int:
+        if kwargs.get("seed") is not None:
+            random.seed(kwargs["seed"])
+
+        k = random.randint(1, kwargs["k"])
+        return self._calculate_prime(k)
+
+
+def random_prime(
+    name: str,
+    k: int = 100,
+    seed: int | None = None,
+) -> Decorator:
+    """
+    Generate a random prime number.
+
+    Type: `ParentNode`
+
+    Args:
+        name (str):
+            The name of the parent node.
+        k (int):
+            A random prime from the first `k` primes.
+            It's important to remember that calculating large prime
+            numbers is a slow process, so try to keep the `k` value
+            small to avoid slowing down your program.
+        seed (int | None):
+            Optional seed for reproducible randomness.
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return RandomPrime.as_decorator(
+        name=name,
+        k=k,
+        seed=seed,
+    )

click_extended/decorators/random/random_string.py

@@ -0,0 +1,77 @@
+"""Parent node for generating a random string."""
+
+# pylint: disable=too-many-arguments
+# pylint: disable=too-many-positional-arguments
+
+import random
+from string import ascii_lowercase, ascii_uppercase, digits, punctuation
+from typing import Any
+
+from click_extended.core.nodes.parent_node import ParentNode
+from click_extended.core.other.context import Context
+from click_extended.types import Decorator
+
+
+class RandomString(ParentNode):
+    """Parent node for generating random strings."""
+
+    def load(self, context: Context, *args: Any, **kwargs: Any) -> str:
+        if kwargs.get("seed") is not None:
+            random.seed(kwargs["seed"])
+
+        chars = ""
+        if kwargs["lowercase"]:
+            chars += ascii_lowercase
+        if kwargs["uppercase"]:
+            chars += ascii_uppercase
+        if kwargs["numbers"]:
+            chars += digits
+        if kwargs["symbols"]:
+            chars += punctuation
+
+        return "".join(random.choice(chars) for _ in range(kwargs["length"]))
+
+
+def random_string(
+    name: str,
+    length: int = 8,
+    lowercase: bool = True,
+    uppercase: bool = True,
+    numbers: bool = True,
+    symbols: bool = True,
+    seed: int | None = None,
+) -> Decorator:
+    """
+    Generate a random string.
+
+    Type: `ParentNode`
+
+    Args:
+        name (str):
+            The name of the parent node.
+        length (int):
+            The length of the string to generate.
+        lowercase (bool):
+            Whether to include lowercase characters.
+        uppercase (bool):
+            Whether to include uppercase characters.
+        numbers (bool):
+            Whether to include numbers.
+        symbols (bool):
+            Whether to include symbols.
+        seed (int | None):
+            Optional seed for reproducible randomness.
+
+    Returns:
+        Decorator:
+            The decorator function.
+    """
+    return RandomString.as_decorator(
+        name=name,
+        length=length,
+        lowercase=lowercase,
+        uppercase=uppercase,
+        numbers=numbers,
+        symbols=symbols,
+        seed=seed,
+    )