xulbux 1.9.5__cp311-cp311-macosx_11_0_arm64.whl

xulbux/json.py

@@ -0,0 +1,200 @@
+"""
+This module provides the `Json` class, which includes methods to read,
+create and update JSON files, with support for comments inside the JSON data.
+"""
+
+from .file_sys import FileSys
+from .data import Data
+from .file import File
+
+from typing import Literal, Any, cast
+from pathlib import Path
+import json as _json
+
+
+class Json:
+    """This class provides methods to read, create and update JSON files,
+    with support for comments inside the JSON data."""
+
+    @classmethod
+    def read(
+        cls,
+        json_file: Path | str,
+        comment_start: str = ">>",
+        comment_end: str = "<<",
+        return_original: bool = False,
+    ) -> dict | tuple[dict, dict]:
+        """Read JSON files, ignoring comments.\n
+        ------------------------------------------------------------------------------------
+        - `json_file` -⠀the path (relative or absolute) to the JSON file to read
+        - `comment_start` -⠀the string that indicates the start of a comment
+        - `comment_end` -⠀the string that indicates the end of a comment
+        - `return_original` -⠀if true, the original JSON data is returned additionally:<br>
+          ```python
+        (processed_json, original_json)
+          ```\n
+        ------------------------------------------------------------------------------------
+        For more detailed information about the comment handling,
+        see the `Data.remove_comments()` method documentation."""
+        if (json_path := Path(json_file) if isinstance(json_file, str) else json_file).suffix != ".json":
+            json_path = json_path.with_suffix(".json")
+        file_path = FileSys.extend_or_make_path(json_path, prefer_script_dir=True)
+
+        with open(file_path, "r") as file:
+            content = file.read()
+
+        try:
+            data = _json.loads(content)
+        except _json.JSONDecodeError as e:
+            fmt_error = "\n  ".join(str(e).splitlines())
+            raise ValueError(f"Error parsing JSON in {file_path!r}:\n  {fmt_error}") from e
+
+        if not (processed_data := dict(Data.remove_comments(data, comment_start, comment_end))):
+            raise ValueError(f"The JSON file {file_path!r} is empty or contains only comments.")
+
+        return (processed_data, data) if return_original else processed_data
+
+    @classmethod
+    def create(
+        cls,
+        json_file: Path | str,
+        data: dict,
+        indent: int = 2,
+        compactness: Literal[0, 1, 2] = 1,
+        force: bool = False,
+    ) -> Path:
+        """Create a nicely formatted JSON file from a dictionary.\n
+        ---------------------------------------------------------------------------
+        - `json_file` -⠀the path (relative or absolute) to the JSON file to create
+        - `data` -⠀the dictionary data to write to the JSON file
+        - `indent` -⠀the amount of spaces to use for indentation
+        - `compactness` -⠀can be `0`, `1` or `2` and indicates how compact
+          the data should be formatted (see `Data.render()` for more info)
+        - `force` -⠀if true, will overwrite existing files
+          without throwing an error (errors explained below)\n
+        ---------------------------------------------------------------------------
+        The method will throw a `FileExistsError` if a file with the same
+        name already exists and a `SameContentFileExistsError` if a file
+        with the same name and same content already exists."""
+        if (json_path := Path(json_file) if isinstance(json_file, str) else json_file).suffix != ".json":
+            json_path = json_path.with_suffix(".json")
+
+        file_path = FileSys.extend_or_make_path(json_path, prefer_script_dir=True)
+        File.create(
+            file_path=file_path,
+            content=Data.render(
+                data=data,
+                indent=indent,
+                compactness=compactness,
+                as_json=True,
+                syntax_highlighting=False,
+            ),
+            force=force,
+        )
+
+        return file_path
+
+    @classmethod
+    def update(
+        cls,
+        json_file: Path | str,
+        update_values: dict[str, Any],
+        comment_start: str = ">>",
+        comment_end: str = "<<",
+        path_sep: str = "->",
+    ) -> None:
+        """Update single/multiple values inside JSON files,
+        without needing to know the rest of the data.\n
+        -----------------------------------------------------------------------------------
+        - `json_file` -⠀the path (relative or absolute) to the JSON file to update
+        - `update_values` -⠀a dictionary with the paths to the values to update
+          and the new values to set (see explanation below – section 2)
+        - `comment_start` -⠀the string that indicates the start of a comment
+        - `comment_end` -⠀the string that indicates the end of a comment
+        - `path_sep` -⠀the separator used inside the value-paths in `update_values`\n
+        -----------------------------------------------------------------------------------
+        For more detailed information about the comment handling,
+        see the `Data.remove_comments()` method documentation.\n
+        -----------------------------------------------------------------------------------
+        The `update_values` is a dictionary, where the keys are the paths
+        to the data to update, and the values are the new values to set.\n
+        For example for this JSON data:
+        ```python
+        {
+            "healthy": {
+                "fruits": ["apples", "bananas", "oranges"],
+                "vegetables": ["carrots", "broccoli", "celery"]
+            }
+        }
+        ```
+        … the `update_values` dictionary could look like this:
+        ```python
+        {
+            # CHANGE FIRST LIST-VALUE UNDER 'fruits' TO "strawberries"
+            "healthy->fruits->0": "strawberries",
+            # CHANGE VALUE OF KEY 'vegetables' TO [1, 2, 3]
+            "healthy->vegetables": [1, 2, 3]
+        }
+        ```
+        In this example, if you want to change the value of `"apples"`,
+        you can use `healthy->fruits->apples` as the value-path.<br>
+        If you don't know that the first list item is `"apples"`,
+        you can use the items list index inside the value-path, so `healthy->fruits->0`.\n
+        ⇾ If the given value-path doesn't exist, it will be created."""
+        processed_data, data = cls.read(
+            json_file=json_file,
+            comment_start=comment_start,
+            comment_end=comment_end,
+            return_original=True,
+        )
+
+        update: dict[str, Any] = {}
+        for val_path, new_val in update_values.items():
+            try:
+                if (path_id := Data.get_path_id(data=processed_data, value_paths=val_path, path_sep=path_sep)) is not None:
+                    update[cast(str, path_id)] = new_val
+                else:
+                    data = cls._create_nested_path(data, val_path.split(path_sep), new_val)
+            except Exception:
+                data = cls._create_nested_path(data, val_path.split(path_sep), new_val)
+
+        if update:
+            data = Data.set_value_by_path_id(data, update)
+
+        cls.create(json_file=json_file, data=dict(data), force=True)
+
+    @staticmethod
+    def _create_nested_path(data_obj: dict, path_keys: list[str], value: Any) -> dict:
+        """Internal method that creates nested dictionaries/lists based on the
+        given path keys and sets the specified value at the end of the path."""
+        last_idx, current = len(path_keys) - 1, data_obj
+
+        for i, key in enumerate(path_keys):
+            if i == last_idx:
+                if isinstance(current, dict):
+                    current[key] = value
+                elif isinstance(current, list) and key.isdigit():
+                    idx = int(key)
+                    while len(current) <= idx:
+                        current.append(None)
+                    current[idx] = value
+                else:
+                    raise TypeError(f"Cannot set key '{key}' on {type(current)}")
+
+            else:
+                next_key = path_keys[i + 1]
+                if isinstance(current, dict):
+                    if key not in current:
+                        current[key] = [] if next_key.isdigit() else {}
+                    current = current[key]
+                elif isinstance(current, list) and key.isdigit():
+                    idx = int(key)
+                    while len(current) <= idx:
+                        current.append(None)
+                    if current[idx] is None:
+                        current[idx] = [] if next_key.isdigit() else {}
+                    current = current[idx]
+                else:
+                    raise TypeError(f"Cannot navigate through {type(current)}")
+
+        return data_obj

xulbux/regex.py

@@ -0,0 +1,247 @@
+"""
+This module provides the `Regex` class, which includes methods
+to dynamically generate complex regex patterns for common use cases.
+"""
+
+from .base.decorators import mypyc_attr
+
+from typing import Optional
+import regex as _rx
+import re as _re
+
+
+class Regex:
+    """This class provides methods to dynamically generate complex regex patterns for common use cases."""
+
+    @classmethod
+    def quotes(cls) -> str:
+        """Matches pairs of quotes. (strings)\n
+        --------------------------------------------------------------------------------
+        Will create two named groups:
+        - `quote` the quote type (single or double)
+        - `string` everything inside the found quote pair\n
+        ---------------------------------------------------------------------------------
+        Attention: Requires non-standard library `regex`, not standard library `re`!"""
+        return r"""(?P<quote>["'])(?P<string>(?:\\.|(?!\g<quote>).)*?)\g<quote>"""
+
+    @classmethod
+    def brackets(
+        cls,
+        bracket1: str = "(",
+        bracket2: str = ")",
+        is_group: bool = False,
+        strip_spaces: bool = False,
+        ignore_in_strings: bool = True,
+    ) -> str:
+        """Matches everything inside pairs of brackets, including other nested brackets.\n
+        ---------------------------------------------------------------------------------------
+        - `bracket1` -⠀the opening bracket (e.g. `(`, `{`, `[`, …)
+        - `bracket2` -⠀the closing bracket (e.g. `)`, `}`, `]`, …)
+        - `is_group` -⠀whether to create a capturing group for the content inside the brackets
+        - `strip_spaces` -⠀whether to strip spaces from the bracket content or not
+        - `ignore_in_strings` -⠀whether to ignore closing brackets that are inside
+          strings/quotes (e.g. `'…)…'` or `"…)…"`)\n
+        ---------------------------------------------------------------------------------------
+        Attention: Requires non-standard library `regex`, not standard library `re`!"""
+        g = "" if is_group else "?:"
+        b1 = _rx.escape(bracket1) if len(bracket1) == 1 else bracket1
+        b2 = _rx.escape(bracket2) if len(bracket2) == 1 else bracket2
+        s1 = r"\s*" if strip_spaces else ""
+        s2 = "" if strip_spaces else r"\s*"
+
+        if ignore_in_strings:
+            return cls._clean( \
+                rf"""{b1}{s1}({g}{s2}(?:
+                    [^{b1}{b2}"']
+                    |"(?:\\.|[^"\\])*"
+                    |'(?:\\.|[^'\\])*'
+                    |{b1}(?:
+                        [^{b1}{b2}"']
+                        |"(?:\\.|[^"\\])*"
+                        |'(?:\\.|[^'\\])*'
+                        |(?R)
+                    )*{b2}
+                )*{s2}){s1}{b2}"""
+            )
+        else:
+            return cls._clean( \
+                rf"""{b1}{s1}({g}{s2}(?:
+                    [^{b1}{b2}]
+                    |{b1}(?:
+                        [^{b1}{b2}]
+                        |(?R)
+                    )*{b2}
+                )*{s2}){s1}{b2}"""
+            )
+
+    @classmethod
+    def outside_strings(cls, pattern: str = r".*") -> str:
+        """Matches the `pattern` only when it is not found inside a string (`'…'` or `"…"`)."""
+        return rf"""(?<!["'])(?:{pattern})(?!["'])"""
+
+    @classmethod
+    def all_except(cls, disallowed_pattern: str, ignore_pattern: str = "", is_group: bool = False) -> str:
+        """Matches everything up to the `disallowed_pattern`, unless the
+        `disallowed_pattern` is found inside a string/quotes (`'…'` or `"…"`).\n
+        -------------------------------------------------------------------------------------
+        - `disallowed_pattern` -⠀the pattern that is not allowed to be matched
+        - `ignore_pattern` -⠀a pattern that, if found, will make the regex ignore the
+          `disallowed_pattern` (even if it contains the `disallowed_pattern` inside it):<br>
+          For example if `disallowed_pattern` is `>` and `ignore_pattern` is `->`,
+          the `->`-arrows will be allowed, even though they have `>` in them.
+        - `is_group` -⠀whether to create a capturing group for the matched content"""
+        g = "" if is_group else "?:"
+
+        return cls._clean( \
+            rf"""({g}
+                (?:(?!{ignore_pattern}).)*
+                (?:(?!{cls.outside_strings(disallowed_pattern)}).)*
+            )"""
+        )
+
+    @classmethod
+    def func_call(cls, func_name: Optional[str] = None) -> str:
+        """Match a function call, and get back two groups:
+        1. function name
+        2. the function's arguments\n
+        If no `func_name` is given, it will match any function call.\n
+        ---------------------------------------------------------------------------------
+        Attention: Requires non-standard library `regex`, not standard library `re`!"""
+        if func_name in {"", None}:
+            func_name = r"[\w_]+"
+
+        return rf"""(?<=\b)({func_name})\s*{cls.brackets("(", ")", is_group=True)}"""
+
+    @classmethod
+    def rgba_str(cls, fix_sep: Optional[str] = ",", allow_alpha: bool = True) -> str:
+        """Matches an RGBA color inside a string.\n
+        ----------------------------------------------------------------------------------
+        - `fix_sep` -⠀the fixed separator between the RGBA values (e.g. `,`, `;` …)<br>
+          If set to nothing or `None`, any char that is not a letter or number
+          can be used to separate the RGBA values, including just a space.
+        - `allow_alpha` -⠀whether to include the alpha channel in the match\n
+        ----------------------------------------------------------------------------------
+        The RGBA color can be in the formats (for `fix_sep = ','`):
+        - `rgba(r, g, b)`
+        - `rgba(r, g, b, a)` (if `allow_alpha=True`)
+        - `(r, g, b)`
+        - `(r, g, b, a)` (if `allow_alpha=True`)
+        - `r, g, b`
+        - `r, g, b, a` (if `allow_alpha=True`)\n
+        #### Valid ranges:
+        - `r` 0-255 (int: red)
+        - `g` 0-255 (int: green)
+        - `b` 0-255 (int: blue)
+        - `a` 0.0-1.0 (float: opacity)"""
+        fix_sep = _re.escape(fix_sep) if isinstance(fix_sep, str) else r"[^0-9A-Z]"
+
+        rgb_part = rf"""((?:0*(?:25[0-5]|2[0-4][0-9]|1?[0-9]{{1,2}})))
+            (?:\s*{fix_sep}\s*)((?:0*(?:25[0-5]|2[0-4][0-9]|1?[0-9]{{1,2}})))
+            (?:\s*{fix_sep}\s*)((?:0*(?:25[0-5]|2[0-4][0-9]|1?[0-9]{{1,2}})))"""
+
+        if allow_alpha:
+            return cls._clean( \
+                rf"""(?ix)(?:rgb|rgba)?\s*(?:
+                    \(?\s*{rgb_part}
+                        (?:(?:\s*{fix_sep}\s*)((?:0*(?:0?\.[0-9]+|1\.0+|[0-9]+\.[0-9]+|[0-9]+))))?
+                    \s*\)?
+                )"""
+            )
+        else:
+            return cls._clean( \
+                rf"""(?ix)(?:rgb|rgba)?\s*(?:
+                    \(?\s*{rgb_part}\s*\)?
+                )"""
+            )
+
+    @classmethod
+    def hsla_str(cls, fix_sep: Optional[str] = ",", allow_alpha: bool = True) -> str:
+        """Matches a HSLA color inside a string.\n
+        ----------------------------------------------------------------------------------
+        - `fix_sep` -⠀the fixed separator between the HSLA values (e.g. `,`, `;` …)<br>
+          If set to nothing or `None`, any char that is not a letter or number
+          can be used to separate the HSLA values, including just a space.
+        - `allow_alpha` -⠀whether to include the alpha channel in the match\n
+        ----------------------------------------------------------------------------------
+        The HSLA color can be in the formats (for `fix_sep = ','`):
+        - `hsla(h, s, l)`
+        - `hsla(h, s, l, a)` (if `allow_alpha=True`)
+        - `(h, s, l)`
+        - `(h, s, l, a)` (if `allow_alpha=True`)
+        - `h, s, l`
+        - `h, s, l, a` (if `allow_alpha=True`)\n
+        #### Valid ranges:
+        - `h` 0-360 (int: hue)
+        - `s` 0-100 (int: saturation)
+        - `l` 0-100 (int: lightness)
+        - `a` 0.0-1.0 (float: opacity)"""
+        fix_sep = _re.escape(fix_sep) if isinstance(fix_sep, str) else r"[^0-9A-Z]"
+
+        hsl_part = rf"""((?:0*(?:360|3[0-5][0-9]|[12][0-9][0-9]|[1-9]?[0-9])))(?:\s*°)?
+            (?:\s*{fix_sep}\s*)((?:0*(?:100|[1-9][0-9]|[0-9])))(?:\s*%)?
+            (?:\s*{fix_sep}\s*)((?:0*(?:100|[1-9][0-9]|[0-9])))(?:\s*%)?"""
+
+        if allow_alpha:
+            return cls._clean( \
+                rf"""(?ix)(?:hsl|hsla)?\s*(?:
+                    \(?\s*{hsl_part}
+                        (?:(?:\s*{fix_sep}\s*)((?:0*(?:0?\.[0-9]+|1\.0+|[0-9]+\.[0-9]+|[0-9]+))))?
+                    \s*\)?
+                )"""
+            )
+        else:
+            return cls._clean( \
+                rf"""(?ix)(?:hsl|hsla)?\s*(?:
+                    \(?\s*{hsl_part}\s*\)?
+                )"""
+            )
+
+    @classmethod
+    def hexa_str(cls, allow_alpha: bool = True) -> str:
+        """Matches a HEXA color inside a string.\n
+        ----------------------------------------------------------------------
+        - `allow_alpha` -⠀whether to include the alpha channel in the match\n
+        ----------------------------------------------------------------------
+        The HEXA color can be in the formats (prefix `#`, `0x` or no prefix):
+        - `RGB`
+        - `RGBA` (if `allow_alpha=True`)
+        - `RRGGBB`
+        - `RRGGBBAA` (if `allow_alpha=True`)\n
+        #### Valid ranges:
+        every channel from 0-9 and A-F (case insensitive)"""
+        return r"(?i)(?:#|0x)?([0-9A-F]{8}|[0-9A-F]{6}|[0-9A-F]{4}|[0-9A-F]{3})" \
+            if allow_alpha else r"(?i)(?:#|0x)?([0-9A-F]{6}|[0-9A-F]{3})"
+
+    @classmethod
+    def _clean(cls, pattern: str) -> str:
+        """Internal method to make a multiline-string regex pattern into a single-line pattern."""
+        return "".join(line.strip() for line in pattern.splitlines()).strip()
+
+
+@mypyc_attr(native_class=False)
+class LazyRegex:
+    """A class that lazily compiles and caches regex patterns on first access.\n
+    --------------------------------------------------------------------------------
+    - `**patterns` -⠀keyword arguments where the key is the name of the pattern and
+      the value is the regex pattern string to compile\n
+    --------------------------------------------------------------------------------
+    #### Example usage:
+    ```python
+    PATTERNS = LazyRegex(
+        email=r"(?i)[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}",
+        phone=r"\\+?\\d{1,3}[-.\\s]?\\(?\\d{1,4}\\)?[-.\\s]?\\d{1,4}[-.\\s]?\\d{1,9}",
+    )
+
+    email_pattern = PATTERNS.email  # Compiles and caches the EMAIL pattern
+    phone_pattern = PATTERNS.phone  # Compiles and caches the PHONE pattern
+    ```"""
+
+    def __init__(self, **patterns: str):
+        self._patterns = patterns
+
+    def __getattr__(self, name: str) -> _rx.Pattern:
+        if name in self._patterns:
+            setattr(self, name, compiled := _rx.compile(self._patterns[name]))
+            return compiled
+
+        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")

xulbux/string.py

@@ -0,0 +1,161 @@
+"""
+This module provides the `String` class, which includes
+various utility methods for string manipulation and conversion.
+"""
+
+from typing import Optional, Literal, Any
+import json as _json
+import ast as _ast
+import re as _re
+
+
+class String:
+    """This class provides various utility methods for string manipulation and conversion."""
+
+    @classmethod
+    def to_type(cls, string: str) -> Any:
+        """Will convert a string to the found type, including complex nested structures.\n
+        -----------------------------------------------------------------------------------
+        - `string` -⠀the string to convert"""
+        try:
+            return _ast.literal_eval(string := string.strip())
+        except (ValueError, SyntaxError):
+            try:
+                return _json.loads(string)
+            except _json.JSONDecodeError:
+                return string
+
+    @classmethod
+    def normalize_spaces(cls, string: str, tab_spaces: int = 4) -> str:
+        """Replaces all special space characters with normal spaces.\n
+        ---------------------------------------------------------------
+        - `tab_spaces` -⠀number of spaces to replace tab chars with"""
+        if tab_spaces < 0:
+            raise ValueError(f"The 'tab_spaces' parameter must be non-negative, got {tab_spaces!r}")
+
+        return string.replace("\t", " " * tab_spaces).replace("\u2000", " ").replace("\u2001", " ").replace("\u2002", " ") \
+            .replace("\u2003", " ").replace("\u2004", " ").replace("\u2005", " ").replace("\u2006", " ") \
+            .replace("\u2007", " ").replace("\u2008", " ").replace("\u2009", " ").replace("\u200A", " ")
+
+    @classmethod
+    def escape(cls, string: str, str_quotes: Optional[Literal["'", '"']] = None) -> str:
+        """Escapes Python's special characters (e.g. `\\n`, `\\t`, …) and quotes inside the string.\n
+        --------------------------------------------------------------------------------------------------------
+        - `string` -⠀the string to escape
+        - `str_quotes` -⠀the type of quotes the string will be put inside of (or None to not escape quotes)<br>
+          Can be either `"` or `'` and should match the quotes, the string will be put inside of.<br>
+          So if your string will be `"string"`, `str_quotes` should be `"`.<br>
+          That way, if the string includes the same quotes, they will be escaped."""
+        string = string.replace("\\", "\\\\").replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t") \
+            .replace("\b", "\\b").replace("\f", "\\f").replace("\a", "\\a")
+
+        if str_quotes == '"':
+            return string.replace("\\'", "'").replace('"', '\\"')
+        elif str_quotes == "'":
+            return string.replace('\\"', '"').replace("'", "\\'")
+        else:
+            return string
+
+    @classmethod
+    def is_empty(cls, string: Optional[str], spaces_are_empty: bool = False) -> bool:
+        """Returns `True` if the string is considered empty and `False` otherwise.\n
+        -----------------------------------------------------------------------------------------------
+        - `string` -⠀the string to check (or `None`, which is considered empty)
+        - `spaces_are_empty` -⠀if true, strings consisting only of spaces are also considered empty"""
+        return bool(
+            (string in {"", None}) or \
+            (spaces_are_empty and isinstance(string, str) and not string.strip())
+        )
+
+    @classmethod
+    def single_char_repeats(cls, string: str, char: str) -> int | bool:
+        """- If the string consists of only the same `char`, it returns the number of times it is present.
+        - If the string doesn't consist of only the same character, it returns `False`.\n
+        ---------------------------------------------------------------------------------------------------
+        - `string` -⠀the string to check
+        - `char` -⠀the character to check for repetition"""
+        if len(char) != 1:
+            raise ValueError(f"The 'char' parameter must be a single character, got {char!r}")
+
+        if len(string) == (len(char) * string.count(char)):
+            return string.count(char)
+        else:
+            return False
+
+    @classmethod
+    def decompose(cls, case_string: str, seps: str = "-_", lower_all: bool = True) -> list[str]:
+        """Will decompose the string (any type of casing, also mixed) into parts.\n
+        ----------------------------------------------------------------------------
+        - `case_string` -⠀the string to decompose
+        - `seps` -⠀additional separators to split the string at
+        - `lower_all` -⠀if true, all parts will be converted to lowercase"""
+        return [
+            (part.lower() if lower_all else part) \
+            for part in _re.split(rf"(?<=[a-z])(?=[A-Z])|[{_re.escape(seps)}]", case_string)
+        ]
+
+    @classmethod
+    def to_camel_case(cls, string: str, upper: bool = True) -> str:
+        """Will convert the string of any type of casing to CamelCase.\n
+        -----------------------------------------------------------------
+        - `string` -⠀the string to convert
+        - `upper` -⠀if true, it will convert to UpperCamelCase,
+          otherwise to lowerCamelCase"""
+        parts = cls.decompose(string)
+
+        return (
+            ("" if upper else parts[0].lower()) + \
+            "".join(part.capitalize() for part in (parts if upper else parts[1:]))
+        )
+
+    @classmethod
+    def to_delimited_case(cls, string: str, delimiter: str = "_", screaming: bool = False) -> str:
+        """Will convert the string of any type of casing to delimited case.\n
+        -----------------------------------------------------------------------
+        - `string` -⠀the string to convert
+        - `delimiter` -⠀the delimiter to use between parts
+        - `screaming` -⠀whether to convert all parts to uppercase"""
+        return delimiter.join(
+            part.upper() if screaming else part \
+            for part in cls.decompose(string)
+        )
+
+    @classmethod
+    def get_lines(cls, string: str, remove_empty_lines: bool = False) -> list[str]:
+        """Will split the string into lines.\n
+        ------------------------------------------------------------------------------------
+        - `string` -⠀the string to split
+        - `remove_empty_lines` -⠀if true, it will remove all empty lines from the result"""
+        if not remove_empty_lines:
+            return string.splitlines()
+        elif not (lines := string.splitlines()):
+            return []
+        elif not (non_empty_lines := [line for line in lines if line.strip()]):
+            return []
+        else:
+            return non_empty_lines
+
+    @classmethod
+    def remove_consecutive_empty_lines(cls, string: str, max_consecutive: int = 0) -> str:
+        """Will remove consecutive empty lines from the string.\n
+        -------------------------------------------------------------------------------------
+        - `string` -⠀the string to process
+        - `max_consecutive` -⠀the maximum number of allowed consecutive empty lines.<br>
+          * If `0`, it will remove all consecutive empty lines.
+          * If bigger than `0`, it will only allow `max_consecutive` consecutive empty lines
+            and everything above it will be cut down to `max_consecutive` empty lines."""
+        if max_consecutive < 0:
+            raise ValueError(f"The 'max_consecutive' parameter must be non-negative, got {max_consecutive!r}")
+
+        return _re.sub(r"(\n\s*){2,}", r"\1" * (max_consecutive + 1), string)
+
+    @classmethod
+    def split_count(cls, string: str, count: int) -> list[str]:
+        """Will split the string every `count` characters.\n
+        -----------------------------------------------------
+        - `string` -⠀the string to split
+        - `count` -⠀the number of characters per part"""
+        if count <= 0:
+            raise ValueError(f"The 'count' parameter must be a positive integer, got {count!r}")
+
+        return [string[i:i + count] for i in range(0, len(string), count)]