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

xulbux/xx_console.py

@@ -15,8 +15,8 @@ Functions for logging and other small actions within the console:
 - `Console.confirm()`
 - `Console.restricted_input()`
 - `Console.pwd_input()`\n
-----------------------------------------------------------------------------------------------------------
-You can also use special formatting codes directly inside the log message to change their appearance.<br>
+------------------------------------------------------------------------------------------------------
+You can also use special formatting codes directly inside the log message to change their appearance.
 For more detailed information about formatting codes, see the the `xx_format_codes` description.
 """
 
@@ -29,7 +29,6 @@ from contextlib import suppress
 import pyperclip as _pyperclip
 import keyboard as _keyboard
 import getpass as _getpass
-import ctypes as _ctypes
 import shutil as _shutil
 import mouse as _mouse
 import sys as _sys
@@ -67,17 +66,6 @@ class Console:
     def user() -> str:
         return _os.getenv("USER") or _os.getenv("USERNAME") or _getpass.getuser()
 
-    def is_admin() -> bool:
-        try:
-            if _os.name == "nt":
-                return _ctypes.windll.shell32.IsUserAnAdmin() != 0
-            elif _os.name == "posix":
-                return _os.geteuid() == 0
-            else:
-                return False
-        except Exception:
-            return False
-
     @staticmethod
     def pause_exit(
         pause: bool = False,
@@ -86,9 +74,8 @@ class Console:
         exit_code: int = 0,
         reset_ansi: bool = False,
     ) -> None:
-        """Will print the `last_prompt` and then pause the program if `pause` is set<br>
-        to `True` and after the pause, exit the program if `exit` is set to `True`.
-        """
+        """Will print the `last_prompt` and then pause the program if `pause` is set
+        to `True` and after the pause, exit the program if `exit` is set to `True`."""
         print(prompt, end="", flush=True)
         if reset_ansi:
             FormatCodes.print("[_]", end="")
@@ -114,17 +101,16 @@ class Console:
         title_bg_color: hexa | rgba = None,
         default_color: hexa | rgba = None,
     ) -> None:
-        """Will print a formatted log message:<br>
-        `title` -⠀the title of the log message (e.g. `DEBUG`, `WARN`, `FAIL`, etc.)<br>
-        `prompt` -⠀the log message<br>
-        `start` -⠀something to print before the log is printed<br>
-        `end` -⠀something to print after the log is printed (e.g. `\\n\\n`)<br>
-        `title_bg_color` -⠀the background color of the `title`<br>
-        `default_color` -⠀the default text color of the `prompt`\n
+        """Will print a formatted log message:
+        - `title` -⠀the title of the log message (e.g. `DEBUG`, `WARN`, `FAIL`, etc.)
+        - `prompt` -⠀the log message
+        - `start` -⠀something to print before the log is printed
+        - `end` -⠀something to print after the log is printed (e.g. `\\n\\n`)
+        - `title_bg_color` -⠀the background color of the `title`
+        - `default_color` -⠀the default text color of the `prompt`\n
         --------------------------------------------------------------------------------
-        The log message supports special formatting codes. For more detailed<br>
-        information about formatting codes, see `xx_format_codes` class description.
-        """
+        The log message supports special formatting codes. For more detailed
+        information about formatting codes, see `xx_format_codes` class description."""
         title_color = "_color" if not title_bg_color else Color.text_color_for_on_bg(title_bg_color)
         if title:
             FormatCodes.print(
@@ -150,7 +136,7 @@ class Console:
         pause: bool = False,
         exit: bool = False,
     ) -> None:
-        """A preset for `log()`: `DEBUG` log message with the options to pause<br>
+        """A preset for `log()`: `DEBUG` log message with the options to pause
         at the message and exit the program after the message was printed."""
         if active:
             Console.log("DEBUG", prompt, start, end, title_bg_color, default_color)
@@ -166,7 +152,7 @@ class Console:
         pause: bool = False,
         exit: bool = False,
     ) -> None:
-        """A preset for `log()`: `INFO` log message with the options to pause<br>
+        """A preset for `log()`: `INFO` log message with the options to pause
         at the message and exit the program after the message was printed."""
         Console.log("INFO", prompt, start, end, title_bg_color, default_color)
         Console.pause_exit(pause, exit)
@@ -181,7 +167,7 @@ class Console:
         pause: bool = False,
         exit: bool = False,
     ) -> None:
-        """A preset for `log()`: `DONE` log message with the options to pause<br>
+        """A preset for `log()`: `DONE` log message with the options to pause
         at the message and exit the program after the message was printed."""
         Console.log("DONE", prompt, start, end, title_bg_color, default_color)
         Console.pause_exit(pause, exit)
@@ -196,7 +182,7 @@ class Console:
         pause: bool = False,
         exit: bool = False,
     ) -> None:
-        """A preset for `log()`: `WARN` log message with the options to pause<br>
+        """A preset for `log()`: `WARN` log message with the options to pause
         at the message and exit the program after the message was printed."""
         Console.log("WARN", prompt, start, end, title_bg_color, default_color)
         Console.pause_exit(pause, exit)
@@ -212,7 +198,7 @@ class Console:
         exit: bool = True,
         reset_ansi=True,
     ) -> None:
-        """A preset for `log()`: `FAIL` log message with the options to pause<br>
+        """A preset for `log()`: `FAIL` log message with the options to pause
         at the message and exit the program after the message was printed."""
         Console.log("FAIL", prompt, start, end, title_bg_color, default_color)
         Console.pause_exit(pause, exit, reset_ansi=reset_ansi)
@@ -228,7 +214,7 @@ class Console:
         exit: bool = True,
         reset_ansi=True,
     ) -> None:
-        """A preset for `log()`: `EXIT` log message with the options to pause<br>
+        """A preset for `log()`: `EXIT` log message with the options to pause
         at the message and exit the program after the message was printed."""
         Console.log("EXIT", prompt, start, end, title_bg_color, default_color)
         Console.pause_exit(pause, exit, reset_ansi=reset_ansi)
@@ -242,10 +228,9 @@ class Console:
         default_is_yes: bool = True,
     ) -> bool:
         """Ask a yes/no question.\n
-        -----------------------------------------------------------------------------------
-        The question can be formatted with special formatting codes. For more detailed<br>
-        information about formatting codes, see the `xx_format_codes` description.
-        """
+        -------------------------------------------------------------------------------
+        The question can be formatted with special formatting codes. For more detailed
+        information about formatting codes, see the `xx_format_codes` description."""
         confirmed = input(
             FormatCodes.to_ansi(
                 f'{start}  {str(prompt)} [_|dim](({"Y" if default_is_yes else "y"}/{"n" if default_is_yes else "N"}):  )',
@@ -271,9 +256,8 @@ class Console:
         - optional mask character (hide user input, e.g. for passwords)
         - reset the ANSI formatting codes after the user continues\n
         -----------------------------------------------------------------------------------
-        The input can be formatted with special formatting codes. For more detailed<br>
-        information about formatting codes, see the `xx_format_codes` description.
-        """
+        The input can be formatted with special formatting codes. For more detailed
+        information about formatting codes, see the `xx_format_codes` description."""
         FormatCodes.print(prompt, end="", flush=True)
         result = ""
         select_all = False
@@ -377,5 +361,6 @@ class Console:
         max_len: int = None,
         _reset_ansi: bool = True,
     ) -> str:
-        """Password input that masks the entered characters with asterisks."""
+        """Password input (preset for `Console.restricted_input()`)
+        that always masks the entered characters with asterisks."""
         return Console.restricted_input(prompt, allowed_chars, min_len, max_len, "*", _reset_ansi)

xulbux/xx_data.py

@@ -26,7 +26,7 @@ class Data:
 
     @staticmethod
     def remove_empty_items(data: DataStructure, spaces_are_empty: bool = False) -> DataStructure:
-        """Removes empty items from the data structure.<br>
+        """Removes empty items from the data structure.
         If `spaces_are_empty` is true, it will count items with only spaces as empty."""
         if isinstance(data, dict):
             return {
@@ -79,14 +79,15 @@ class Data:
         comment_sep: str = "",
     ) -> DataStructure:
         """Remove comments from a list, tuple or dictionary.\n
-        --------------------------------------------------------------------------------------------------------------------
-        The `data` parameter is your list, tuple or dictionary, where the comments should get removed from.<br>
-        The `comment_start` parameter is the string that marks the start of a comment inside `data`. (default: `>>`)<br>
-        The `comment_end` parameter is the string that marks the end of a comment inside `data`. (default: `<<`)<br>
-        The `comment_sep` parameter is a string with which a comment will be replaced, if it is in the middle of a value.\n
-        --------------------------------------------------------------------------------------------------------------------
-        Examples:\n
-        ```python\n data = {
+        ----------------------------------------------------------------------------------------------------------------------
+        - The `data` parameter is your list, tuple or dictionary, where the comments should get removed from.
+        - The `comment_start` parameter is the string that marks the start of a comment inside `data`. (default: `>>`)
+        - The `comment_end` parameter is the string that marks the end of a comment inside `data`. (default: `<<`)
+        - The `comment_sep` parameter is a string with which a comment will be replaced, if it is in the middle of a value.\n
+        ----------------------------------------------------------------------------------------------------------------------
+        Examples:
+        ```python
+        data = {
             "key1": [
                 ">> COMMENT IN THE BEGINNING OF THE STRING <<  value1",
                 "value2  >> COMMENT IN THE END OF THE STRING",
@@ -106,24 +107,25 @@ class Data:
             comment_start=">>",
             comment_end="<<",
             comment_sep="__"
-        )\n```
-        --------------------------------------------------------------------------------------------------------------------
+        )
+        ```\n
+        ----------------------------------------------------------------------------------------------------------------------
         For this example, `processed_data` will be:
-        ```python\n {
+        ```python
+        {
             "key1": [
                 "value1",
                 "value2",
                 "val__ue3"
             ],
             "key3": None
-        }\n```
-        For `key1`, all the comments will just be removed, except at `value3` and `value4`:<br>
-         `value3` The comment is removed and the parts left and right are joined through `comment_sep`.<br>
-         `value4` The whole value is removed, since the whole value was a comment.<br>
-        For `key2`, the key, including its whole values will be removed.<br>
-        For `key3`, since all its values are just comments, the key will still exist, but with a value of `None`.
-        """
-
+        }
+        ```\n
+        - For `key1`, all the comments will just be removed, except at `value3` and `value4`:
+          - `value3` The comment is removed and the parts left and right are joined through `comment_sep`.
+          - `value4` The whole value is removed, since the whole value was a comment.
+        - For `key2`, the key, including its whole values will be removed.
+        - For `key3`, since all its values are just comments, the key will still exist, but with a value of `None`."""
         if comment_end:
             pattern = _re.compile(
                 rf"^((?:(?!{_re.escape(comment_start)}).)*){_re.escape(comment_start)}(?:(?:(?!{_re.escape(comment_end)}).)*)(?:{_re.escape(comment_end)})?(.*?)$"
@@ -163,13 +165,13 @@ class Data:
         comment_end: str = "<<",
     ) -> bool:
         """Compares two structures and returns `True` if they are equal and `False` otherwise.\n
-        ⇾ **Will not detect, if a key-name has changed, only if removed or added.**\n
-        ------------------------------------------------------------------------------------------------
-        Ignores the specified (found) key/s or item/s from `ignore_paths`. Comments are not ignored<br>
-        when comparing. `comment_start` and `comment_end` are only used to correctly recognize the<br>
+        ⇾ Will not detect, if a key-name has changed, only if removed or added.\n
+        --------------------------------------------------------------------------------------------
+        Ignores the specified (found) key/s or item/s from `ignore_paths`. Comments are not ignored
+        when comparing. `comment_start` and `comment_end` are only used to correctly recognize the
         keys in the `ignore_paths`.\n
-        ------------------------------------------------------------------------------------------------
-        The paths from `ignore_paths` and the `path_sep` parameter work exactly the same way as for<br>
+        --------------------------------------------------------------------------------------------
+        The paths from `ignore_paths` and the `path_sep` parameter work exactly the same way as for
         the function `Data.get_path_id()`. See its documentation for more details."""
 
         def process_ignore_paths(
@@ -222,26 +224,28 @@ class Data:
         -------------------------------------------------------------------------------------------------
         The `data` parameter is the list, tuple, or dictionary, which the id should be generated for.\n
         -------------------------------------------------------------------------------------------------
-        The param `value_path` is a sort of path (or a list of paths) to the value/s to be updated.<br>
+        The param `value_path` is a sort of path (or a list of paths) to the value/s to be updated.
         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"`, the value path<br>
-        would be `healthy->fruit->apples` or if you don't know that the value is `"apples"`<br>
-        you can also use the index of the value, so `healthy->fruit->0`.\n
+        }
+        ```
+        ... if you want to change the value of `"apples"` to `"strawberries"`, the value path would be
+        `healthy->fruit->apples` or if you don't know that the value is `"apples"` you can also use the
+        index of the value, so `healthy->fruit->0`.\n
         -------------------------------------------------------------------------------------------------
-        The comments marked with `comment_start` and `comment_end` will be removed,<br>
-        before trying to get the path id.\n
+        The comments marked with `comment_start` and `comment_end` will be removed, before trying to get
+        the path id.\n
         -------------------------------------------------------------------------------------------------
-        The `path_sep` param is the separator between the keys/indexes in the path<br>
-        (default is `->` just like in the example above).\n
+        The `path_sep` param is the separator between the keys/indexes in the path (default is `->` just
+        like in the example above).\n
         -------------------------------------------------------------------------------------------------
-        If `ignore_not_found` is `True`, the function will return `None` if the value is not<br>
-        found instead of raising an error."""
+        If `ignore_not_found` is `True`, the function will return `None` if the value is not found
+        instead of raising an error."""
 
         def process_path(path: str, data_obj: list | tuple | set | frozenset | dict) -> str | None:
             keys = path.split(path_sep)
@@ -289,11 +293,11 @@ class Data:
     @staticmethod
     def get_value_by_path_id(data: DataStructure, path_id: str, get_key: bool = False) -> any:
         """Retrieves the value from `data` using the provided `path_id`.\n
-        ----------------------------------------------------------------------------------------------------
-        Input your `data` along with a `path_id` that was created before using `Data.get_path_id()`.<br>
+        -------------------------------------------------------------------------------------------------
+        Input your `data` along with a `path_id` that was created before using `Data.get_path_id()`.
         If `get_key` is true and the final item is in a dict, it returns the key instead of the value.\n
-        ----------------------------------------------------------------------------------------------------
-        The function will return the value (or key) from the path ID location, as long as the structure<br>
+        -------------------------------------------------------------------------------------------------
+        The function will return the value (or key) from the path ID location, as long as the structure
         of `data` hasn't changed since creating the path ID to that value."""
 
         def get_nested(data: list | tuple | set | frozenset | dict, path: list[int], get_key: bool) -> any:
@@ -326,12 +330,12 @@ class Data:
     ) -> list | tuple | dict:
         """Updates the value/s from `update_values` in the `data`.\n
         --------------------------------------------------------------------------------
-        Input a list, tuple or dict as `data`, along with `update_values`, which is<br>
-        a path ID that was created before using `Data.get_path_id()`, together<br>
-        with the new value to be inserted where the path ID points to. The path ID<br>
-        and the new value are separated by `sep`, which per default is `::`.\n
+        Input a list, tuple or dict as `data`, along with `update_values`, which is a
+        path ID that was created before using `Data.get_path_id()`, together with the
+        new value to be inserted where the path ID points to. The path ID and the new
+        value are separated by `sep`, which per default is `::`.\n
         --------------------------------------------------------------------------------
-        The value from path ID will be changed to the new value, as long as the<br>
+        The value from path ID will be changed to the new value, as long as the
         structure of `data` hasn't changed since creating the path ID to that value."""
 
         def update_nested(
@@ -383,16 +387,15 @@ class Data:
         end: str = "\n",
     ) -> None:
         """Print nicely formatted data structures.\n
-        ------------------------------------------------------------------------------------
-        The indentation spaces-amount can be set with with `indent`.<br>
-        There are three different levels of `compactness`:<br>
-        `0` expands everything possible<br>
-        `1` only expands if there's other lists, tuples or dicts inside of data or,<br>
-         ⠀if the data's content is longer than `max_width`<br>
-        `2` keeps everything collapsed (all on one line)\n
-        ------------------------------------------------------------------------------------
-        If `as_json` is set to `True`, the output will be in valid JSON format.
-        """
+        ------------------------------------------------------------------------------
+        The indentation spaces-amount can be set with with `indent`.
+        There are three different levels of `compactness`:
+        - `0` expands everything possible
+        - `1` only expands if there's other lists, tuples or dicts inside of data or,
+          if the data's content is longer than `max_width`
+        - `2` keeps everything collapsed (all on one line)\n
+        ------------------------------------------------------------------------------
+        If `as_json` is set to `True`, the output will be in valid JSON format."""
         print(
             Data.to_str(data, indent, compactness, sep, max_width, as_json),
             end=end,
@@ -409,14 +412,14 @@ class Data:
         as_json: bool = False,
     ) -> str:
         """Get nicely formatted data structure-strings.\n
-        ------------------------------------------------------------------------------------
-        The indentation spaces-amount can be set with with `indent`.<br>
-        There are three different levels of `compactness`:<br>
-        `0` expands everything possible<br>
-        `1` only expands if there's other lists, tuples or dicts inside of data or,<br>
-         ⠀if the data's content is longer than `max_width`<br>
-        `2` keeps everything collapsed (all on one line)\n
-        ------------------------------------------------------------------------------------
+        ------------------------------------------------------------------------------
+        The indentation spaces-amount can be set with with `indent`.
+        There are three different levels of `compactness`:
+        - `0` expands everything possible
+        - `1` only expands if there's other lists, tuples or dicts inside of data or,
+          if the data's content is longer than `max_width`
+        - `2` keeps everything collapsed (all on one line)\n
+        ------------------------------------------------------------------------------
         If `as_json` is set to `True`, the output will be in valid JSON format."""
 
         def format_value(value: any, current_indent: int) -> str:
@@ -495,7 +498,7 @@ class Data:
     def _is_key(data: DataStructure, path_id: str) -> bool:
         """Returns `True` if the path ID points to a key in `data` and `False` otherwise.\n
         ------------------------------------------------------------------------------------
-        Input a list, tuple or dict as `data`, along with `path_id`, which is a path ID<br>
+        Input a list, tuple or dict as `data`, along with `path_id`, which is a path ID
         that was created before using `Data.get_path_id()`."""
 
         def check_nested(data: list | tuple | set | frozenset | dict, path: list[int]) -> bool:

xulbux/xx_env_path.py

@@ -8,8 +8,8 @@ Functions for modifying and checking the systems environment-variables:
 
 from .xx_path import Path
 
-import os as _os
 import sys as _sys
+import os as _os
 
 
 class EnvPath:
@@ -60,9 +60,9 @@ class EnvPath:
         cwd: bool = False,
         base_dir: bool = False,
     ) -> list:
-        """Get and/or normalize the paths.<br>
-        Raise an error if no path is provided and<br>
-        neither `cwd` or `base_dir` is `True`."""
+        """Get and/or normalize the paths.\n
+        ------------------------------------------------------------------------------------
+        Raise an error if no path is provided and neither `cwd` or `base_dir` is `True`."""
         if cwd:
             path = _os.getcwd()
         elif base_dir:

xulbux/xx_file.py

@@ -7,20 +7,31 @@ import os as _os
 class File:
 
     @staticmethod
-    def rename_extension(file_path: str, new_extension: str) -> str:
-        directory, filename_with_ext = _os.path.split(file_path)
+    def rename_extension(
+        file: str,
+        new_extension: str,
+        camel_case_filename: bool = False,
+    ) -> str:
+        """Rename the extension of a file.\n
+        --------------------------------------------------------------------------
+        If the `camel_case_filename` parameter is true, the filename will be made
+        CamelCase in addition to changing the files extension."""
+        directory, filename_with_ext = _os.path.split(file)
         filename = filename_with_ext.split(".")[0]
-        camel_case_filename = String.to_camel_case(filename)
-        new_filename = f"{camel_case_filename}{new_extension}"
-        new_file_path = _os.path.join(directory, new_filename)
-        return new_file_path
+        if camel_case_filename:
+            filename = String.to_camel_case(filename)
+        return _os.path.join(directory, f"{filename}{new_extension}")
 
     @staticmethod
-    def create(content: str = "", file: str = "new_file.txt", force: bool = False) -> str:
+    def create(
+        file: str,
+        content: str = "",
+        force: bool = False,
+    ) -> str:
         """Create a file with ot without content.\n
-        ----------------------------------------------------------------------------
-        The function will throw a `FileExistsError` if the file already exists.<br>
-        To overwrite the file, set the `force` parameter to `True`."""
+        ------------------------------------------------------------------------
+        The function will throw a `FileExistsError` if the file already exists.
+        To always overwrite the file, set the `force` parameter to `True`."""
         if _os.path.exists(file) and not force:
             with open(file, "r", encoding="utf-8") as existing_file:
                 existing_content = existing_file.read()
@@ -33,24 +44,22 @@ class File:
         return full_path
 
     @staticmethod
-    def make_path(
-        filename: str,
-        filetype: str,
+    def extend_or_make_path(
+        file: str,
         search_in: str | list[str] = None,
         prefer_base_dir: bool = True,
-        correct_path: bool = False,
+        correct_paths: bool = False,
     ) -> str:
-        """Create the path to a file in the cwd, the base-dir, or predefined directories.\n
-        --------------------------------------------------------------------------------------
-        If the `filename` is not found in the above directories, it will be searched<br>
-        in the `search_in` directory/directories. If the file is still not found, it will<br>
-        return the path to the file in the base-dir per default or to the file in the<br>
-        cwd if `prefer_base_dir` is set to `False`."""
-        if not filename.lower().endswith(f".{filetype.lower()}"):
-            filename = f"{filename}.{filetype.lower()}"
+        """Tries to find the file and extend the path to be absolute and if the file was not found:\n
+        Generate the absolute path to the file in the CWD or the running program's base-directory.\n
+        ----------------------------------------------------------------------------------------------
+        If the `file` is not found in the above directories, it will be searched in the `search_in`
+        directory/directories. If the file is still not found, it will return the path to the file in
+        the base-dir per default or to the file in the CWD if `prefer_base_dir` is set to `False`.\n
+        ----------------------------------------------------------------------------------------------
+        If `correct_paths` 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 Path.extend(filename, search_in, True, correct_path)
+            return Path.extend(file, search_in, raise_error=True, correct_path=correct_paths)
         except FileNotFoundError:
-            return (
-                _os.path.join(Path.get(base_dir=True), filename) if prefer_base_dir else _os.path.join(_os.getcwd(), filename)
-            )
+            return _os.path.join(Path.get(base_dir=True), file) if prefer_base_dir else _os.path.join(_os.getcwd(), file)