xulbux 1.6.8__py3-none-any.whl → 1.7.0__py3-none-any.whl

xulbux/xx_format_codes.py

@@ -152,10 +152,10 @@ Per default, you can also use `+` and `-` to get lighter and darker `default_col
 
 from ._consts_ import ANSI
 from .xx_string import String
-from .xx_regex import Regex
-from .xx_color import Color, rgba, hexa
+from .xx_regex import Regex, Match, Pattern
+from .xx_color import Color, rgba, Rgba, Hexa
 
-from typing import Optional, Pattern
+from typing import Optional
 import ctypes as _ctypes
 import regex as _rx
 import sys as _sys
@@ -205,7 +205,7 @@ class FormatCodes:
     @staticmethod
     def print(
         *values: object,
-        default_color: rgba | hexa = None,
+        default_color: Optional[Rgba | Hexa] = None,
         brightness_steps: int = 20,
         sep: str = " ",
         end: str = "\n",
@@ -223,7 +223,7 @@ class FormatCodes:
     @staticmethod
     def input(
         prompt: object = "",
-        default_color: rgba | hexa = None,
+        default_color: Optional[Rgba | Hexa] = None,
         brightness_steps: int = 20,
         reset_ansi: bool = False,
     ) -> str:
@@ -243,7 +243,7 @@ class FormatCodes:
     @staticmethod
     def to_ansi(
         string: str,
-        default_color: rgba | hexa = None,
+        default_color: Optional[Rgba | Hexa] = None,
         brightness_steps: int = 20,
         _default_start: bool = True,
     ) -> str:
@@ -253,9 +253,9 @@ class FormatCodes:
         `xx_format_codes` module documentation."""
         if not isinstance(string, str):
             string = str(string)
-        if Color.is_valid_rgba(default_color, False):
+        if default_color and Color.is_valid_rgba(default_color, False):  # type: ignore[assignment]
             use_default = True
-        elif Color.is_valid_hexa(default_color, False):
+        elif default_color and Color.is_valid_hexa(default_color, False):  # type: ignore[assignment]
             use_default, default_color = True, Color.to_rgba(default_color)
         else:
             use_default = False
@@ -264,9 +264,9 @@ class FormatCodes:
             string = _COMPILED["*color"].sub(r"[\1default\2]", string)  # REPLACE `[…|*color|…]` WITH `[…|default|…]`
 
         def is_valid_color(color: str) -> bool:
-            return color in ANSI.color_map or Color.is_valid_rgba(color) or Color.is_valid_hexa(color)
+            return bool((color in ANSI.color_map) or Color.is_valid_rgba(color) or Color.is_valid_hexa(color))
 
-        def replace_keys(match: _re.Match) -> str:
+        def replace_keys(match: Match) -> str:
             _formats = formats = match.group(1)
             auto_reset_escaped = match.group(2)
             auto_reset_txt = match.group(3)
@@ -280,8 +280,8 @@ class FormatCodes:
                 formats = FormatCodes.to_ansi(formats, default_color, brightness_steps, False)
             format_keys = [k.strip() for k in formats.split("|") if k.strip()]
             ansi_formats = [
-                r if (r := FormatCodes.__get_replacement(k, default_color, brightness_steps)) != k else f"[{k}]"
-                for k in format_keys
+                r if (r := FormatCodes.__get_replacement(k, default_color, brightness_steps)) != k  # type: ignore[assignment]
+                else f"[{k}]" for k in format_keys
             ]
             if auto_reset_txt and not auto_reset_escaped:
                 reset_keys = []
@@ -306,8 +306,9 @@ class FormatCodes:
                     else:
                         reset_keys.append(f"_{k}")
                 ansi_resets = [
-                    r for k in reset_keys if (r := FormatCodes.__get_replacement(k, default_color, brightness_steps)
-                                              ).startswith(f"{ANSI.char}{ANSI.start}")
+                    r for k in reset_keys
+                    if (r := FormatCodes.__get_replacement(k, default_color, brightness_steps)  # type: ignore[assignment]
+                        ).startswith(f"{ANSI.char}{ANSI.start}")
                 ]
             else:
                 ansi_resets = []
@@ -325,7 +326,8 @@ class FormatCodes:
                 )
 
         string = "\n".join(_COMPILED["formatting"].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
+        return (((FormatCodes.__get_default_ansi(default_color) or "") if _default_start else "")  # type: ignore[assignment]
+                + string) if use_default else string
 
     @staticmethod
     def escape_ansi(ansi_string: str) -> str:
@@ -333,33 +335,50 @@ class FormatCodes:
         return ansi_string.replace(ANSI.char, ANSI.escaped_char)
 
     @staticmethod
-    def remove_ansi(ansi_string: str, get_removals: bool = False) -> str | tuple[str, tuple[tuple[int, str], ...]]:
+    def remove_ansi(
+        ansi_string: str,
+        get_removals: bool = False,
+        _ignore_linebreaks: bool = False,
+    ) -> str | tuple[str, tuple[tuple[int, str], ...]]:
         """Removes all ANSI codes from the string.\n
         --------------------------------------------------------------------------------------------------
         If `get_removals` is true, additionally to the cleaned string, a list of tuples will be returned.
-        Each tuple contains the position of the removed ansi code and the removed ansi code."""
+        Each tuple contains the position of the removed ansi code and the removed ansi code.\n
+        If `_ignore_linebreaks` is true, linebreaks will be ignored for the removal positions."""
         if get_removals:
             removals = []
 
-            def replacement(match: _re.Match) -> str:
+            def replacement(match: Match) -> str:
                 start_pos = match.start() - sum(len(removed) for _, removed in removals)
                 if removals and removals[-1][0] == start_pos:
                     start_pos = removals[-1][0]
                 removals.append((start_pos, match.group()))
                 return ""
 
-            clean_string = _COMPILED["ansi_seq"].sub(replacement, ansi_string)
-            return clean_string, tuple(removals)
+            clean_string = _COMPILED["ansi_seq"].sub(
+                replacement,
+                ansi_string.replace("\n", "") if _ignore_linebreaks else ansi_string
+            )
+            return _COMPILED["ansi_seq"].sub("", ansi_string) if _ignore_linebreaks else clean_string, tuple(removals)
         else:
             return _COMPILED["ansi_seq"].sub("", ansi_string)
 
     @staticmethod
-    def remove_formatting(string: str, get_removals: bool = False) -> str | tuple[str, tuple[tuple[int, str], ...]]:
+    def remove_formatting(
+        string: str,
+        get_removals: bool = False,
+        _ignore_linebreaks: bool = False,
+    ) -> str | tuple[str, tuple[tuple[int, str], ...]]:
         """Removes all formatting codes from the string.\n
-        ----------------------------------------------------------------------------------------------------
+        ---------------------------------------------------------------------------------------------------
         If `get_removals` is true, additionally to the cleaned string, a list of tuples will be returned.
-        Each tuple contains the position of the removed formatting code and the removed formatting code."""
-        return FormatCodes.remove_ansi(FormatCodes.to_ansi(string), get_removals=get_removals)
+        Each tuple contains the position of the removed formatting code and the removed formatting code.\n
+        If `_ignore_linebreaks` is true, linebreaks will be ignored for the removal positions."""
+        return FormatCodes.remove_ansi(
+            FormatCodes.to_ansi(string),
+            get_removals=get_removals,
+            _ignore_linebreaks=_ignore_linebreaks,
+        )
 
     @staticmethod
     def __config_console() -> None:
@@ -377,8 +396,8 @@ class FormatCodes:
     @staticmethod
     def __get_default_ansi(
         default_color: tuple,
-        format_key: str = None,
-        brightness_steps: int = None,
+        format_key: Optional[str] = None,
+        brightness_steps: Optional[int] = None,
         _modifiers: tuple[str, str] = (ANSI.default_color_modifiers["lighten"], ANSI.default_color_modifiers["darken"]),
     ) -> Optional[str]:
         """Get the `default_color` and lighter/darker versions of it as ANSI code."""
@@ -386,8 +405,9 @@ class FormatCodes:
             return (ANSI.seq_bg_color if format_key and _COMPILED["bg_default"].search(format_key) else ANSI.seq_color).format(
                 *default_color[:3]
             )
-        if not (format_key in _modifiers[0] or format_key in _modifiers[1]):
+        if format_key is None or not (format_key in _modifiers[0] or format_key in _modifiers[1]):
             return None
+        assert format_key is not None
         match = _COMPILED["modifier"].match(format_key)
         if not match:
             return None
@@ -398,23 +418,25 @@ class FormatCodes:
             if adjust and adjust > 0:
                 modifiers = mod
                 break
+        new_rgb = default_color
         if adjust == 0:
             return None
         elif modifiers in _modifiers[0]:
-            new_rgb = Color.adjust_lightness(default_color, (brightness_steps / 100) * adjust)
+            new_rgb = tuple(Color.adjust_lightness(default_color, (brightness_steps / 100) * adjust))
         elif modifiers in _modifiers[1]:
-            new_rgb = Color.adjust_lightness(default_color, -(brightness_steps / 100) * adjust)
+            new_rgb = tuple(Color.adjust_lightness(default_color, -(brightness_steps / 100) * adjust))
         return (ANSI.seq_bg_color if is_bg else ANSI.seq_color).format(*new_rgb[:3])
 
     @staticmethod
-    def __get_replacement(format_key: str, default_color: rgba = None, brightness_steps: int = 20) -> str:
+    def __get_replacement(format_key: str, default_color: Optional[Rgba] = None, brightness_steps: int = 20) -> str:
         """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)
+        _default_color = tuple(Color.to_rgba(default_color)) if use_default else ()  # type: ignore[assignment]
         _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):
+            if new_default_color := FormatCodes.__get_default_ansi(_default_color, format_key, brightness_steps):
                 return new_default_color
         for map_key in ANSI.codes_map:
             if (isinstance(map_key, tuple) and format_key in map_key) or format_key == map_key:
@@ -423,8 +445,8 @@ class FormatCodes:
                         v for k, v in ANSI.codes_map.items() if format_key == k or (isinstance(k, tuple) and format_key in k)
                     ), None)
                 )
-        rgb_match = _re.match(_COMPILED["rgb"], format_key)
-        hex_match = _re.match(_COMPILED["hex"], format_key)
+        rgb_match = _COMPILED["rgb"].match(format_key)
+        hex_match = _COMPILED["hex"].match(format_key)
         try:
             if rgb_match:
                 is_bg = rgb_match.group(1)

xulbux/xx_json.py

@@ -1,8 +1,9 @@
 from .xx_data import Data
 from .xx_file import File
+from .xx_path import Path
 
+from typing import Any
 import json as _json
-import os as _os
 
 
 class Json:
@@ -15,89 +16,144 @@ class Json:
         return_original: bool = False,
     ) -> dict | tuple[dict, dict]:
         """Read JSON files, ignoring comments.\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 `return_original` is set to `True`, the original JSON is returned
+        If `return_original` is true, the original JSON is returned
         additionally. (returns: `[processed_json, original_json]`)"""
         if not json_file.endswith(".json"):
             json_file += ".json"
-        file_path = File.extend_or_make_path(json_file, prefer_base_dir=True)
+        file_path = Path.extend_or_make(json_file, prefer_script_dir=True)
+        if file_path is None:
+            raise FileNotFoundError(f"Could not find JSON file: {json_file}")
         with open(file_path, "r") as f:
             content = f.read()
         try:
             data = _json.loads(content)
         except _json.JSONDecodeError as e:
             raise ValueError(f"Error parsing JSON in '{file_path}':  {str(e)}")
-        processed_data = Data.remove_comments(data, comment_start, comment_end)
+        processed_data = dict(Data.remove_comments(data, comment_start, comment_end))
         if not processed_data:
             raise ValueError(f"The JSON file '{file_path}' is empty or contains only comments.")
         return (processed_data, data) if return_original else processed_data
 
     @staticmethod
     def create(
-        content: dict,
-        new_file: str = "config",
+        json_file: str,
+        data: dict,
         indent: int = 2,
         compactness: int = 1,
         force: bool = False,
     ) -> str:
-        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)
-                if existing_content == content:
-                    raise FileExistsError("Already created this file. (nothing changed)")
-            raise FileExistsError("File already exists.")
-        with open(file_path, "w", encoding="utf-8") as f:
-            f.write(Data.to_str(content, indent, compactness, as_json=True))
-        full_path = _os.path.abspath(file_path)
-        return full_path
+        """Create a nicely formatted JSON file from a dictionary.\n
+        ----------------------------------------------------------------------
+        The `indent` is the amount of spaces to use for indentation.\n
+        The `compactness` can be `0`, `1` or `2` and indicates how compact
+        the data should be formatted (see `Data.to_str()`).\n
+        The function will throw a `FileExistsError` if a file with the same
+        name already exists and a `SameContentFileExistsError` if a file with
+        the same name and content already exists.
+        To always overwrite the file, set the `force` parameter to `True`."""
+        if not json_file.endswith(".json"):
+            json_file += ".json"
+        file_path = Path.extend_or_make(json_file, prefer_script_dir=True)
+        File.create(
+            file=file_path,
+            content=Data.to_str(data, indent, compactness, as_json=True),
+            force=force,
+        )
+        return file_path
 
     @staticmethod
     def update(
         json_file: str,
-        update_values: str | list[str],
+        update_values: dict[str, Any],
         comment_start: str = ">>",
         comment_end: str = "<<",
-        sep: tuple[str, str] = ("->", "::"),
+        path_sep: 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
-        the new value at the end of the path.\n
-        In this example:
+        """Update single/multiple values inside JSON files, without needing to know the rest of the data.\n
+        ----------------------------------------------------------------------------------------------------
+        The `update_values` parameter is a dictionary, where the keys are the paths to the data to update,
+        and the values are the new values to set.\n
+        Example: For this JSON data:
         ```python
         {
-          'healthy': {
-            'fruit': ['apples', 'bananas', 'oranges'],
-            'vegetables': ['carrots', 'broccoli', 'celery']
-          }
+            "healthy": {
+                "fruit": ["apples", "bananas", "oranges"],
+                "vegetables": ["carrots", "broccoli", "celery"]
+            }
         }
         ```
-        ... 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
-        ------------------------------------------------------------------------------------------------------
+        ... the `update_values` dictionary could look like this:
+        ```python
+        {
+            # CHANGE VALUE "apples" TO "strawberries"
+            "healthy->fruit->0": "strawberries",
+            # CHANGE VALUE UNDER 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->fruit->apples`
+        as the value-path. 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->fruit->0`.\n
+        ⇾ If the given value-path 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 = [(parts[0].strip(), parts[1]) for update_value in update_values
-                         if len(parts := update_value.split(str(sep[1]).strip())) == 2]
-        value_paths, new_values = zip(*valid_entries) if valid_entries else ([], [])
+        and therefore completely ignored. If `comment_start` and `comment_end` are found inside an item, the
+        section from `comment_start` to `comment_end` is counted as a comment and ignored."""
         processed_data, data = Json.read(json_file, comment_start, comment_end, return_original=True)
-        update = []
-        for value_path, new_value in zip(value_paths, new_values):
-            path_id = Data.get_path_id(processed_data, value_path)
-            update.append(f"{path_id}::{new_value}")
-        updated = Data.set_value_by_path_id(data, update)
-        Json.create(updated, json_file, force=True)
+
+        def create_nested_path(data_obj: dict, path_keys: list[str], value: Any) -> dict:
+            current = data_obj
+            last_idx = len(path_keys) - 1
+            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).__name__}")
+                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).__name__}")
+            return data_obj
+
+        update = {}
+        for value_path, new_value in update_values.items():
+            try:
+                path_id = Data.get_path_id(
+                    data=processed_data,
+                    value_paths=value_path,
+                    path_sep=path_sep,
+                )
+                if path_id is not None:
+                    update[path_id] = new_value
+                else:
+                    keys = value_path.split(path_sep)
+                    keys = value_path.split(path_sep)
+                    data = create_nested_path(data, keys, new_value)
+            except Exception:
+                keys = value_path.split(path_sep)
+                data = create_nested_path(data, keys, new_value)
+        if "update" in locals() and update:
+            data = Data.set_value_by_path_id(data, update)
+        Json.create(json_file=json_file, data=dict(data), force=True)

xulbux/xx_path.py

@@ -6,42 +6,60 @@ import sys as _sys
 import os as _os
 
 
-# YAPF: disable
-class ProcessNotFoundError(Exception):
-    pass
+class PathNotFoundError(FileNotFoundError):
+    ...
+
 
 class _Cwd:
+
     def __get__(self, obj, owner=None):
         return _os.getcwd()
 
+
 class _ScriptDir:
+
     def __get__(self, obj, owner=None):
         if getattr(_sys, "frozen", False):
             base_path = _os.path.dirname(_sys.executable)
         else:
             main_module = _sys.modules["__main__"]
-            if hasattr(main_module, "__file__"):
+            if hasattr(main_module, "__file__") and main_module.__file__ is not None:
                 base_path = _os.path.dirname(_os.path.abspath(main_module.__file__))
-            elif (hasattr(main_module, "__spec__") and main_module.__spec__
-                    and getattr(main_module.__spec__, "origin", None)):
+            elif (hasattr(main_module, "__spec__") and main_module.__spec__ and main_module.__spec__.origin is not None):
                 base_path = _os.path.dirname(_os.path.abspath(main_module.__spec__.origin))
             else:
                 raise RuntimeError("Can only get base directory if accessed from a file.")
         return base_path
-# YAPF: enable
 
 
 class Path:
 
-    cwd: str = _Cwd()
+    cwd: str = _Cwd()  # type: ignore[assignment]
     """The path to the current working directory."""
-    script_dir: str = _ScriptDir()
+    script_dir: str = _ScriptDir()  # type: ignore[assignment]
     """The path to the directory of the current script."""
 
     @staticmethod
-    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
+    def extend(
+        rel_path: str,
+        search_in: Optional[str | list[str]] = None,
+        raise_error: bool = False,
+        use_closest_match: bool = False,
+    ) -> Optional[str]:
+        """Tries to locate and extend a relative path to an absolute path.\n
+        --------------------------------------------------------------------------------
+        If the `rel_path` couldn't be located in predefined directories, it will be
+        searched in the `search_in` directory/s. If the `rel_path` is still not found,
+        it returns `None` or raises a `PathNotFoundError` if `raise_error` is true.\n
+        --------------------------------------------------------------------------------
+        If `use_closest_match` is true, it is possible to have typos in the `search_in`
+        path/s and it will still find the file if it is under one of those paths."""
+        if rel_path in (None, ""):
+            if raise_error:
+                raise PathNotFoundError("Path is empty.")
+            return None
+        elif _os.path.isabs(rel_path):
+            return rel_path
 
         def get_closest_match(dir: str, part: str) -> Optional[str]:
             try:
@@ -56,7 +74,7 @@ class Path:
             for part in parts:
                 if _os.path.isfile(current):
                     return current
-                closest_match = get_closest_match(current, part) if correct_path else part
+                closest_match = get_closest_match(current, part) if use_closest_match else part
                 current = _os.path.join(current, closest_match) if closest_match else None
                 if current is None:
                     return None
@@ -71,20 +89,20 @@ class Path:
                     parts[i] = _os.environ[parts[i].upper()]
             return "".join(parts)
 
-        path = _os.path.normpath(expand_env_path(path))
-        if _os.path.isabs(path):
-            drive, rel_path = _os.path.splitdrive(path)
+        rel_path = _os.path.normpath(expand_env_path(rel_path))
+        if _os.path.isabs(rel_path):
+            drive, rel_path = _os.path.splitdrive(rel_path)
             rel_path = rel_path.lstrip(_os.sep)
-            search_dirs = (drive + _os.sep) if drive else [_os.sep]
+            search_dirs = [(drive + _os.sep) if drive else _os.sep]
         else:
-            rel_path = path.lstrip(_os.sep)
+            rel_path = rel_path.lstrip(_os.sep)
             base_dir = Path.script_dir
-            search_dirs = (
+            search_dirs = [
                 _os.getcwd(),
                 base_dir,
                 _os.path.expanduser("~"),
                 _tempfile.gettempdir(),
-            )
+            ]
         if search_in:
             search_dirs.extend([search_in] if isinstance(search_in, str) else search_in)
         path_parts = rel_path.split(_os.sep)
@@ -92,19 +110,51 @@ class Path:
             full_path = _os.path.join(search_dir, rel_path)
             if _os.path.exists(full_path):
                 return full_path
-            match = find_path(search_dir, path_parts) if correct_path else None
+            match = find_path(search_dir, path_parts) if use_closest_match else None
             if match:
                 return match
         if raise_error:
-            raise FileNotFoundError(f"Path '{path}' not found in specified directories.")
-        return _os.path.join(search_dirs[0], rel_path)
+            raise PathNotFoundError(f"Path '{rel_path}' not found in specified directories.")
+        return None
+
+    @staticmethod
+    def extend_or_make(
+        rel_path: str,
+        search_in: Optional[str | list[str]] = None,
+        prefer_script_dir: bool = True,
+        use_closest_match: bool = False,
+    ) -> str:
+        """Tries to locate and extend a relative path to an absolute path, and if the `rel_path`
+        couldn't be located, it generates a path, as if it was located.\n
+        -----------------------------------------------------------------------------------------
+        If the `rel_path` couldn't be located in predefined directories, it will be searched in
+        the `search_in` directory/s. If the `rel_path` is still not found, it will makes a path
+        that points to where the `rel_path` would be in the script directory, even though the
+        `rel_path` doesn't exist there. If `prefer_script_dir` is false, it will instead make a
+        path that points to where the `rel_path` would be in the CWD.\n
+        -----------------------------------------------------------------------------------------
+        If `use_closest_match` is true, it is possible to have typos in the `search_in` path/s
+        and it will still find the file if it is under one of those paths."""
+        try:
+            return str(Path.extend(rel_path, search_in, raise_error=True, use_closest_match=use_closest_match))
+        except PathNotFoundError:
+            normalized_rel_path = _os.path.normpath(rel_path)
+            base = Path.script_dir if prefer_script_dir else _os.getcwd()
+            return _os.path.join(base, normalized_rel_path)
 
     @staticmethod
     def remove(path: str, only_content: bool = False) -> None:
+        """Removes the directory or the directory's content at the specified path.\n
+        -----------------------------------------------------------------------------
+        Normally it removes the directory and its content, but if `only_content` is
+        true, the directory is kept and only its contents are removed."""
         if not _os.path.exists(path):
             return None
         if not only_content:
-            _shutil.rmtree(path)
+            if _os.path.isfile(path) or _os.path.islink(path):
+                _os.unlink(path)
+            elif _os.path.isdir(path):
+                _shutil.rmtree(path)
         elif _os.path.isdir(path):
             for filename in _os.listdir(path):
                 file_path = _os.path.join(path, filename)

xulbux/xx_regex.py

@@ -1,11 +1,12 @@
-"""
-Very useful and complicated (generated) regex patterns.
-"""
-
+from typing import TypeAlias, Optional
 import regex as _rx
 import re as _re
 
 
+Pattern: TypeAlias = _re.Pattern[str] | _rx.Pattern[str]
+Match: TypeAlias = _re.Match[str] | _rx.Match[str]
+
+
 class Regex:
 
     @staticmethod
@@ -67,7 +68,7 @@ class Regex:
         return rf'({"" if is_group else "?:"}(?:(?!{ignore_pattern}).)*(?:(?!{Regex.outside_strings(disallowed_pattern)}).)*)'
 
     @staticmethod
-    def func_call(func_name: str = None) -> str:
+    def func_call(func_name: Optional[str] = None) -> str:
         """Match a function call, and get back two groups:
         1. function name
         2. the function's arguments\n
@@ -93,7 +94,7 @@ class Regex:
         - `r` 0-255 (int: red)
         - `g` 0-255 (int: green)
         - `b` 0-255 (int: blue)
-        - `a` 0-1 (float: opacity)\n
+        - `a` 0.0-1.0 (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."""
@@ -126,7 +127,7 @@ class Regex:
         - `h` 0-360 (int: hue)
         - `s` 0-100 (int: saturation)
         - `l` 0-100 (int: lightness)
-        - `a` 0-1 (float: opacity)\n
+        - `a` 0.0-1.0 (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."""
@@ -134,9 +135,9 @@ class Regex:
             fix_sep = r"[^0-9A-Z]"
         else:
             fix_sep = _re.escape(fix_sep)
-        hsl_part = rf"""((?:0*(?:360|3[0-5][0-9]|[12][0-9][0-9]|[1-9]?[0-9])))
-            (?:\s*{fix_sep}\s*)((?:0*(?:100|[1-9][0-9]|[0-9])))
-            (?:\s*{fix_sep}\s*)((?:0*(?:100|[1-9][0-9]|[0-9])))"""
+        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*%)?)"""
         return (
             rf"""(?ix)
             (?:hsl|hsla)?\s*(?:\(?\s*{hsl_part}