absfuyu 5.1.0__py3-none-any.whl → 5.3.0__py3-none-any.whl

absfuyu/tools/generator.py

@@ -3,8 +3,8 @@ Absfuyu: Generator
 ------------------
 This generate stuff (Not python's ``generator``)
 
-Version: 5.1.0
-Date updated: 10/03/2025 (dd/mm/yyyy)
+Version: 5.2.0
+Date updated: 15/03/2025 (dd/mm/yyyy)
 
 Features:
 ---------
@@ -22,12 +22,18 @@ __all__ = ["Charset", "Generator"]
 # Library
 # ---------------------------------------------------------------------------
 import string
+from collections.abc import Collection, Sequence
 from itertools import chain, combinations
 from random import choice
+from typing import TypeVar, cast, overload
 
-from absfuyu.core import BaseClass
-from absfuyu.logger import logger
-from absfuyu.util import set_max, set_min_max
+from absfuyu.core.baseclass import ShowAllMethodsMixin
+from absfuyu.core.docstring import deprecated
+from absfuyu.util import set_min_max
+
+# Type
+# ---------------------------------------------------------------------------
+T = TypeVar("T")
 
 
 # Class
@@ -37,30 +43,43 @@ class Charset:
     Character set data class
     """
 
-    DEFAULT = string.ascii_letters + string.digits
-    ALPHABET = string.ascii_letters
-    FULL = string.ascii_letters + string.digits + string.punctuation
-    UPPERCASE = string.ascii_uppercase
-    LOWERCASE = string.ascii_lowercase
-    DIGIT = string.digits
-    SPECIAL = string.punctuation
-    ALL = string.printable
-    PRODUCT_KEY = "BCDFGHJKMNPQRTVWXY2346789"  # Charset that various key makers use
+    DEFAULT: str = string.ascii_letters + string.digits
+    ALPHABET: str = string.ascii_letters
+    FULL: str = string.ascii_letters + string.digits + string.punctuation
+    UPPERCASE: str = string.ascii_uppercase
+    LOWERCASE: str = string.ascii_lowercase
+    DIGIT: str = string.digits
+    SPECIAL: str = string.punctuation
+    ALL: str = string.printable
+    PRODUCT_KEY: str = (
+        "BCDFGHJKMNPQRTVWXY2346789"  # Charset that various key makers use
+    )
 
     def __str__(self) -> str:
         charset = [x for x in self.__class__.__dict__.keys() if not x.startswith("__")]
         return f"List of Character set: {charset}"
 
     def __repr__(self) -> str:
-        return self.__str__()
+        charset = [x for x in self.__class__.__dict__.keys() if not x.startswith("__")]
+        clsname = self.__class__.__name__
+        return f"{clsname}({', '.join(charset)})"
 
 
-class Generator(BaseClass):
+class Generator(ShowAllMethodsMixin):
     """
     Generator that generate stuffs
+
+    Features:
+    ---------
+    - Generate random string
+    - Generate key
+    - Generate check digit
+    - Generate combinations of list in range
     """
 
+    # Generate string
     @staticmethod
+    @deprecated("5.2.0", reason="Use generate_string2() instead.")
     def generate_string(
         charset: str = Charset.DEFAULT,
         size: int = 8,
@@ -69,11 +88,12 @@ class Generator(BaseClass):
         string_type_if_1: bool = False,
     ):
         """
-        Generate a list of random string from character set (Random string generator)
+        Generate a list of random string from character set (Random string generator).
+        Deprecated
 
         Parameters
         ----------
-        charset : str
+        charset : str, optional
             - Use custom character set or character sets already defined in ``Charset``
             - ``Charset.DEFAULT``: character in [a-zA-Z0-9] (default)
             - ``Charset.ALPHABET``: character in [a-zA-Z]
@@ -84,21 +104,18 @@ class Generator(BaseClass):
             - ``Charset.SPECIAL``: character in [!@#$%^&*()_+=-]
             - ``Charset.ALL``: character in every printable character
 
-        size : int
-            Length of each string in list
-            (Default: ``8``)
+        size : int, optional
+            Length of each string in list, by default ``8``
 
-        times : int
-            How many random string generated
-            (Default: ``1``)
+        times : int, optional
+            How many random string generated, by default ``1``
 
-        unique : bool
-            Each generated text is unique
-            (Default: ``False``)
+        unique : bool, optional
+            Each generated text is unique, by default ``False``
 
-        string_type_if_1 : bool
-            Return a ``str`` type result if ``times == 1``
-            (Default: ``False``)
+        string_type_if_1 : bool, optional
+            Return a ``str`` type result if ``times == 1``,
+            by default ``False``
 
         Returns
         -------
@@ -107,32 +124,18 @@ class Generator(BaseClass):
 
         str
             When ``string_type_if_1`` is ``True``
-
-        None
-            When invalid option
-
-
-        Example:
-        --------
-        >>> Generator.generate_string(times=3)
-        ['67Xfh1fv', 'iChcGz9P', 'u82fNzlm']
         """
 
         try:
             char_lst = list(charset)
         except Exception:
             char_lst = charset  # type: ignore # ! review this sometime
-        # logger.debug(char_lst)
 
         unique_string = []
         count = 0
-        logger.debug(f"Unique generated text: {unique}")
 
         while count < times:
             s = "".join(choice(char_lst) for _ in range(size))
-            logger.debug(
-                f"Time generated: {count + 1}. Remaining: {times - count - 1}. {s}"
-            )
             if not unique:
                 unique_string.append(s)
                 count += 1
@@ -141,12 +144,127 @@ class Generator(BaseClass):
                     unique_string.append(s)
                     count += 1
 
-        logger.debug(unique_string)
         if string_type_if_1 and times == 1:
             return unique_string[0]
         else:
             return unique_string
 
+    @overload
+    @staticmethod
+    def generate_string2() -> list[str]: ...
+
+    @overload
+    @staticmethod
+    def generate_string2(
+        charset: str = Charset.DEFAULT,
+        length: int = 8,
+        times: int = 1,
+        unique: bool = False,
+    ) -> list[str]: ...
+
+    @overload
+    @staticmethod
+    def generate_string2(
+        charset: Sequence[str],
+        length: int = 8,
+        times: int = 1,
+        unique: bool = False,
+    ) -> list[str]: ...
+
+    @staticmethod
+    def generate_string2(
+        charset: Sequence[str] | Charset | str = Charset.DEFAULT,
+        length: int = 8,
+        times: int = 1,
+        unique: bool = False,
+    ) -> list[str]:
+        """
+        Generate a list of random string from character set (Random string generator).
+        Improved version.
+
+        Parameters
+        ----------
+        charset : Sequence[str] | Charset | str, optional
+            - Use custom character set or character sets already defined in ``Charset``
+            - ``Charset.DEFAULT``: character in [a-zA-Z0-9] (default)
+            - ``Charset.ALPHABET``: character in [a-zA-Z]
+            - ``Charset.FULL``: character in [a-zA-Z0-9] + special characters
+            - ``Charset.UPPERCASE``: character in [A-Z]
+            - ``Charset.LOWERCASE``: character in [a-z]
+            - ``Charset.DIGIT``: character in [0-9]
+            - ``Charset.SPECIAL``: character in [!@#$%^&*()_+=-]
+            - ``Charset.ALL``: character in every printable character
+
+        length : int, optional
+            Length of each string in list, by default ``8``
+
+        times : int, optional
+            How many random string generated, by default ``1``
+
+        unique : bool, optional
+            Each generated text is unique, by default ``False``
+
+        Returns
+        -------
+        list[str]
+            List of random generated string.
+
+        Raises
+        ------
+        TypeError
+            When ``charset`` not in correct type.
+
+
+        Example:
+        --------
+        >>> Generator.generate_string2(times=3)
+        ['67Xfh1fv', 'iChcGz9P', 'u82fNzlm']
+        """
+
+        # Type check
+        if isinstance(charset, str):
+            character_list: list[str] = list(charset)
+        elif isinstance(charset, Sequence):
+            character_list = cast(list, charset)
+        else:
+            raise TypeError("Not a valid type.")
+
+        # Setup
+        generated_strings: list[str] = []
+        unique_generated_strings: set[str] = set[str]()
+        times_ = max(1, times)
+
+        while True:
+            random_string = "".join(choice(character_list) for _ in range(length))
+            if unique:
+                unique_generated_strings.add(random_string)
+            else:
+                generated_strings.append(random_string)
+
+            # Break condition
+            if (
+                len(unique_generated_strings) >= times_
+                or len(generated_strings) >= times_
+            ):
+                break
+
+        return list(unique_generated_strings) if unique else generated_strings
+
+    # Generate key
+    @overload
+    @classmethod
+    def generate_key(cls) -> str: ...
+
+    @overload
+    @classmethod
+    def generate_key(
+        cls,
+        charset: str = Charset.PRODUCT_KEY,
+        letter_per_block: int = 5,
+        number_of_block: int = 5,
+        sep: str = "-",
+    ) -> str: ...
+
     @classmethod
     def generate_key(
         cls,
@@ -156,25 +274,21 @@ class Generator(BaseClass):
         sep: str = "-",
     ) -> str:
         """
-        Generate custom key
+        Generate custom key.
 
         Parameters
         ----------
-        charset : str
-            Character set
-            (Default: ``Charset.PRODUCT_KEY``)
+        charset : Charset | str, optional
+            Character set, by default ``Charset.PRODUCT_KEY``
 
-        letter_per_block : int
-            Number of letter per key block
-            (Default: ``5``)
+        letter_per_block : int, optional
+            Number of letter per key block, by default ``5``
 
-        number_of_block : int
-            Number of key block
-            (Default: ``5``)
+        number_of_block : int, optional
+            Number of key block, by default ``5``
 
-        sep : str
-            Key block separator
-            (Default: ``-``)
+        sep : str, optional
+            Key block separator, by default ``-``
 
         Returns
         -------
@@ -188,36 +302,47 @@ class Generator(BaseClass):
         'VKKPJVYD2H-M7R687QCV2'
         """
         out = sep.join(
-            cls.generate_string(
+            cls.generate_string2(
                 charset,
-                size=letter_per_block,
+                length=letter_per_block,
                 times=number_of_block,
                 unique=False,
-                string_type_if_1=False,
             )
         )
-        logger.debug(out)
         return out
 
+    # Generate check digit
+    @overload
+    @staticmethod
+    def generate_check_digit(number: int) -> int: ...
+
+    @overload
+    @staticmethod
+    def generate_check_digit(number: list[int]) -> int: ...
+
+    @overload
     @staticmethod
-    def generate_check_digit(number: int) -> int:
+    def generate_check_digit(number: str) -> int: ...
+
+    @staticmethod
+    def generate_check_digit(number: int | list[int] | str) -> int:
         """
-        Check digit generator
-
-            "A check digit is a form of redundancy check used for
-            error detection on identification numbers, such as
-            bank account numbers, which are used in an application
-            where they will at least sometimes be input manually.
-            It is analogous to a binary parity bit used to
-            check for errors in computer-generated data.
-            It consists of one or more digits (or letters) computed
-            by an algorithm from the other digits (or letters) in the sequence input.
-            With a check digit, one can detect simple errors in
-            the input of a series of characters (usually digits)
-            such as a single mistyped digit or some permutations
-            of two successive digits." (Wikipedia)
-
-            This function use Luhn's algorithm to calculate
+        Check digit generator.
+
+        "A check digit is a form of redundancy check used for
+        error detection on identification numbers, such as
+        bank account numbers, which are used in an application
+        where they will at least sometimes be input manually.
+        It is analogous to a binary parity bit used to
+        check for errors in computer-generated data.
+        It consists of one or more digits (or letters) computed
+        by an algorithm from the other digits (or letters) in the sequence input.
+        With a check digit, one can detect simple errors in
+        the input of a series of characters (usually digits)
+        such as a single mistyped digit or some permutations
+        of two successive digits." (Wikipedia)
+
+        This function use Luhn's algorithm to calculate.
 
         Parameters
         ----------
@@ -232,55 +357,69 @@ class Generator(BaseClass):
 
         Example:
         --------
-        >>> Generator.generate_check_digit("4129984562545")
+        >>> Generator.generate_check_digit(4129984562545)
         7
         """
 
-        logger.debug(f"Base: {number}")
-        # turn into list then reverse the order
-        num = list(str(number))[::-1]
+        # Type handle
+        if isinstance(number, int):
+            # Turn into list[int] then reverse the order
+            num = [int(x) for x in list(str(number))][::-1]
+        elif isinstance(number, str):
+            num = [int(x) for x in list(number)][::-1]
+        elif isinstance(number, list):
+            num = number[::-1]
+        else:
+            raise TypeError("Variable `number` is not correct type.")
+
         sum = 0
-        logger.debug(f"Reversed: {''.join(num)}")
-        for i in range(len(num)):
-            # convert back into integer
-            num[i] = int(num[i])  # type: ignore
-            if i % 2 == 0:
+
+        # for i in range(len(num)):
+        for idx, _ in enumerate(num):
+            if idx % 2 == 0:
                 # double value of the even-th digit
-                num[i] *= 2
+                num[idx] *= 2
                 # sum the character of digit if it's >= 10
-                if num[i] >= 10:  # type: ignore
-                    num[i] -= 9  # type: ignore
-            sum += num[i]  # type: ignore
-            logger.debug(f"Loop {i + 1}: {num[i]}, {sum}")
+                if num[idx] >= 10:
+                    num[idx] -= 9
+            sum += num[idx]
 
         out = (10 - (sum % 10)) % 10
-        logger.debug(f"Output: {out}")
         return out
 
+    # Generate combinations range
+    @overload
+    @staticmethod
+    def combinations_range(collection: Collection[T]) -> list[tuple[T, ...]]: ...
+
+    @overload
+    @staticmethod
+    def combinations_range(
+        collection: Collection[T], *, min_len: int = 1, max_len: int = 0
+    ) -> list[tuple[T, ...]]: ...
+
     @staticmethod
     def combinations_range(
-        sequence: list, *, min_len: int = 1, max_len: int = 0
-    ) -> list[tuple]:
+        collection: Collection[T], *, min_len: int = 1, max_len: int = 0
+    ) -> list[tuple[T, ...]]:
         """
-        Generate all combinations of a ``sequence`` from ``min_len`` to ``max_len``
+        Generate all combinations of a ``collection`` from ``min_len`` to ``max_len``
 
         Parameters
         ----------
-        sequence : list
-            A sequence that need to generate combination
+        collection : Collection[T]
+            A collection (Iterable with ``__len__``) that need to generate combination
 
-        min_len : int
-            Minimum ``r`` of ``combinations``
-            (Default: ``1``)
+        min_len : int, optional
+            Minimum ``r`` of ``combinations``, by default ``1``
 
-        max_len : int
-            Maximum ``r`` of ``combinations``
-            (Default: ``0`` - len of ``sequence``)
+        max_len : int, optional
+            Maximum ``r`` of ``combinations``, by default ``0`` (len of ``collection``)
 
         Returns
         -------
         list[tuple]
-            A list of all combinations from range(``min_len``, ``max_len``) of ``sequence``
+            A list of all combinations from range(``min_len``, ``max_len``) of ``collection``
 
 
         Example:
@@ -289,15 +428,17 @@ class Generator(BaseClass):
         [(1, 2), (1, 3), (2, 3), (1, 2, 3)]
         """
         # Restrain
+        len_iter = len(
+            collection
+        )  # with collection.abc.Iterable, use len(list(collection))
         if max_len < 1:
-            max_len = len(sequence)
-        max_len = int(set_max(max_len, max_value=len(sequence)))
+            max_len = len_iter
+        max_len = int(min(max_len, len_iter))
         min_len = int(set_min_max(min_len, min_value=1, max_value=max_len))
-        logger.debug(f"Combination range: [{min_len}, {max_len}]")
 
         # Return
         return list(
             chain.from_iterable(
-                [list(combinations(sequence, i)) for i in range(min_len, max_len + 1)]
+                combinations(collection, i) for i in range(min_len, max_len + 1)
             )
         )