reykit 1.0.0__py3-none-any.whl

reykit/rrandom.py

@@ -0,0 +1,351 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+@Time    : 2023-04-22 22:32:34
+@Author  : Rey
+@Contact : reyxbo@163.com
+@Explain : Random methods.
+"""
+
+
+from __future__ import annotations
+from typing import Dict, Union, Optional, Literal, Self, overload
+from types import TracebackType
+from collections.abc import Sequence
+from string import digits as string_digits, ascii_letters as string_ascii_letters, punctuation as string_punctuation
+from math import ceil as math_ceil
+from random import Random
+from secrets import randbelow as secrets_randbelow
+from threading import get_ident as threading_get_ident
+
+from .rdata import Element
+from .rexception import throw
+from .rnumber import digits
+from .rtype import RConfigMeta
+
+
+__all__ = (
+    'RConfigRandom',
+    'RRandomSeed',
+    'randn',
+    'randb',
+    'randi',
+    'randchar',
+    'randsort'
+)
+
+
+class RConfigRandom(object, metaclass=RConfigMeta):
+    """
+    Rey's `config random` type.
+    """
+
+    # RRandom.
+    _rrandom_dict: Dict[int, RRandomSeed] = {}
+
+
+class RRandomSeed(object):
+    """
+    Rey's `random seed` type.
+    To be used in syntax `with`, set random seed.
+    If set, based on `random` package.
+    If not set, based on `secrets` package.
+    """
+
+
+    def __init__(self, seed: Union[int, float, str, bytes, bytearray]) -> None:
+        """
+        Build `random` attributes.
+        """
+
+        # Build.
+        self.seed = seed
+        self.random = Random(seed)
+
+        # Record.
+        thread_id = threading_get_ident()
+        RConfigRandom._rrandom_dict[thread_id] = self
+
+
+    def __enter__(self) -> Self:
+        """
+        Enter syntax `with`.
+
+        Returns
+        -------
+        Self.
+        """
+
+        return self
+
+
+    def __exit__(
+        self,
+        exc_type: Optional[type[BaseException]],
+        exc_instance: Optional[BaseException],
+        exc_traceback: Optional[TracebackType]
+    ) -> None:
+        """
+        Exit syntax `with`.
+
+        Parameters
+        ----------
+        exc_type : Exception type.
+        exc_instance : Exception instance.
+        exc_traceback : Exception traceback instance.
+        """
+
+        # Delete.
+        thread_id = threading_get_ident()
+        del RConfigRandom._rrandom_dict[thread_id]
+
+
+@overload
+def randn(
+    *thresholds: int,
+    precision: None = None
+) -> int: ...
+
+@overload
+def randn(
+    *thresholds: float,
+    precision: None = None
+) -> float: ...
+
+@overload
+def randn(
+    *thresholds: float,
+    precision: Literal[0] = None
+) -> int: ...
+
+@overload
+def randn(
+    *thresholds: float,
+    precision: int = None
+) -> float: ...
+
+def randn(
+    *thresholds: float,
+    precision: Optional[int] = None
+) -> Union[int, float]:
+    """
+    Random number.
+
+    Parameters
+    ----------
+    thresholds : Low and high thresholds of random range, range contains thresholds.
+        - When `length is 0`, then low and high thresholds is `0` and `10`.
+        - When `length is 1`, then low and high thresholds is `0` and `thresholds[0]`.
+        - When `length is 2`, then low and high thresholds is `thresholds[0]` and `thresholds[1]`.
+    precision : Precision of random range, that is maximum decimal digits of return value.
+        - `None`: Set to Maximum decimal digits of element of parameter `thresholds`.
+        - `int`: Set to this value.
+
+    Returns
+    -------
+    Random number.
+        - When parameters `precision` is 0, then return int.
+        - When parameters `precision` is greater than 0, then return float.
+    """
+
+    # Handle parameter.
+    thresholds_len = len(thresholds)
+    match thresholds_len:
+        case 0:
+            threshold_low = 0
+            threshold_high = 10
+        case 1:
+            threshold_low = 0
+            threshold_high = thresholds[0]
+        case 2:
+            threshold_low = thresholds[0]
+            threshold_high = thresholds[1]
+        case _:
+            raise ValueError('number of parameter "thresholds" must is 0 or 1 or 2')
+    if precision is None:
+        threshold_low_desimal_digits = digits(threshold_low)[1]
+        threshold_high_desimal_digits = digits(threshold_high)[1]
+        desimal_digits_max = max(threshold_low_desimal_digits, threshold_high_desimal_digits)
+        precision = desimal_digits_max
+
+    # Get random number.
+    magnifier = 10 ** precision
+    threshold_low = int(threshold_low * magnifier)
+    threshold_high = int(threshold_high * magnifier)
+
+    ## No seed.
+    thread_id = threading_get_ident()
+    rrandom = RConfigRandom._rrandom_dict.get(thread_id)
+    if rrandom is None:
+        range_ = threshold_high - threshold_low + 1
+        number = secrets_randbelow(range_)
+        number += threshold_low
+
+    ## Seed.
+    else:
+        number = rrandom.random.randint(threshold_low, threshold_high)
+    number = number / magnifier
+
+    # Convert Integer.
+    if precision == 0:
+        number = int(number)
+
+    return number
+
+
+def randb(pr: float = 0.5) -> bool:
+    """
+    Random bool.
+
+    Parameters
+    ----------
+    pr : Probability setting.
+        - `∈(0, 1)`: Random probability, formula is `randn(1, int(1 / pr * 100)) <= 100`.
+        - `∈(1, +∞)`: Random range, formula is `randn(1, ceil(pr)) == 1`.
+
+    Returns
+    -------
+    Random bool.
+    """
+
+    # Random probability.
+    if 0 < pr < 1:
+        high = int(1 / pr * 100)
+        result = randn(1, high) <= 100
+
+    # Random range.
+    elif 1 < pr:
+        high = math_ceil(pr)
+        result = randn(1, high) == 1
+
+    # Throw exception.
+    else:
+        throw(ValueError, pr)
+
+    return result
+
+
+@overload
+def randi(
+    data: Sequence[Element],
+    multi: None = None,
+    unique: bool = True
+) -> Element: ...
+
+@overload
+def randi(
+    data: Sequence,
+    multi: int = None,
+    unique: bool = True
+) -> list[Element]: ...
+
+def randi(
+    data: Sequence,
+    multi: Optional[int] = None,
+    unique: bool = True
+) -> Union[Element, list[Element]]:
+    """
+    Random index data element.
+
+    Parameters
+    ----------
+    data : Sequence data.
+    multi : Whether index multiple data elements.
+        - `None`: Return a value.
+        - `int`: Return multiple values.
+    unique : Whether index unique, non value constraint.
+
+    Returns
+    -------
+    Element.
+    """
+
+    # Random.
+    data_len = len(data)
+    match multi:
+
+        ## One.
+        case None:
+            index = randn(data_len - 1)
+            result = data[index]
+
+        ## Multiple.
+        case _:
+            match unique:
+
+                ### Unique.
+                case True:
+
+                    #### Check.
+                    if multi > data_len:
+                        throw(IndexError, multi, data_len)
+
+                    indexes = list(range(data_len))
+                    indexes_randsort = [
+                        indexes.pop(randn(indexes_len - 1))
+                        for indexes_len in range(data_len, data_len - multi, -1)
+                    ]
+                    result = [
+                        data[index]
+                        for index in indexes_randsort
+                    ]
+
+                ### Not unique.
+                case False:
+                    rand_max = data_len - 1
+                    result = [
+                        data[randn(rand_max)]
+                        for _ in range(multi)
+                    ]
+
+    return result
+
+
+def randchar(
+    length: int,
+    punctuation: bool = True
+) -> str:
+    """
+    Generate random characters.
+
+    Parameters
+    ----------
+    length : Character length.
+    punctuation : Whether contain punctuation.
+
+    Returns
+    -------
+    Random characters.
+    """
+
+    # Get parameter.
+    char_range = string_digits + string_ascii_letters
+    if punctuation:
+        char_range += string_punctuation
+
+    # Generate.
+    char_list = randi(char_range, length, False)
+    chars = ''.join(char_list)
+
+    return chars
+
+
+def randsort(data: Sequence[Element]) -> list[Element]:
+    """
+    Random sorting data.
+
+    Parameters
+    ----------
+    data : Sequence data.
+
+    Returns
+    -------
+    Sorted data.
+    """
+
+    # Random.
+    data_len = len(data)
+    data_randsort = randi(data, data_len)
+
+    return data_randsort

reykit/rregex.py

@@ -0,0 +1,293 @@
+# !/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""
+@Time    : 2022-12-11 23:25:36
+@Author  : Rey
+@Contact : reyxbo@163.com
+@Explain : Regular expression methods.
+"""
+
+
+from typing import Optional, Union, Literal, overload
+from collections.abc import Callable
+from re import (
+    search as re_search,
+    sub as re_sub,
+    split as re_split,
+    findall as re_findall,
+    S as RS,
+    Match as RMatch
+)
+
+from .rdata import unique
+
+
+__all__ = (
+    'search',
+    'findall',
+    'sub',
+    'split',
+    'search_batch',
+    'findall_batch',
+    'sub_batch',
+    'split_batch'
+)
+
+
+def search(
+    pattern: str,
+    text: str
+) -> Optional[Union[str, tuple[Optional[str], ...]]]:
+    """
+    Regular search text.
+
+    Parameters
+    ----------
+    pattern : Regular pattern, `period match any character`.
+    text : Match text.
+
+    Returns
+    -------
+    Matching result.
+        - When match to and not use `group`, then return string.
+        - When match to and use `group`, then return tuple with value string or None.
+            If tuple length is `1`, extract and return string.
+        - When no match, then return None.
+    """
+
+    # Search.
+    obj_re = re_search(pattern, text, RS)
+
+    # Return result.
+    if obj_re is not None:
+        result = obj_re.groups()
+        if result == ():
+            result = obj_re[0]
+        elif len(result) == 1:
+            result = obj_re[1]
+
+        return result
+
+
+def findall(
+    pattern: str,
+    text: str,
+) -> Union[list[str], list[tuple[str, ...]]]:
+    """
+    Regular find all text.
+
+    Parameters
+    ----------
+    pattern : Regular pattern, `period match any character`.
+    text : Match text.
+
+    Returns
+    -------
+    Find result.
+    """
+
+    # Find all.
+    result = re_findall(pattern, text, RS)
+
+    return result
+
+
+def sub(
+    pattern: str,
+    text: str,
+    replace: Optional[Union[str, Callable[[RMatch], str]]] = None,
+    count: Optional[int] = None
+) -> str:
+    """
+    Regular replace text.
+
+    Parameters
+    ----------
+    pattern : Regular pattern, `period match any character`.
+    text : Match text.
+    replace : Replace text or handle function.
+        - `None`: Delete match part.
+    count : Replace maximum count.
+
+    Returns
+    -------
+    Replaced result.
+    """
+
+    # Handle parameter.
+    if replace is None:
+        replace = ''
+    if count is None:
+        count = 0
+
+    # Replace.
+    result = re_sub(pattern, replace, text, count, RS)
+
+    return result
+
+
+def split(
+    pattern: str,
+    text: str,
+    count: Optional[int] = None
+) -> list[str]:
+    """
+    Regular split text.
+
+    Parameters
+    ----------
+    pattern : Regular pattern, `period match any character`.
+    text : Match text.
+    count : Split maximum count.
+
+    Returns
+    -------
+    Split result.
+    """
+
+    # Handle parameter.
+    if count is None:
+        count = 0
+
+    # Replace.
+    result = re_split(pattern, text, count, RS)
+
+    return result
+
+
+@overload
+def search_batch(
+    text: str,
+    *patterns: str,
+    first: Literal[True] = True
+) -> Optional[Union[str, tuple[Optional[str], ...]]]: ...
+
+@overload
+def search_batch(
+    text: str,
+    *patterns: str,
+    first: Literal[False] = True
+) -> list[Optional[Union[str, tuple[Optional[str], ...]]]]: ...
+
+def search_batch(
+    text: str,
+    *patterns: str,
+    first: bool = True
+) -> Union[
+    Optional[Union[str, tuple[Optional[str], ...]]],
+    list[Optional[Union[str, tuple[Optional[str], ...]]]]
+]:
+    """
+    Batch regular search text.
+
+    Parameters
+    ----------
+    text : Match text.
+    pattern : Regular pattern, `period match any character`.
+    first : Whether return first successful match.
+
+    Returns
+    -------
+    Matching result.
+        - When match to and not use group, then return string.
+        - When match to and use group, then return tuple with value string or None.
+        - When no match, then return.
+    """
+
+    # Search.
+
+    ## Return first result.
+    if first:
+        for pattern in patterns:
+            result = search(pattern, text)
+            if result is not None:
+                return result
+
+    ## Return all result.
+    else:
+        result = [search(pattern, text) for pattern in patterns]
+        return result
+
+
+def findall_batch(text: str, *patterns: str) -> str:
+    """
+    Batch regular find all text.
+
+    Parameters
+    ----------
+    text : Match text.
+    patterns : Regular pattern, `period match any character`.
+
+    Returns
+    -------
+    List of Find result.
+    """
+
+    # Find all.
+    texts = [
+        string
+        for pattern in patterns
+        for string in findall(pattern, text)
+    ]
+
+    # De duplicate.
+    texts = unique(texts)
+
+    return texts
+
+
+def sub_batch(text: str, *patterns: Union[str, tuple[str, Union[str, Callable[[RMatch], str]]]]) -> str:
+    """
+    Batch regular replace text.
+
+    Parameters
+    ----------
+    text : Match text.
+    patterns : Regular pattern and replace text, `period match any character`.
+        - `str`: Regular pattern, delete match part.
+        - `tuple[str, str]`: Regular pattern and replace text.
+        - `tuple[str, Callable[[RMatch], str]]`: Regular pattern and replace handle function.
+
+    Returns
+    -------
+    Replaced result.
+    """
+
+    # Replace.
+    for pattern in patterns:
+        if pattern.__class__ == str:
+            replace = None
+        else:
+            pattern, replace = pattern
+        text = sub(pattern, text, replace)
+
+    return text
+
+
+def split_batch(text: str, *patterns: str) -> str:
+    """
+    Batch regular split text.
+
+    Parameters
+    ----------
+    text : Match text.
+    patterns : Regular pattern, `period match any character`.
+
+    Returns
+    -------
+    Split result.
+    """
+
+    # Split.
+    texts = [
+        string
+        for pattern in patterns
+        for string in split(pattern, text)
+        if string != ''
+    ]
+
+    # De duplicate.
+    texts = unique(texts)
+
+    return texts