xulbux 1.6.6__py3-none-any.whl → 1.6.7__py3-none-any.whl

xulbux/__init__.py

@@ -19,7 +19,7 @@
   • REGEX PATTERN TEMPLATES  xx.Regex
 """
 
-__version__ = "1.6.6"
+__version__ = "1.6.7"
 __author__ = "XulbuX"
 __email__ = "xulbux.real@gmail.com"
 __license__ = "MIT"

xulbux/_consts_.py

@@ -3,13 +3,16 @@ from typing import TypeAlias
 
 
 FormattableString: TypeAlias = str
+"""A `str` object that is made to be formatted with the `.format()` method."""
 
 
 @dataclass
 class COLOR:
-    """Color presets used in the XulbuX library."""
+    """Color presets used in the `xulbux` library."""
 
     text = "#A5D6FF"
+    """The default text color used in the `xulbux` library."""
+
     white = "#F1F2FF"
     lightgray = "#B6B7C0"
     gray = "#7B7C8D"
@@ -21,6 +24,7 @@ class COLOR:
     tangerine = "#FF9962"
     gold = "#FFAF60"
     yellow = "#FFD260"
+    lime = "#C9F16E"
     green = "#7EE787"
     teal = "#50EAAF"
     cyan = "#3EDEE6"
@@ -40,50 +44,67 @@ class _AllTextCharacters:
 
 @dataclass
 class CHARS:
-    """Strings with only certain text characters."""
+    """Text character sets."""
 
-    # CODE TO SIGNAL, ALL CHARACTERS ARE ALLOWED
     all = _AllTextCharacters
+    """Code to signal that all characters are allowed."""
 
-    # DIGIT SETS
     digits: str = "0123456789"
+    """Digits: `0`-`9`"""
     float_digits: str = digits + "."
+    """Digits: `0`-`9` with decimal point `.`"""
     hex_digits: str = digits + "#abcdefABCDEF"
+    """Digits: `0`-`9` Letters: `a`-`f` `A`-`F` and a hashtag `#`"""
 
-    # LETTER CATEGORIES
     lowercase: str = "abcdefghijklmnopqrstuvwxyz"
+    """Lowercase letters `a`-`z`"""
     lowercase_extended: str = lowercase + "äëïöüÿàèìòùáéíóúýâêîôûãñõåæç"
+    """Lowercase letters `a`-`z` with all lowercase diacritic letters."""
     uppercase: str = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    """Uppercase letters `A`-`Z`"""
     uppercase_extended: str = uppercase + "ÄËÏÖÜÀÈÌÒÙÁÉÍÓÚÝÂÊÎÔÛÃÑÕÅÆÇß"
+    """Uppercase letters `A`-`Z` with all uppercase diacritic letters."""
 
-    # COMBINED LETTER SETS
     letters: str = lowercase + uppercase
+    """Lowercase and uppercase letters `a`-`z` and `A`-`Z`"""
     letters_extended: str = lowercase_extended + uppercase_extended
+    """Lowercase and uppercase letters `a`-`z` `A`-`Z` and all diacritic letters."""
 
-    # ASCII sets
     special_ascii: str = " !\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
+    """All ASCII special characters."""
     special_ascii_extended: str = special_ascii + "ø£Ø׃ªº¿®¬½¼¡«»░▒▓│┤©╣║╗╝¢¥┐└┴┬├─┼╚╔╩╦╠═╬¤ðÐı┘┌█▄¦▀µþÞ¯´≡­±‗¾¶§÷¸°¨·¹³²■ "
+    """All ASCII special characters with the extended ASCII special characters."""
     standard_ascii: str = special_ascii + digits + letters
+    """All standard ASCII characters."""
     full_ascii: str = special_ascii_extended + digits + letters_extended
+    """All characters in the ASCII table."""
 
 
 class ANSI:
     """Constants and class-methods for use of ANSI escape codes."""
 
     escaped_char: str = "\\x1b"
+    """The printable ANSI escape character."""
     CHAR = char = "\x1b"
+    """The ANSI escape character."""
     START = start = "["
+    """The start of an ANSI escape sequence."""
     SEP = sep = ";"
+    """The separator between ANSI escape sequence parts."""
     END = end = "m"
+    """The end of an ANSI escape sequence."""
     default_color_modifiers: dict[str, str] = {"lighten": "+l", "darken": "-d"}
+    """Characters to modify the lightness of the default color with."""
 
     @classmethod
-    def seq(cls, parts: int = 1) -> str:
+    def seq(cls, parts: int = 1) -> FormattableString:
         """Generate an ANSI sequence with `parts` amount of placeholders."""
         return cls.CHAR + cls.START + cls.SEP.join(["{}" for _ in range(parts)]) + cls.END
 
     seq_color: FormattableString = CHAR + START + "38" + SEP + "2" + SEP + "{}" + SEP + "{}" + SEP + "{}" + END
+    """The ANSI escape sequence for setting the text RGB color."""
     seq_bg_color: FormattableString = CHAR + START + "48" + SEP + "2" + SEP + "{}" + SEP + "{}" + SEP + "{}" + END
+    """The ANSI escape sequence for setting the background RGB color."""
 
     color_map: list[str] = [
         ########### DEFAULT CONSOLE COLOR NAMES ############
@@ -96,6 +117,7 @@ class ANSI:
         "cyan",
         "white",
     ]
+    """The console default color names."""
 
     codes_map: dict[str | tuple[str, ...], int] = {
         ################# SPECIFIC RESETS ##################
@@ -156,3 +178,4 @@ class ANSI:
         "bg:br:cyan": 106,
         "bg:br:white": 107,
     }
+    """All custom format keys and their corresponding ANSI format number codes."""

xulbux/xx_console.py

@@ -39,18 +39,64 @@ class _ConsoleSize:
 class _ConsoleUser:
     def __get__(self, obj, owner=None):
         return _os.getenv("USER") or _os.getenv("USERNAME") or _getpass.getuser()
+
+class ArgResult:
+    """Exists: if the argument was found or not\n
+    Value: the value from behind the found argument"""
+    def __init__(self, exists: bool, value: any):
+        self.exists = exists
+        self.value = value
+
+class Args:
+    """Stores arguments under their aliases with their results."""
+    def __init__(self, **kwargs):
+        for key, value in kwargs.items():
+            if not key.isidentifier():
+                raise TypeError(f"Argument alias '{key}' is invalid. It must be a valid Python variable name.")
+            setattr(self, key, ArgResult(**value))
 # YAPF: enable
 
 
 class Console:
 
     w: int = _ConsoleWidth()
+    """The width of the console in characters."""
     h: int = _ConsoleHeight()
+    """The height of the console in lines."""
     wh: tuple[int, int] = _ConsoleSize()
+    """A tuple with the width and height of
+    the console in characters and lines."""
     usr: str = _ConsoleUser()
+    """The name of the current user."""
 
     @staticmethod
-    def get_args(find_args: dict) -> dict[str, dict[str, any]]:
+    def get_args(find_args: dict[str, list[str] | tuple[str, ...]]) -> Args:
+        """Will search for the specified arguments in the command line
+        arguments and return the results as a special `Args` object.\n
+        ----------------------------------------------------------------
+        The `find_args` dictionary should have the following structure:
+        ```python
+        find_args={
+            "arg1_alias": ["-a1", "--arg1", "--argument-1"],
+            "arg2_alias": ("-a2", "--arg2", "--argument-2"),
+            ...
+        }
+        ```
+        And if the script is called via the command line:\n
+        `python script.py -a1 "argument value" --arg2`\n
+        ...it would return the following `Args` object:
+        ```python
+        Args(
+            arg1_alias=ArgResult(exists=True, value="argument value"),
+            arg2_alias=ArgResult(exists=True, value=None),
+            ...
+        )
+        ```
+        ...which can be accessed like this:\n
+        - `Args.<arg_alias>.exists` is `True` if any of the specified
+            args were found and `False` if not
+        - `Args.<arg_alias>.value` the value from behind the found arg,
+            `None` if no value was found"""
         args = _sys.argv[1:]
         results = {}
         for arg_key, arg_group in find_args.items():
@@ -64,7 +110,7 @@ class Console:
                         value = String.to_type(args[arg_index + 1])
                     break
             results[arg_key] = {"exists": exists, "value": value}
-        return results
+        return Args(**results)
 
     @staticmethod
     def pause_exit(
@@ -111,7 +157,8 @@ class Console:
         - `start` -⠀something to print before the log is printed
         - `end` -⠀something to print after the log is printed (e.g. `\\n`)
         - `title_bg_color` -⠀the background color of the `title`
-        - `default_color` -⠀the default text color of the `prompt`\n
+        - `default_color` -⠀the default text color of the `prompt`
+        - `_console_tabsize` -⠀the tab size of the console (default is 8)\n
         -----------------------------------------------------------------------------------
         The log message can be formatted with special formatting codes. For more detailed
         information about formatting codes, see `xx_format_codes` module documentation."""
@@ -253,7 +300,7 @@ class Console:
         - `*values` -⠀the box content (each value is on a new line)
         - `start` -⠀something to print before the log box is printed
         - `end` -⠀something to print after the log box is printed (e.g. `\\n`)
-        - `box_bg_color` -⠀the box's background color
+        - `box_bg_color` -⠀the background color of the box
         - `default_color` -⠀the default text color of the `*values`
         - `w_padding` -⠀the horizontal padding (in chars) to the box content
         - `w_full` -⠀whether to make the box be the full console width or not\n
@@ -300,6 +347,41 @@ class Console:
             Console.log("", end, end="")
         return confirmed
 
+    @staticmethod
+    def multiline_input(
+        prompt: object = "",
+        start="",
+        end="\n",
+        default_color: hexa | rgba = COLOR.cyan,
+        show_keybindings=True,
+        input_prefix=" ⤷ ",
+        reset_ansi=True,
+    ) -> str:
+        """An input where users can input (and paste) text over multiple lines.\n
+        -----------------------------------------------------------------------------------
+        - `prompt` -⠀the input prompt
+        - `start` -⠀something to print before the input
+        - `end` -⠀something to print after the input (e.g. `\\n`)
+        - `default_color` -⠀the default text color of the `prompt`
+        - `show_keybindings` -⠀whether to show the special keybindings or not
+        - `input_prefix` -⠀the prefix of the input line
+        - `reset_ansi` -⠀whether to reset the ANSI codes after the input or not
+        -----------------------------------------------------------------------------------
+        The input prompt can be formatted with special formatting codes. For more detailed
+        information about formatting codes, see `xx_format_codes` module documentation."""
+        kb = KeyBindings()
+
+        @kb.add("c-d", eager=True)  # CTRL+D
+        def _(event):
+            event.app.exit(result=event.app.current_buffer.document.text)
+
+        FormatCodes.print(start + prompt, default_color=default_color)
+        if show_keybindings:
+            FormatCodes.print("[dim][[b](CTRL+D)[dim] : end of input][_dim]")
+        input_string = _prompt_toolkit.prompt(input_prefix, multiline=True, wrap_lines=True, key_bindings=kb)
+        FormatCodes.print("[_]" if reset_ansi else "", end=end[1:] if end.startswith("\n") else end)
+        return input_string
+
     @staticmethod
     def restricted_input(
         prompt: object = "",
@@ -417,38 +499,3 @@ class Console:
         """Password input (preset for `Console.restricted_input()`)
         that always masks the entered characters with asterisks."""
         return Console.restricted_input(prompt, start, end, default_color, allowed_chars, min_len, max_len, "*", reset_ansi)
-
-    @staticmethod
-    def multiline_input(
-        prompt: object = "",
-        start="",
-        end="\n",
-        default_color: hexa | rgba = COLOR.cyan,
-        show_keybindings=True,
-        input_prefix=" ⤷ ",
-        reset_ansi=True,
-    ) -> str:
-        """An input where users can input (and paste) text over multiple lines.\n
-        -----------------------------------------------------------------------------------
-        - `prompt` -⠀the input prompt
-        - `start` -⠀something to print before the input
-        - `end` -⠀something to print after the input (e.g. `\\n`)
-        - `default_color` -⠀the default text color of the `prompt`
-        - `show_keybindings` -⠀whether to show the special keybindings or not
-        - `input_prefix` -⠀the prefix of the input line
-        - `reset_ansi` -⠀whether to reset the ANSI codes after the input or not
-        -----------------------------------------------------------------------------------
-        The input prompt can be formatted with special formatting codes. For more detailed
-        information about formatting codes, see `xx_format_codes` module documentation."""
-        kb = KeyBindings()
-
-        @kb.add("c-d", eager=True)  # CTRL+D
-        def _(event):
-            event.app.exit(result=event.app.current_buffer.document.text)
-
-        FormatCodes.print(start + prompt, default_color=default_color)
-        if show_keybindings:
-            FormatCodes.print("[dim][[b](CTRL+D)[dim] : end of input][_dim]")
-        input_string = _prompt_toolkit.prompt(input_prefix, multiline=True, wrap_lines=True, key_bindings=kb)
-        FormatCodes.print("[_]" if reset_ansi else "", end=end[1:] if end.startswith("\n") else end)
-        return input_string

xulbux/xx_data.py

@@ -63,8 +63,7 @@ class Data:
                     v if not isinstance(v,
                                         (list, tuple, set, frozenset, dict)) else Data.remove_empty_items(v, spaces_are_empty)
                 )
-                for k, v in data.items()
-                if not String.is_empty(v, spaces_are_empty)
+                for k, v in data.items() if not String.is_empty(v, spaces_are_empty)
             }
         if isinstance(data, (list, tuple, set, frozenset)):
             return type(data)(
@@ -166,8 +165,7 @@ class Data:
             if isinstance(item, dict):
                 return {
                     k: v
-                    for k, v in ((process_item(key), process_item(value)) for key, value in item.items())
-                    if k is not None
+                    for k, v in ((process_item(key), process_item(value)) for key, value in item.items()) if k is not None
                 }
             if isinstance(item, (list, tuple, set, frozenset)):
                 processed = (v for v in map(process_item, item) if v is not None)
@@ -379,8 +377,7 @@ class Data:
 
         if isinstance(update_values, str):
             update_values = [update_values]
-        valid_entries = [(parts[0].strip(), parts[1])
-                         for update_value in update_values
+        valid_entries = [(parts[0].strip(), parts[1]) for update_value in update_values
                          if len(parts := update_value.split(str(sep).strip())) == 2]
         if not valid_entries:
             raise ValueError(f"No valid update_values found: {update_values}")
@@ -493,14 +490,14 @@ class Data:
             if not d or compactness == 2:
                 return (
                     punct["{"]
-                    + sep.join(f"{format_value(k)}{punct[':']} {format_value(v, current_indent)}" for k, v in d.items())
-                    + punct["}"]
+                    + sep.join(f"{format_value(k)}{punct[':']} {format_value(v, current_indent)}"
+                               for k, v in d.items()) + punct["}"]
                 )
             if not should_expand(d.values()):
                 return (
                     punct["{"]
-                    + sep.join(f"{format_value(k)}{punct[':']} {format_value(v, current_indent)}" for k, v in d.items())
-                    + punct["}"]
+                    + sep.join(f"{format_value(k)}{punct[':']} {format_value(v, current_indent)}"
+                               for k, v in d.items()) + punct["}"]
                 )
             items = []
             for k, val in d.items():
@@ -530,7 +527,7 @@ class Data:
             else:
                 return f"{punct['(']}\n{formatted_items}\n{' ' * current_indent}{punct[')']}"
 
-        return format_dict(data, 0) if isinstance(data, dict) else format_sequence(data, 0)
+        return _re.sub(r"\s+(?=\n)", "", format_dict(data, 0) if isinstance(data, dict) else format_sequence(data, 0))
 
     @staticmethod
     def print(
@@ -559,11 +556,11 @@ class Data:
         part. The formatting can be changed by simply adding the key with the new
         value inside the `syntax_highlighting` dictionary.\n
         The keys with their default values are:
-        - `str: COLOR.["blue"]`
-        - `number: COLOR.["magenta"]`
-        - `literal: COLOR.["cyan"]`
-        - `type: "i|" + COLOR.["lightblue"]`
-        - `punctuation: COLOR.["darkgray"]`\n
+        - `str: COLOR.blue`
+        - `number: COLOR.magenta`
+        - `literal: COLOR.cyan`
+        - `type: "i|" + COLOR.lightblue`
+        - `punctuation: COLOR.darkgray`\n
         For no syntax highlighting, set `syntax_highlighting` to `False` or `None`.\n
         ------------------------------------------------------------------------------
         For more detailed information about formatting codes, see `xx_format_codes`

xulbux/xx_env_path.py

@@ -22,7 +22,7 @@ class EnvPath:
         if cwd:
             path = _os.getcwd()
         elif base_dir:
-            path = Path.get(base_dir=True)
+            path = Path.script_dir
         elif path is None:
             raise ValueError("A path must be provided or either 'cwd' or 'base_dir' must be True.")
         paths = EnvPath.paths(as_list=True)
@@ -62,7 +62,7 @@ class EnvPath:
         if cwd:
             path = _os.getcwd()
         elif base_dir:
-            path = Path.get(base_dir=True)
+            path = Path.script_dir
         elif path is None:
             raise ValueError("A path must be provided or either 'cwd' or 'base_dir' must be True.")
         return _os.path.normpath(path)

xulbux/xx_file.py

@@ -4,6 +4,10 @@ from .xx_path import Path
 import os as _os
 
 
+class SameContentFileExistsError(FileExistsError):
+    pass
+
+
 class File:
 
     @staticmethod
@@ -29,14 +33,16 @@ class File:
         force: bool = False,
     ) -> str:
         """Create a file with ot without content.\n
-        ------------------------------------------------------------------------
-        The function will throw a `FileExistsError` if the file already exists.
+        ----------------------------------------------------------------------
+        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 _os.path.exists(file) and not force:
             with open(file, "r", encoding="utf-8") as existing_file:
                 existing_content = existing_file.read()
                 if existing_content == content:
-                    raise FileExistsError("Already created this file. (nothing changed)")
+                    raise SameContentFileExistsError("Already created this file. (nothing changed)")
             raise FileExistsError("File already exists.")
         with open(file, "w", encoding="utf-8") as f:
             f.write(content)
@@ -62,4 +68,4 @@ class File:
         try:
             return Path.extend(file, search_in, raise_error=True, correct_path=correct_paths)
         except FileNotFoundError:
-            return _os.path.join(Path.get(base_dir=True), file) if prefer_base_dir else _os.path.join(_os.getcwd(), file)
+            return _os.path.join(Path.script_dir, file) if prefer_base_dir else _os.path.join(_os.getcwd(), file)

xulbux/xx_path.py

@@ -6,27 +6,37 @@ import sys as _sys
 import os as _os
 
 
-class Path:
+# YAPF: disable
+class ProcessNotFoundError(Exception):
+    pass
 
-    @staticmethod
-    def get(cwd: bool = False, base_dir: bool = False) -> str | list[str]:
-        paths = []
-        if cwd:
-            paths.append(_os.getcwd())
-        if base_dir:
-            if getattr(_sys, "frozen", False):
-                base_path = _os.path.dirname(_sys.executable)
+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__"):
+                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)):
+                base_path = _os.path.dirname(_os.path.abspath(main_module.__spec__.origin))
             else:
-                main_module = _sys.modules["__main__"]
-                if hasattr(main_module, "__file__"):
-                    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)):
-                    base_path = _os.path.dirname(_os.path.abspath(main_module.__spec__.origin))
-                else:
-                    raise RuntimeError("Can only get base directory if ran from a file.")
-            paths.append(base_path)
-        return paths[0] if len(paths) == 1 else paths
+                raise RuntimeError("Can only get base directory if accessed from a file.")
+        return base_path
+# YAPF: enable
+
+
+class Path:
+
+    cwd: str = _Cwd()
+    """The path to the current working directory."""
+    script_dir: str = _ScriptDir()
+    """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:
@@ -68,7 +78,7 @@ class Path:
             search_dirs = (drive + _os.sep) if drive else [_os.sep]
         else:
             rel_path = path.lstrip(_os.sep)
-            base_dir = Path.get(base_dir=True)
+            base_dir = Path.script_dir
             search_dirs = (
                 _os.getcwd(),
                 base_dir,

xulbux/xx_system.py

@@ -7,15 +7,12 @@ import sys as _sys
 import os as _os
 
 
+# YAPF: disable
 class ProcessNotFoundError(Exception):
     pass
 
-
-class System:
-
-    @staticmethod
-    def is_elevated() -> bool:
-        """Returns `True` if the current user is an admin and `False` otherwise."""
+class _IsElevated:
+    def __get__(self, obj, owner=None):
         try:
             if _os.name == "nt":
                 return _ctypes.windll.shell32.IsUserAnAdmin() != 0
@@ -24,6 +21,14 @@ class System:
         except Exception:
             pass
         return False
+# YAPF: enable
+
+
+class System:
+
+    is_elevated: bool = _IsElevated()
+    """Is `True` if the current process has
+    elevated privileges and `False` otherwise."""
 
     @staticmethod
     def restart(prompt: object = None, wait: int = 0, continue_program: bool = False, force: bool = False) -> None:

{xulbux-1.6.6.dist-info → xulbux-1.6.7.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.2
 Name: xulbux
-Version: 1.6.6
-Summary: A library which includes a lot of really helpful functions.
+Version: 1.6.7
+Summary: A Python library which includes lots of helpful classes, types and functions aiming to make common programming tasks simpler.
 Author-email: XulbuX <xulbux.real@gmail.com>
 License: MIT License
         
@@ -31,7 +31,7 @@ Project-URL: Documentation, https://github.com/XulbuX/PythonLibraryXulbuX/wiki
 Project-URL: Homepage, https://github.com/XulbuX/PythonLibraryXulbuX
 Project-URL: License, https://github.com/XulbuX/PythonLibraryXulbuX/blob/main/LICENSE
 Project-URL: Source Code, https://github.com/XulbuX/PythonLibraryXulbuX/tree/main/src
-Keywords: xulbux,python,library,utility,helper,functions,tools,classes,types,methods,cmd,console,code,color,data,structures,env,environment,file,format,json,path,regex,string,system,operations,presets
+Keywords: xulbux,python,library,utility,helper,functions,tools,classes,types,methods,cmd,console,constants,code,color,data,structures,env,environment,file,format,json,path,regex,string,system,operations,presets
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
@@ -57,38 +57,50 @@ Requires-Dist: flake8-pyproject>=1.2.3; extra == "dev"
 
 # **$\color{#8085FF}\Huge\textsf{XulbuX}$**
 
-**$\color{#8085FF}\textsf{XulbuX}$** is a library which includes a lot of really helpful classes, types and functions.
+**$\color{#8085FF}\textsf{XulbuX}$** is library that contains many useful classes, types, and functions,
+ranging from console logging and working with colors to file management and system operations.
+The library is designed to simplify common programming tasks and improve code readability through its collection of tools.
 
-For precise information about the library, see the library's [Wiki page](https://github.com/XulbuX/PythonLibraryXulbuX/wiki).<br>
-For the libraries latest changes, see the [change log](https://github.com/XulbuX/PythonLibraryXulbuX/blob/main/CHANGELOG.md).
+For precise information about the library, see the library's [wiki page](https://github.com/XulbuX/PythonLibraryXulbuX/wiki).<br>
+For the libraries latest changes and updates, see the [change log](https://github.com/XulbuX/PythonLibraryXulbuX/blob/main/CHANGELOG.md).
 
+<br>
 
 ## Installation
 
-To install the library and all its dependencies, open a console and run the command:
-```prolog
+Run the following commands in a console with administrator privileges, so the actions take effect for all users.
+
+Install the library and all its dependencies with the command:
+```console
 pip install xulbux
 ```
 
-To upgrade the library to the latest available version, run the following command in your console:
-```prolog
+Upgrade the library and all its dependencies to their latest available version with the command:
+```console
 pip install --upgrade xulbux
 ```
 
+<br>
 
 ## Usage
 
-Import the full library under the alias `xx`, so it's classes, types and functions are accessible with `xx.Class.method()`, `xx.type()` and `xx.function()`:
+Import the full library under the alias `xx`, so its constants, classes, methods and types are accessible with `xx.CONSTANT.value`, `xx.Class.method()`, `xx.type()`:
 ```python
 import xulbux as xx
 ```
-So you don't have to write `xx` in front of the library's types, you can import them directly:
+So you don't have to import the full library under an alias, you can also import only certain parts of the library's contents:
 ```python
+# CONSTANTS
+from xulbux import COLOR, CHARS, ANSI
+# Classes
+from xulbux import Code, Color, Console, ...
+# types
 from xulbux import rgba, hsla, hexa
 ```
 
+<br>
 
-# Modules
+## Modules
 
 | | |
 | :--------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------- |
@@ -105,7 +117,72 @@ from xulbux import rgba, hsla, hexa
 | <h3>[`xx_string`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_string)</h3>             | helpful actions when working with strings. (*normalize, escape, decompose, ...*)                   |
 | <h3>`xx_system`</h3>                                                                                 | advanced system actions (*restart with message, check installed Python libs, ...*)                 |
 
+<br>
+
+## Example Usage
 
+This is what it could look like using this library for a simple but very nice looking color converter:
+```python
+from xulbux import COLOR                 # CONSTANTS
+from xulbux import FormatCodes, Console  # Classes
+from xulbux import hexa                  # types
+
+
+def main() -> None:
+
+    # LET THE USER ENTER A HEXA COLOR IN ANY HEXA FORMAT
+    input_clr = FormatCodes.input(
+      "\n[b](Enter a HEXA color in any format) [dim](>) "
+    )
+
+    # ANNOUNCE INDEXING THE INPUT COLOR
+    Console.log(
+      "INDEX",
+      "Indexing the input HEXA color...",
+      start="\n",
+      title_bg_color=COLOR.blue,
+    )
+
+    try:
+        # TRY TO CONVERT THE INPUT COLOR INTO A hexa() COLOR
+        hexa_color = hexa(input_clr)
+
+    except ValueError:
+        # ANNOUNCE THE ERROR AND EXIT THE PROGRAM
+        Console.fail(
+          "The input HEXA color is invalid.",
+          end="\n\n",
+          exit=True,
+        )
+
+    # ANNOUNCE STARTING THE CONVERSION
+    Console.log(
+      "CONVERT",
+      "Converting the HEXA color into different types...",
+      title_bg_color=COLOR.tangerine,
+    )
+
+    # CONVERT THE HEXA COLOR INTO THE TWO OTHER COLOR TYPES
+    rgba_color = hexa_color.to_rgba()
+    hsla_color = hexa_color.to_hsla()
+
+    # ANNOUNCE THE SUCCESSFUL CONVERSION
+    Console.done(
+      "Successfully converted color into different types.",
+      end="\n\n",
+    )
+
+    # PRETTY PRINT THE COLOR IN DIFFERENT TYPES
+    FormatCodes.print(f"[b](HEXA:) [i|white]({hexa_color})")
+    FormatCodes.print(f"[b](RGBA:) [i|white]({rgba_color})")
+    FormatCodes.print(f"[b](HSLA:) [i|white]({hsla_color})\n")
+
+
+if __name__ == "__main__":
+    main()
+```
+
+<br>
 <br>
 
 --------------------------------------------------------------

xulbux-1.6.7.dist-info/RECORD

@@ -0,0 +1,21 @@
+xulbux/__init__.py,sha256=UpA3daxpIqjsDltsQawhVZWD5ggQAHl9L8YVurs_LgQ,1654
+xulbux/_cli_.py,sha256=I1TieHnX60mlRvMaTQnon-VRuf_70dkP7sOU1aHthQY,3470
+xulbux/_consts_.py,sha256=b85O5sePS18z7CJgrVw0V7v88PIG9qnQ7G2bJL71odk,6287
+xulbux/xx_code.py,sha256=dY2HRXIDXHN3KTzzUkQVBacFDExNVwH8flREshwi4vk,5288
+xulbux/xx_color.py,sha256=nwcd5_4JIRfZ99JqbCXMl4RWpic_-M361AA5zEa9Nuw,44846
+xulbux/xx_console.py,sha256=X5Xw-Sd-0aOPqIhdddTyXyEELsnlOP8QFOmBED4cbJg,22175
+xulbux/xx_data.py,sha256=5MIEKDgbRLGkZi9Yd35XhzrWZY09oXyVLGs0BgTTHFA,30219
+xulbux/xx_env_path.py,sha256=pdFyfZgOgCQ440thNdUKzhb1JVxefeTLp7rj6YHYrpk,4305
+xulbux/xx_file.py,sha256=sVUj50vT0wpc2C8Kkg1MlqDUFauCvLGQx6ZEh1gMm5k,3316
+xulbux/xx_format_codes.py,sha256=abR9TWtnBLF0L08oyRjDYXx9VCtun9kjGVPmkv44emU,20359
+xulbux/xx_json.py,sha256=dw2AiqMErdjW0ot4pICDBdTL6j03IrYJWJz-Lw21d4Q,5149
+xulbux/xx_path.py,sha256=trDke1N9ewbkQmAIqjeB9gfbTuAlzqFY2mtPtlK2Ks0,4639
+xulbux/xx_regex.py,sha256=gvnDel8xVmf11kvhc0iIjSj1dFW3OLnXNDlaJsUxXU4,7952
+xulbux/xx_string.py,sha256=nJBXAVNknhTE9N_4yOyCVwSSIwOyHCRlZe_D7LOgrOY,5450
+xulbux/xx_system.py,sha256=4WuItIeVF5cU3u3-cu3XqhtxBcap9YDJiQKTZuWsUyM,6494
+xulbux-1.6.7.dist-info/LICENSE,sha256=6NflEcvzFEe8_JFVNCPVwZBwBhlLLd4vqQi8WiX_Xk4,1084
+xulbux-1.6.7.dist-info/METADATA,sha256=QDBNVRyIAIrMBzSHxJ1u-cIX2QiU-f9HxcudiCr5of4,9295
+xulbux-1.6.7.dist-info/WHEEL,sha256=nn6H5-ilmfVryoAQl3ZQ2l8SH5imPWFpm1A5FgEuFV4,91
+xulbux-1.6.7.dist-info/entry_points.txt,sha256=a3womfLIMZKnOFiyy-xnVb4g2qkZsHR5FbKKkljcGns,94
+xulbux-1.6.7.dist-info/top_level.txt,sha256=FkK4EZajwfP36fnlrPaR98OrEvZpvdEOdW1T5zTj6og,7
+xulbux-1.6.7.dist-info/RECORD,,

{xulbux-1.6.6.dist-info → xulbux-1.6.7.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: setuptools (75.8.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

xulbux-1.6.6.dist-info/RECORD

@@ -1,21 +0,0 @@
-xulbux/__init__.py,sha256=kGUOl7SiyAMqKsEZfZODjJILWaFVVRnzAkT5WrwmHMQ,1654
-xulbux/_cli_.py,sha256=I1TieHnX60mlRvMaTQnon-VRuf_70dkP7sOU1aHthQY,3470
-xulbux/_consts_.py,sha256=aQyWSJ5_Spqot1HHWKbYj1j-6YSakIqG89Olv7rp7Ms,4886
-xulbux/xx_code.py,sha256=dY2HRXIDXHN3KTzzUkQVBacFDExNVwH8flREshwi4vk,5288
-xulbux/xx_color.py,sha256=nwcd5_4JIRfZ99JqbCXMl4RWpic_-M361AA5zEa9Nuw,44846
-xulbux/xx_console.py,sha256=pwB1gLuwTj9V2FhcK-kNTfK7eK3Mb-fbsD59Cua-XTM,20078
-xulbux/xx_data.py,sha256=fkJKArU7TTmXTk90vG_s4BHIor6NRqUP_gqypyv3v9U,30254
-xulbux/xx_env_path.py,sha256=e5r47g-dLIo_J9RM9teqLM1rTzNsI0w9U0xjjcK6nro,4321
-xulbux/xx_file.py,sha256=MGGrPDyvgVQJrdcRSGE_jiB_aQz6zo5I0m6_5pKYIo8,3123
-xulbux/xx_format_codes.py,sha256=abR9TWtnBLF0L08oyRjDYXx9VCtun9kjGVPmkv44emU,20359
-xulbux/xx_json.py,sha256=dw2AiqMErdjW0ot4pICDBdTL6j03IrYJWJz-Lw21d4Q,5149
-xulbux/xx_path.py,sha256=KjSurQ9SHqcdhyTo1vzZn2qGXaQr3T1eDr-E_PVdyXo,4537
-xulbux/xx_regex.py,sha256=gvnDel8xVmf11kvhc0iIjSj1dFW3OLnXNDlaJsUxXU4,7952
-xulbux/xx_string.py,sha256=nJBXAVNknhTE9N_4yOyCVwSSIwOyHCRlZe_D7LOgrOY,5450
-xulbux/xx_system.py,sha256=izDmmrh3o66drAp-LkqsA5AruAdHprq5p_CuseT1OJI,6399
-xulbux-1.6.6.dist-info/LICENSE,sha256=6NflEcvzFEe8_JFVNCPVwZBwBhlLLd4vqQi8WiX_Xk4,1084
-xulbux-1.6.6.dist-info/METADATA,sha256=s2U6Uel8qNsGjnL8Czi8nxzXcOy_sByZCSd_dLAg-w4,6979
-xulbux-1.6.6.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-xulbux-1.6.6.dist-info/entry_points.txt,sha256=a3womfLIMZKnOFiyy-xnVb4g2qkZsHR5FbKKkljcGns,94
-xulbux-1.6.6.dist-info/top_level.txt,sha256=FkK4EZajwfP36fnlrPaR98OrEvZpvdEOdW1T5zTj6og,7
-xulbux-1.6.6.dist-info/RECORD,,