xulbux 1.6.0__py3-none-any.whl → 1.6.2__py3-none-any.whl

xulbux/xx_format_codes.py

@@ -1,56 +1,74 @@
 """
-Functions to be able to use special (easy) formatting codes directly inside some message (string).<br>
+Functions to be able to use special (easy) formatting codes directly inside some message (string).\n
 These codes, when used within following functions, will change the look of log within the console:
-- `FormatCodes.print()` (*print a special format-codes containing string*)
-- `FormatCodes.input()` (*input with a special format-codes containing prompt*)
-- `FormatCodes.to_ansi()` (*transform all special format-codes into ANSI codes in a string*)\n
+- `FormatCodes.print()` (print a special format-codes containing string)
+- `FormatCodes.input()` (input with a special format-codes containing prompt)
+- `FormatCodes.to_ansi()` (transform all special format-codes into ANSI codes in a string)\n
 --------------------------------------------------------------------------------------------------------------------
-How to change the text format and color?<br>
-**Example string with formatting codes:**<br>
-> `[bold]This is bold text, [#F08]which is pink now [black|BG:#FF0088] and now it changed`<br>
-> `to black with a pink background. [_]And this is the boring text, where everything is reset.`\n
-⇾ **Instead of writing the formats all separate** `[…][…][…]` **you can join them like this** `[…|…|…]`\n
+How to change the text format and color?\n
+Example string with formatting codes:
+```string
+[bold]This is bold text, [#F08]which is pink now [black|BG:#FF0088] and now it changed`
+to black with a pink background. [_]And this is the boring text, where everything is reset.
+```
+⇾ Instead of writing the formats all separate `[x][y][z]` you can join them like this `[x|y|z]`\n
 --------------------------------------------------------------------------------------------------------------------
-You can also automatically reset a certain format, behind text like shown in the following example:<br>
-> `This is normal text [b](which is bold now) but now it was automatically reset to normal.`\n
-This will only reset formats, that have a reset listed below. Colors and BG-colors won't be reset.<br>
-This is what will happen, if you use it with a color-format:<br>
-> `[cyan]This is cyan text [b](which is bold now.) Now it's not bold any more but still cyan.`\n
-If you want to ignore the `()` brackets you can put a `\\` or `/` between:<br>
-> `[cyan]This is cyan text [b]/(which is bold now.) And now it is still bold and cyan.`\n
-⇾ **To see these examples in action, you can put them into the** `FormatCodes.print()` **function.**\n
+You can also automatically reset a certain format, behind text like shown in the following example:
+```string
+This is normal text [b](which is bold now) but now it was automatically reset to normal.
+```
+This will only reset formats, that have a reset listed below. Colors and BG-colors won't be reset.\n
+This is what will happen, if you use it with a color-format:
+```string
+[cyan]This is cyan text [b](which is bold now.) Now it's not bold any more but still cyan.
+```
+If you want to ignore the `()` brackets you can put a `\\` or `/` between:
+```string
+[cyan]This is cyan text [b]/(which is bold now.) And now it is still bold and cyan.
+```
+⇾ To see these examples in action, you can put them into the `FormatCodes.print()` function.\n
 --------------------------------------------------------------------------------------------------------------------
-**All possible formatting codes:**
-- HEX colors:  `[#F08]` or `[#FF0088]` (*with or without leading #*)
+All possible formatting codes:
+- HEX colors:  `[#F08]` or `[#FF0088]` (with or without leading #)
 - RGB colors:  `[rgb(255, 0, 136)]`
-- bright colors:  `[bright:#F08]`
 - background colors:  `[BG:#F08]`
 - standard cmd colors:
-    - `[black]`
-    - `[red]`
-    - `[green]`
-    - `[yellow]`
-    - `[blue]`
-    - `[magenta]`
-    - `[cyan]`
-    - `[white]`
+  - `[black]`
+  - `[red]`
+  - `[green]`
+  - `[yellow]`
+  - `[blue]`
+  - `[magenta]`
+  - `[cyan]`
+  - `[white]`
 - bright cmd colors: `[bright:black]` or `[br:black]`, `[bright:red]` or `[br:red]`, ...
 - background cmd colors: `[BG:black]`, `[BG:red]`, ...
-- bright background cmd colors: `[BG:bright:black]` or `[BG:br:black]`, `[BG:bright:red]` or `[BG:br:red]`, ...<br>
-    ⇾ **The order of** `BG:` **and** `bright:` or `br:` **does not matter.**
+- bright background cmd colors: `[BG:bright:black]` or `[BG:br:black]`, `[BG:bright:red]` or `[BG:br:red]`, ...\n
+  ⇾ The order of `BG:` and `bright:` or `br:` does not matter.
 - text formats:
-    - `[bold]` or `[b]`
-    - `[dim]`
-    - `[italic]` or `[i]`
-    - `[underline]` or `[u]`
-    - `[inverse]`, `[invert]` or `[in]`
-    - `[hidden]`, `[hide]` or `[h]`
-    - `[strikethrough]` or `[s]`
-    - `[double-underline]` or `[du]`
-- specific reset:  `[_bold]` or `[_b]`, `[_dim]`, ... or `[_color]` or `[_c]`, `[_background]` or `[_bg]`
-- total reset: `[_]` (only if no `default_color` is set, otherwise see **↓** )
+  - `[bold]` or `[b]`
+  - `[dim]`
+  - `[italic]` or `[i]`
+  - `[underline]` or `[u]`
+  - `[inverse]`, `[invert]` or `[in]`
+  - `[hidden]`, `[hide]` or `[h]`
+  - `[strikethrough]` or `[s]`
+  - `[double-underline]` or `[du]`
+- specific reset:
+  - `[_bold]` or `[_b]`
+  - `[_dim]`
+  - `[_italic]` or `[_i]`
+  - `[_underline]` or `[_u]`
+  - `[_inverse]`, `[_invert]` or `[_in]`
+  - `[_hidden]`, `[_hide]` or `[_h]`
+  - `[_strikethrough]` or `[_s]`
+  - `[_double-underline]` or `[_du]`
+  - `[_color]` or `[_c]`
+  - `[_background]` or `[_bg]`
+- total reset:
+  - `[_]`
 --------------------------------------------------------------------------------------------------------------------
-**Special formatting when param `default_color` is set to a color:**
+Additional formats when a `default_color` is set:
 - `[*]` will reset everything, just like `[_]`, but the text-color will remain in `default_color`
 - `[*color]` will reset the text-color, just like `[_color]`, but then also make it `default_color`
 - `[default]` will just color the text in `default_color`,
@@ -78,20 +96,32 @@ import regex as _rx
 import sys as _sys
 import re as _re
 
-
+PREFIX = {
+    "BG": {"background", "bg"},
+    "BR": {"bright", "br"},
+}
+PREFIXES = {val for values in PREFIX.values() for val in values}
+PREFIX_RX = {
+    "BG": rf"(?:{'|'.join(PREFIX['BG'])})\s*:",
+    "BR": rf"(?:{'|'.join(PREFIX['BR'])})\s*:",
+}
 COMPILED = {  # PRECOMPILE REGULAR EXPRESSIONS
     "*": _re.compile(r"\[\s*([^]_]*?)\s*\*\s*([^]_]*?)\]"),
     "*color": _re.compile(r"\[\s*([^]_]*?)\s*\*color\s*([^]_]*?)\]"),
     "format": _rx.compile(
         Regex.brackets("[", "]", is_group=True) + r"(?:\s*([/\\]?)\s*" + Regex.brackets("(", ")", is_group=True) + r")?"
     ),
-    "bg?_default": _re.compile(r"(?i)((?:BG\s*:)?)\s*default"),
-    "bg_default": _re.compile(r"(?i)BG\s*:\s*default"),
+    "bg?_default": _re.compile(r"(?i)((?:" + PREFIX_RX["BG"] + r")?)\s*default"),
+    "bg_default": _re.compile(r"(?i)" + PREFIX_RX["BG"] + r"\s*default"),
     "modifier": _re.compile(
-        rf'(?i)((?:BG\s*:)?)\s*({"|".join([f"{_re.escape(m)}+" for m in ANSI.modifier["lighten"] + ANSI.modifier["darken"]])})$'
+        r"(?i)((?:BG\s*:)?)\s*("
+        + "|".join([f"{_re.escape(m)}+" for m in ANSI.modifier["lighten"] + ANSI.modifier["darken"]])
+        + r")$"
     ),
-    "rgb": _re.compile(r"(?i)^\s*(BG\s*:)?\s*(?:rgb|rgba)?\s*\(?\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)?\s*$"),
-    "hex": _re.compile(r"(?i)^\s*(BG\s*:)?\s*(?:#|0x)?([0-9A-F]{6}|[0-9A-F]{3})\s*$"),
+    "rgb": _re.compile(
+        r"(?i)^\s*(" + PREFIX_RX["BG"] + r")?\s*(?:rgb|rgba)?\s*\(?\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})\s*\)?\s*$"
+    ),
+    "hex": _re.compile(r"(?i)^\s*(" + PREFIX_RX["BG"] + r")?\s*(?:#|0x)?([0-9A-F]{6}|[0-9A-F]{3})\s*$"),
 }
 
 
@@ -106,6 +136,10 @@ class FormatCodes:
         end: str = "\n",
         flush: bool = True,
     ) -> None:
+        """Print a string that can be formatted using special formatting codes.\n
+        --------------------------------------------------------------------------
+        For exact information about how to use special formatting codes, see the
+        `xx_format_codes` module documentation."""
         FormatCodes.__config_console()
         _sys.stdout.write(FormatCodes.to_ansi(sep.join(map(str, values)) + end, default_color, brightness_steps))
         if flush:
@@ -116,16 +150,29 @@ class FormatCodes:
         prompt: object = "",
         default_color: hexa | rgba = None,
         brightness_steps: int = 20,
+        reset_ansi: bool = False,
     ) -> str:
+        """An input, which's prompt can be formatted using special formatting codes.\n
+        -------------------------------------------------------------------------------
+        If `reset_ansi` is true, all ANSI formatting will be reset, after the user has
+        confirmed the input and the program continues.\n
+        -------------------------------------------------------------------------------
+        For exact information about how to use special formatting codes, see the
+        `xx_format_codes` module documentation."""
         FormatCodes.__config_console()
-        return input(FormatCodes.to_ansi(prompt, default_color, brightness_steps))
+        user_input = input(FormatCodes.to_ansi(prompt, default_color, brightness_steps))
+        if reset_ansi:
+            _sys.stdout.write("\x1b[0m")
+        return user_input
 
     @staticmethod
     def to_ansi(
         string: str, default_color: hexa | rgba = None, brightness_steps: int = 20, _default_start: bool = True
     ) -> str:
-        result, bg_kwd, color_pref = string, {"bg"}, {"br", "bright"}
-
+        """Convert the special formatting codes inside a string to printable ANSI codes.\n
+        -----------------------------------------------------------------------------------
+        For exact information about how to use special formatting codes, see the
+        `xx_format_codes` module documentation."""
         if Color.is_valid_rgba(default_color, False):
             use_default = True
         elif Color.is_valid_hexa(default_color, False):
@@ -158,10 +205,9 @@ class FormatCodes:
                 reset_keys = []
                 for k in format_keys:
                     k_lower = k.lower()
-                    k_parts = k_lower.split(":")
-                    k_set = set(k_parts)
-                    if bg_kwd & k_set and len(k_parts) <= 3:
-                        if k_set & color_pref:
+                    k_set = set(k_lower.split(":"))
+                    if PREFIX["BG"] & k_set and len(k_set) <= 3:
+                        if k_set & PREFIX["BR"]:
                             for i in range(len(k)):
                                 if is_valid_color(k[i:]):
                                     reset_keys.extend(["_bg", "_color"])
@@ -173,7 +219,7 @@ class FormatCodes:
                                     break
                     elif is_valid_color(k) or any(
                         k_lower.startswith(pref_colon := f"{prefix}:") and is_valid_color(k[len(pref_colon) :])
-                        for prefix in color_pref
+                        for prefix in PREFIX["BR"]
                     ):
                         reset_keys.append("_color")
                     else:
@@ -201,8 +247,8 @@ class FormatCodes:
                 + ("" if escaped else "".join(ansi_resets))
             )
 
-        result = "\n".join(COMPILED["format"].sub(replace_keys, line) for line in string.split("\n"))
-        return (FormatCodes.__get_default_ansi(default_color) if _default_start else "") + result if use_default else result
+        string = "\n".join(COMPILED["format"].sub(replace_keys, line) for line in string.split("\n"))
+        return (FormatCodes.__get_default_ansi(default_color) if _default_start else "") + string if use_default else string
 
     @staticmethod
     def escape_ansi(ansi_string: str, escaped_char: str = ANSI.char_esc) -> str:
@@ -212,6 +258,7 @@ class FormatCodes:
     @staticmethod
     @lru_cache(maxsize=64)
     def __config_console() -> None:
+        """Configure the console to be able to interpret ANSI formatting."""
         _sys.stdout.flush()
         kernel32 = _ctypes.windll.kernel32
         h = kernel32.GetStdHandle(-11)
@@ -226,6 +273,7 @@ class FormatCodes:
         brightness_steps: int = None,
         _modifiers: tuple[str, str] = (ANSI.modifier["lighten"], ANSI.modifier["darken"]),
     ) -> str | None:
+        """Get the `default_color` and lighter/darker versions of it in ANSI format."""
         if not brightness_steps or (format_key and COMPILED["bg?_default"].search(format_key)):
             return (ANSI.seq_bg_color if format_key and COMPILED["bg_default"].search(format_key) else ANSI.seq_color).format(
                 *default_color[:3]
@@ -252,15 +300,11 @@ class FormatCodes:
 
     @staticmethod
     def __get_replacement(format_key: str, default_color: rgba = None, brightness_steps: int = 20) -> str:
-        """Gives you the corresponding ANSI code for the given format key.<br>
-        If `default_color` is not `None`, the text color will be `default_color` if all formats<br>
+        """Gives you the corresponding ANSI code for the given format key.
+        If `default_color` is not `None`, the text color will be `default_color` if all formats
         are reset or you can get lighter or darker version of `default_color` (also as BG)"""
         use_default = default_color and Color.is_valid_rgba(default_color, False)
-        _format_key, format_key = format_key, (  # NORMALIZE THE FORMAT KEY (+ SAVE ORIGINAL)
-            "bg:" if "bg" in (parts := format_key.replace(" ", "").lower().split(":")) else ""
-        ) + ("bright:" if any(x in parts for x in ("bright", "br")) else "") + ":".join(
-            p for p in parts if p not in ("bg", "bright", "br")
-        )
+        _format_key, format_key = format_key, FormatCodes.__normalize_key(format_key)  # NORMALIZE KEY AND SAVE ORIGINAL
         if use_default:
             if new_default_color := FormatCodes.__get_default_ansi(default_color, format_key, brightness_steps):
                 return new_default_color
@@ -295,3 +339,17 @@ class FormatCodes:
         except Exception:
             pass
         return _format_key
+
+    @staticmethod
+    @lru_cache(maxsize=64)
+    def __normalize_key(format_key: str) -> str:
+        """Normalizes the given format key."""
+        k_parts = format_key.replace(" ", "").lower().split(":")
+        prefix_str = "".join(
+            f"{prefix_key.lower()}:"
+            for prefix_key, prefix_values in PREFIX.items()
+            if any(k_part in prefix_values for k_part in k_parts)
+        )
+        return prefix_str + ":".join(
+            part for part in k_parts if part not in {val for values in PREFIX.values() for val in values}
+        )

xulbux/xx_json.py

@@ -16,13 +16,15 @@ class Json:
     ) -> dict | tuple[dict, dict]:
         """Read JSON files, ignoring comments.\n
         -------------------------------------------------------------------------
-        If only `comment_start` is found at the beginning of an item,<br>
-        the whole item is counted as a comment and therefore ignored.<br>
-        If `comment_start` and `comment_end` are found inside an item,<br>
-        the the section from `comment_start` to `comment_end` is ignored.<br>
-        If `return_original` is set to `True`, the original JSON is returned<br>
+        If only `comment_start` is found at the beginning of an item,
+        the whole item is counted as a comment and therefore ignored.
+        If `comment_start` and `comment_end` are found inside an item,
+        the the section from `comment_start` to `comment_end` is ignored.
+        If `return_original` is set to `True`, the original JSON is returned
         additionally. (returns: `[processed_json, original_json]`)"""
-        file_path = File.make_path(json_file, "json", prefer_base_dir=True)
+        if not json_file.endswith(".json"):
+            json_file += ".json"
+        file_path = File.extend_or_make_path(json_file, prefer_base_dir=True)
         with open(file_path, "r") as f:
             content = f.read()
         try:
@@ -42,7 +44,9 @@ class Json:
         compactness: int = 1,
         force: bool = False,
     ) -> str:
-        file_path = File.make_path(new_file, "json", prefer_base_dir=True)
+        if not new_file.endswith(".json"):
+            new_file += ".json"
+        file_path = File.extend_or_make_path(new_file, prefer_base_dir=True)
         if _os.path.exists(file_path) and not force:
             with open(file_path, "r", encoding="utf-8") as existing_f:
                 existing_content = _json.load(existing_f)
@@ -63,27 +67,28 @@ class Json:
         sep: tuple[str, str] = ("->", "::"),
     ) -> None:
         """Function to easily update single/multiple values inside JSON files.\n
-        --------------------------------------------------------------------------------------------------------
+        ------------------------------------------------------------------------------------------------------
         The param `json_file` is the path to the JSON file or just the name of the JSON file to be updated.\n
-        --------------------------------------------------------------------------------------------------------
-        The param `update_values` is a sort of path (or a list of paths) to the value/s to be updated, with<br>
-        the new value at the end of the path.<br>
+        ------------------------------------------------------------------------------------------------------
+        The param `update_values` is a sort of path (or a list of paths) to the value/s to be updated, with
+        the new value at the end of the path.\n
         In this example:
-        ```\n {
+        ```python
+        {
           'healthy': {
             'fruit': ['apples', 'bananas', 'oranges'],
             'vegetables': ['carrots', 'broccoli', 'celery']
           }
-        }\n```
-        ... if you want to change the value of `'apples'` to `'strawberries'`, `update_values` would<br>
-        be `healthy->fruit->apples::strawberries` or if you don't know that the value to update<br>
-        is `apples` you can also use the position of the value, so `healthy->fruit->0::strawberries`.\n
-        ⇾ **If the path from `update_values` doesn't exist, it will be created.**\n
-        --------------------------------------------------------------------------------------------------------
-        If only `comment_start` is found at the beginning of an item, the whole item is counted<br>
-        as a comment and therefore ignored. If `comment_start` and `comment_end` are found<br>
-        inside an item, the the section from `comment_start` to `comment_end` is ignored.
-        """
+        }
+        ```
+        ... if you want to change the value of `'apples'` to `'strawberries'`, `update_values` would be
+        `healthy->fruit->apples::strawberries` or if you don't know that the value to update is `apples` you
+        can also use the position of the value, so `healthy->fruit->0::strawberries`.\n
+        ⇾ If the path from `update_values` doesn't exist, it will be created.\n
+        ------------------------------------------------------------------------------------------------------
+        If only `comment_start` is found at the beginning of an item, the whole item is counted as a comment
+        and therefore ignored. If `comment_start` and `comment_end` are found inside an item, the the section
+        from `comment_start` to `comment_end` is ignored."""
         if isinstance(update_values, str):
             update_values = [update_values]
         valid_entries = [

xulbux/xx_path.py

@@ -8,7 +8,7 @@ import os as _os
 class Path:
 
     @staticmethod
-    def get(cwd: bool = False, base_dir: bool = False) -> str | list:
+    def get(cwd: bool = False, base_dir: bool = False) -> str | list[str]:
         paths = []
         if cwd:
             paths.append(_os.getcwd())
@@ -29,12 +29,7 @@ class Path:
         return paths[0] if len(paths) == 1 else paths
 
     @staticmethod
-    def extend(
-        path: str,
-        search_in: str | list[str] = None,
-        raise_error: bool = False,
-        correct_path: bool = False,
-    ) -> str:
+    def extend(path: str, search_in: str | list[str] = None, raise_error: bool = False, correct_path: bool = False) -> str:
         if path in (None, ""):
             return path
 

xulbux/xx_regex.py

@@ -1,11 +1,11 @@
 """
-Really long regex code presets:<br>
-`quotes` match everything inside quotes<br>
-`brackets` match everything inside brackets<br>
-`outside_strings` match the pattern but not inside strings<br>
-`all_except` match everything except a certain pattern<br>
-`func_call` match a function call<br>
-`rgba_str` match an RGBA color<br>
+Really long regex code presets:
+`quotes` match everything inside quotes
+`brackets` match everything inside brackets
+`outside_strings` match the pattern but not inside strings
+`all_except` match everything except a certain pattern
+`func_call` match a function call
+`rgba_str` match an RGBA color
 `hsla_str` match a HSLA color
 """
 
@@ -16,20 +16,20 @@ class Regex:
 
     @staticmethod
     def quotes() -> str:
-        """Matches everything inside quotes. (Strings)\n
+        """Matches everything inside quotes. (strings)\n
         ------------------------------------------------------------------------------------
-        Will create two named groups:<br>
-        **`quote`** the quote type (single or double)<br>
-        **`string`** everything inside the found quote pair\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`!"""
+        Attention: Requires non standard library `regex` not standard library `re`!"""
         return r'(?P<quote>[\'"])(?P<string>(?:\\.|(?!\g<quote>).)*?)\g<quote>'
 
     @staticmethod
     def brackets(bracket1: str = "(", bracket2: str = ")", is_group: bool = False) -> str:
         """Matches everything inside brackets, including other nested brackets.\n
         ------------------------------------------------------------------------------------
-        **Attention:** Requires non standard library `regex` not standard library `re`!"""
+        Attention: Requires non standard library `regex` not standard library `re`!"""
         g, b1, b2 = (
             "" if is_group else "?:",
             _re.escape(bracket1) if len(bracket1) == 1 else bracket1,
@@ -50,40 +50,40 @@ class Regex:
     ) -> str:
         """Matches everything except `disallowed_pattern`, unless the `disallowed_pattern` is found inside a string (`'...'` or `"..."`).\n
         ------------------------------------------------------------------------------------------------------------------------------------
-        The `ignore_pattern` is just always ignored. For example if `disallowed_pattern` is `>` and `ignore_pattern` is `->`, the `->`<br>
-        -arrows will be allowed, even though they have `>` in them. If `is_group` is `True`, you will be able to reference the matched<br>
-        content as a group (e.g. <code>match.group(<i>int</i>)</code> or <code>r'\\<i>int</i>'</code>)."""
+        The `ignore_pattern` is just always ignored. For example if `disallowed_pattern` is `>` and `ignore_pattern` is `->`, the `->`
+        -arrows will be allowed, even though they have `>` in them. If `is_group` is `True`, you will be able to reference the matched
+        content as a group (e.g. `match.group(int)` or `r'\\int'`)."""
         return rf'({"" if is_group else "?:"}(?:(?!{ignore_pattern}).)*(?:(?!{Regex.outside_strings(disallowed_pattern)}).)*)'
 
     @staticmethod
     def func_call(func_name: str = None) -> str:
-        """Match a function call<br>
-        **`1`** function name<br>
-        **`2`** the function's arguments\n
+        """Match a function call
+        - `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`!"""
+        Attention: Requires non standard library `regex` not standard library `re`!"""
         return r"(?<=\b)(" + (func_name if func_name else r"[\w_]+") + r")\s*" + Regex.brackets("(", ")", is_group=True)
 
     @staticmethod
     def rgba_str(fix_sep: str = ",", allow_alpha: bool = True) -> str:
         """Matches an RGBA color inside a string.\n
-        --------------------------------------------------------------------------------
-        The RGBA color can be in the formats (for `fix_sep = ','`):<br>
-        `rgba(r, g, b)`<br>
-        `rgba(r, g, b, a)` (if `allow_alpha=True`)<br>
-        `(r, g, b)`<br>
-        `(r, g, b, a)` (if `allow_alpha=True`)<br>
-        `r, g, b`<br>
-        `r, g, b, a` (if `allow_alpha=True`)\n
-        --------------------------------------------------------------------------------
-        ### Valid ranges:<br>
-        `r` 0-255 (amount: red)<br>
-        `g` 0-255 (amount: green)<br>
-        `b` 0-255 (amount: blue)<br>
-        `a` 0-1 (float: opacity)\n
-        --------------------------------------------------------------------------------
-        If the `fix_sep` is set to nothing, any char that is not a letter or number<br>
+        ----------------------------------------------------------------------------
+        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 (amount: red)
+        - `g` 0-255 (amount: green)
+        - `b` 0-255 (amount: blue)
+        - `a` 0-1 (float: opacity)\n
+        ----------------------------------------------------------------------------
+        If the `fix_sep` is set to nothing, any char that is not a letter or number
         can be used to separate the RGBA values, including just a space."""
         if fix_sep in (None, ""):
             fix_sep = r"[^0-9A-Z]"
@@ -104,22 +104,22 @@ class Regex:
     @staticmethod
     def hsla_str(fix_sep: str = ",", allow_alpha: bool = True) -> str:
         """Matches a HSLA color inside a string.\n
-        --------------------------------------------------------------------------------
-        The HSLA color can be in the formats (for `fix_sep = ','`):<br>
-        `hsla(h, s, l)`<br>
-        `hsla(h, s, l, a)` (if `allow_alpha=True`)<br>
-        `(h, s, l)`<br>
-        `(h, s, l, a)` (if `allow_alpha=True`)<br>
-        `h, s, l`<br>
-        `h, s, l, a` (if `allow_alpha=True`)\n
-        --------------------------------------------------------------------------------
-        ### Valid ranges:<br>
-        `h` 0-360 (degrees: hue)<br>
-        `s` 0-100 (percentage: saturation)<br>
-        `l` 0-100 (percentage: lightness)<br>
-        `a` 0-1 (float: opacity)\n
-        --------------------------------------------------------------------------------
-        If the `fix_sep` is set to nothing, any char that is not a letter or number<br>
+        ----------------------------------------------------------------------------
+        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 (degrees: hue)
+        - `s` 0-100 (percentage: saturation)
+        - `l` 0-100 (percentage: lightness)
+        - `a` 0-1 (float: opacity)\n
+        ----------------------------------------------------------------------------
+        If the `fix_sep` is set to nothing, any char that is not a letter or number
         can be used to separate the HSLA values, including just a space."""
         if fix_sep in (None, ""):
             fix_sep = r"[^0-9A-Z]"
@@ -140,15 +140,15 @@ class Regex:
     @staticmethod
     def hexa_str(allow_alpha: bool = True) -> str:
         """Matches a HEXA color inside a string.\n
-        --------------------------------------------------------------------------
-        The HEXA color can be in the formats (prefix `#`, `0x` or no prefix):<br>
-        `RGB`<br>
-        `RGBA` (if `allow_alpha=True`)<br>
-        `RRGGBB`<br>
-        `RRGGBBAA` (if `allow_alpha=True`)\n
-        --------------------------------------------------------------------------
-        ### Valid ranges:<br>
-        each channel from 0-9 and A-F (*case insensitive*)"""
+        ----------------------------------------------------------------------
+        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:
+        each 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

xulbux/xx_string.py

@@ -56,7 +56,7 @@ class String:
 
     @staticmethod
     def normalize_spaces(string: str, tab_spaces: int = 4) -> str:
-        """Replaces all special space characters with normal spaces.<br>
+        """Replaces all special space characters with normal spaces.
         Also replaces tab characters with `tab_spaces` spaces."""
         return (
             string.replace("\t", " " * tab_spaces)
@@ -76,10 +76,10 @@ class String:
     @staticmethod
     def escape(string: str, str_quotes: str = '"') -> str:
         """Escapes the special characters and quotes inside a string.\n
-        ----------------------------------------------------------------------------
-        `str_quotes` can be either `"` or `'` and should match the quotes,<br>
-        the string will be put inside of. So if your string will be `"string"`,<br>
-        you should pass `"` to the parameter `str_quotes`.<br>
+        ---------------------------------------------------------------------------
+        `str_quotes` can be either `"` or `'` and should match the quotes,
+        the string will be put inside of. So if your string will be `"string"`,
+        you should pass `"` to the parameter `str_quotes`.
         That way, if the string includes the same quotes, they will be escaped."""
         string = (
             string.replace("\\", r"\\")
@@ -98,14 +98,15 @@ class String:
 
     @staticmethod
     def is_empty(string: str, spaces_are_empty: bool = False):
-        """Returns `True` if the string is empty and `False` otherwise.<br>
+        """Returns `True` if the string is empty and `False` otherwise.\n
+        -------------------------------------------------------------------------------------------
         If `spaces_are_empty` is true, it will also return `True` if the string is only spaces."""
         return (string in (None, "")) or (spaces_are_empty and isinstance(string, str) and not string.strip())
 
     @staticmethod
     def single_char_repeats(string: str, char: str) -> int | bool:
-        """If the string consists of only the same `char`, it returns the number of times it is present.<br>
-        If the string doesn't consist of only the same character, it returns `False`."""
+        """- 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`."""
         if len(string) == len(char) * string.count(char):
             return string.count(char)
         else:
@@ -113,7 +114,7 @@ class String:
 
     @staticmethod
     def decompose(case_string: str, seps: str = "-_", lower_all: bool = True) -> list[str]:
-        """Will decompose the string (*any type of casing, also mixed*) into parts."""
+        """Will decompose the string (any type of casing, also mixed) into parts."""
         return [
             (part.lower() if lower_all else part)
             for part in _re.split(rf"(?<=[a-z])(?=[A-Z])|[{_re.escape(seps)}]", case_string)
@@ -121,7 +122,7 @@ class String:
 
     @staticmethod
     def to_camel_case(string: str, upper: bool = True) -> str:
-        """Will convert the string of any type of casing to UpperCamelCase or lowerCamelCase if `upper` is false."""
+        """Will convert the string of any type of casing to `UpperCamelCase` or `lowerCamelCase` if `upper` is false."""
         parts = String.decompose(string)
         return ("" if upper else parts[0].lower()) + "".join(part.capitalize() for part in (parts if upper else parts[1:]))
 
@@ -146,9 +147,9 @@ class String:
     @staticmethod
     def remove_consecutive_empty_lines(string: str, max_consecutive: int = 0) -> str:
         """Will remove consecutive empty lines from the string.\n
-        ----------------------------------------------------------------------------------------------
-        If `max_consecutive` is `0`, it will remove all consecutive empty lines.<br>
-        If `max_consecutive` is bigger than `0`, it will only allow `max_consecutive` consecutive<br>
+        --------------------------------------------------------------------------------------------
+        - If `max_consecutive` is `0`, it will remove all consecutive empty lines.
+        - If `max_consecutive` is 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."""
         return _re.sub(r"(\n\s*){2,}", r"\1" * (max_consecutive + 1), string)