xulbux 1.8.0__py3-none-any.whl → 1.8.2__py3-none-any.whl

xulbux/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.8.0"
+__version__ = "1.8.2"
 
 __author__ = "XulbuX"
 __email__ = "xulbux.real@gmail.com"
@@ -7,11 +7,26 @@ __copyright__ = "Copyright (c) 2024 XulbuX"
 __url__ = "https://github.com/XulbuX/PythonLibraryXulbuX"
 __description__ = "A Python library which includes lots of helpful classes, types, and functions aiming to make common programming tasks simpler."
 
-__all__ = ["Code", "Color", "Console", "Data", "EnvPath", "File", "FormatCodes", "Json", "Path", "Regex", "String", "System"]
+__all__ = [
+    "Code",
+    "Color",
+    "Console",
+    "Data",
+    "EnvPath",
+    "File",
+    "FormatCodes",
+    "Json",
+    "Path",
+    "ProgressBar",
+    "Regex",
+    "String",
+    "System",
+]
 
 from .code import Code
 from .color import Color
 from .console import Console
+from .console import ProgressBar
 from .data import Data
 from .env_path import EnvPath
 from .file import File

xulbux/base/consts.py

@@ -0,0 +1,173 @@
+from typing import TypeAlias
+
+
+FormattableString: TypeAlias = str
+"""A `str` object that is made to be formatted with the `.format()` method."""
+
+
+class COLOR:
+    """Hexa color presets."""
+
+    WHITE = "#F1F2FF"
+    LIGHT_GRAY = "#B6B7C0"
+    GRAY = "#7B7C8D"
+    DARK_GRAY = "#67686C"
+    BLACK = "#202125"
+    RED = "#FF606A"
+    CORAL = "#FF7069"
+    ORANGE = "#FF876A"
+    TANGERINE = "#FF9962"
+    GOLD = "#FFAF60"
+    YELLOW = "#FFD260"
+    LIME = "#C9F16E"
+    GREEN = "#7EE787"
+    NEON_GREEN = "#4CFF85"
+    TEAL = "#50EAAF"
+    CYAN = "#3EDEE6"
+    ICE = "#77DBEF"
+    LIGHT_BLUE = "#60AAFF"
+    BLUE = "#8085FF"
+    LAVENDER = "#9B7DFF"
+    PURPLE = "#AD68FF"
+    MAGENTA = "#C860FF"
+    PINK = "#F162EF"
+    ROSE = "#FF609F"
+
+
+class CHARS:
+    """Text character sets."""
+
+    class _AllTextChars:
+        pass
+
+    ALL = _AllTextChars
+    """Code to signal that all characters are allowed."""
+
+    DIGITS = "0123456789"
+    """Digits: `0`-`9`"""
+    FLOAT_DIGITS = DIGITS + "."
+    """Digits: `0`-`9` with decimal point `.`"""
+    HEX_DIGITS = DIGITS + "#abcdefABCDEF"
+    """Digits: `0`-`9` Letters: `a`-`f` `A`-`F` and a hashtag `#`"""
+
+    LOWERCASE = "abcdefghijklmnopqrstuvwxyz"
+    """Lowercase letters `a`-`z`"""
+    LOWERCASE_EXTENDED = LOWERCASE + "äëïöüÿàèìòùáéíóúýâêîôûãñõåæç"
+    """Lowercase letters `a`-`z` with all lowercase diacritic letters."""
+    UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+    """Uppercase letters `A`-`Z`"""
+    UPPERCASE_EXTENDED = UPPERCASE + "ÄËÏÖÜÀÈÌÒÙÁÉÍÓÚÝÂÊÎÔÛÃÑÕÅÆÇß"
+    """Uppercase letters `A`-`Z` with all uppercase diacritic letters."""
+
+    LETTERS = LOWERCASE + UPPERCASE
+    """Lowercase and uppercase letters `a`-`z` and `A`-`Z`"""
+    LETTERS_EXTENDED = LOWERCASE_EXTENDED + UPPERCASE_EXTENDED
+    """Lowercase and uppercase letters `a`-`z` `A`-`Z` and all diacritic letters."""
+
+    SPECIAL_ASCII = " !\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
+    """All ASCII special characters."""
+    SPECIAL_ASCII_EXTENDED = SPECIAL_ASCII + "ø£Ø׃ªº¿®¬½¼¡«»░▒▓│┤©╣║╗╝¢¥┐└┴┬├─┼╚╔╩╦╠═╬¤ðÐı┘┌█▄¦▀µþÞ¯´≡­±‗¾¶§÷¸°¨·¹³²■ "
+    """All ASCII special characters with the extended ASCII special characters."""
+    STANDARD_ASCII = SPECIAL_ASCII + DIGITS + LETTERS
+    """All standard ASCII characters."""
+    FULL_ASCII = SPECIAL_ASCII_EXTENDED + DIGITS + LETTERS_EXTENDED
+    """All characters in the ASCII table."""
+
+
+class ANSI:
+    """Constants and methods for use of ANSI escape codes"""
+
+    ESCAPED_CHAR = "\\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."""
+
+    @classmethod
+    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: tuple[str, ...] = (
+        ########### DEFAULT CONSOLE COLOR NAMES ############
+        "black",
+        "red",
+        "green",
+        "yellow",
+        "blue",
+        "magenta",
+        "cyan",
+        "white",
+    )
+    """The console default color names."""
+
+    CODES_MAP: dict[str | tuple[str, ...], int] = {
+        ################# SPECIFIC RESETS ##################
+        "_": 0,
+        ("_bold", "_b"): 22,
+        ("_dim", "_d"): 22,
+        ("_italic", "_i"): 23,
+        ("_underline", "_u"): 24,
+        ("_double-underline", "_du"): 24,
+        ("_inverse", "_invert", "_in"): 27,
+        ("_hidden", "_hide", "_h"): 28,
+        ("_strikethrough", "_s"): 29,
+        ("_color", "_c"): 39,
+        ("_background", "_bg"): 49,
+        ################### TEXT STYLES ####################
+        ("bold", "b"): 1,
+        ("dim", "d"): 2,
+        ("italic", "i"): 3,
+        ("underline", "u"): 4,
+        ("inverse", "invert", "in"): 7,
+        ("hidden", "hide", "h"): 8,
+        ("strikethrough", "s"): 9,
+        ("double-underline", "du"): 21,
+        ################## DEFAULT COLORS ##################
+        "black": 30,
+        "red": 31,
+        "green": 32,
+        "yellow": 33,
+        "blue": 34,
+        "magenta": 35,
+        "cyan": 36,
+        "white": 37,
+        ############## BRIGHT DEFAULT COLORS ###############
+        "br:black": 90,
+        "br:red": 91,
+        "br:green": 92,
+        "br:yellow": 93,
+        "br:blue": 94,
+        "br:magenta": 95,
+        "br:cyan": 96,
+        "br:white": 97,
+        ############ DEFAULT BACKGROUND COLORS #############
+        "bg:black": 40,
+        "bg:red": 41,
+        "bg:green": 42,
+        "bg:yellow": 43,
+        "bg:blue": 44,
+        "bg:magenta": 45,
+        "bg:cyan": 46,
+        "bg:white": 47,
+        ######### BRIGHT DEFAULT BACKGROUND COLORS #########
+        "bg:br:black": 100,
+        "bg:br:red": 101,
+        "bg:br:green": 102,
+        "bg:br:yellow": 103,
+        "bg:br:blue": 104,
+        "bg:br:magenta": 105,
+        "bg:br:cyan": 106,
+        "bg:br:white": 107,
+    }
+    """All custom format keys and their corresponding ANSI format number codes."""

xulbux/cli/help.py

@@ -0,0 +1,73 @@
+from .. import __version__
+from ..base.consts import COLOR
+from ..format_codes import FormatCodes
+from ..console import Console
+
+from urllib.error import HTTPError
+from typing import Optional
+import urllib.request as _request
+import json as _json
+
+
+def get_latest_version() -> Optional[str]:
+    with _request.urlopen(URL) as response:
+        if response.status == 200:
+            data = _json.load(response)
+            return data["info"]["version"]
+        else:
+            raise HTTPError(URL, response.status, "Failed to fetch latest version info", response.headers, None)
+
+
+def is_latest_version() -> Optional[bool]:
+    try:
+        latest = get_latest_version()
+        if latest in ("", None): return None
+        latest_v_parts = tuple(int(part) for part in latest.lower().lstrip("v").split('.'))
+        installed_v_parts = tuple(int(part) for part in __version__.lower().lstrip("v").split('.'))
+        return latest_v_parts <= installed_v_parts
+    except Exception:
+        return None
+
+
+URL = "https://pypi.org/pypi/xulbux/json"
+IS_LATEST_VERSION = is_latest_version()
+CLR = {
+    "class": COLOR.TANGERINE,
+    "code_border": COLOR.GRAY,
+    "const": COLOR.RED,
+    "func": COLOR.CYAN,
+    "import": COLOR.NEON_GREEN,
+    "lib": COLOR.ORANGE,
+    "notice": COLOR.YELLOW,
+    "punctuators": COLOR.DARK_GRAY,
+}
+HELP = FormatCodes.to_ansi(
+    rf"""  [_|b|#7075FF]               __  __
+  [b|#7075FF]  _  __ __  __/ / / /_  __  ___  __
+  [b|#7075FF] | |/ // / / / / / __ \/ / / | |/ /
+  [b|#7075FF] > , </ /_/ / /_/ /_/ / /_/ /> , <
+  [b|#7075FF]/_/|_|\____/\__/\____/\____//_/|_|  [*|BG:{COLOR.GRAY}|#000] v[b]{__version__} [*|dim|{CLR['notice']}]({'' if IS_LATEST_VERSION else ' (newer available)'})[*]
+
+  [i|{COLOR.CORAL}]A TON OF COOL FUNCTIONS, YOU NEED![*]
+
+  [b|#FCFCFF]Usage:[*]
+  [dim|{CLR['code_border']}](╭────────────────────────────────────────────────────╮)
+  [dim|{CLR['code_border']}](│) [{CLR['punctuators']}]# LIBRARY CONSTANTS[*]                                [dim|{CLR['code_border']}](│)
+  [dim|{CLR['code_border']}](│) [{CLR['import']}]from [{CLR['lib']}]xulbux[{CLR['punctuators']}].[{CLR['lib']}]base[{CLR['punctuators']}].[{CLR['lib']}]consts [{CLR['import']}]import [{CLR['const']}]COLOR[{CLR['punctuators']}], [{CLR['const']}]CHARS[{CLR['punctuators']}], [{CLR['const']}]ANSI[*]  [dim|{CLR['code_border']}](│)
+  [dim|{CLR['code_border']}](│) [{CLR['punctuators']}]# Main Classes[*]                                     [dim|{CLR['code_border']}](│)
+  [dim|{CLR['code_border']}](│) [{CLR['import']}]from [{CLR['lib']}]xulbux [{CLR['import']}]import [{CLR['class']}]Code[{CLR['punctuators']}], [{CLR['class']}]Color[{CLR['punctuators']}], [{CLR['class']}]Console[{CLR['punctuators']}], ...[*]       [dim|{CLR['code_border']}](│)
+  [dim|{CLR['code_border']}](│) [{CLR['punctuators']}]# module specific imports[*]                          [dim|{CLR['code_border']}](│)
+  [dim|{CLR['code_border']}](│) [{CLR['import']}]from [{CLR['lib']}]xulbux[{CLR['punctuators']}].[{CLR['lib']}]color [{CLR['import']}]import [{CLR['func']}]rgba[{CLR['punctuators']}], [{CLR['func']}]hsla[{CLR['punctuators']}], [{CLR['func']}]hexa[*]          [dim|{CLR['code_border']}](│)
+  [dim|{CLR['code_border']}](╰────────────────────────────────────────────────────╯)
+  [b|#FCFCFF]Documentation:[*]
+  [dim|{CLR['code_border']}](╭────────────────────────────────────────────────────╮)
+  [dim|{CLR['code_border']}](│) [#DADADD]For more information see the GitHub page.          [dim|{CLR['code_border']}](│)
+  [dim|{CLR['code_border']}](│) [u|#8085FF](https://github.com/XulbuX/PythonLibraryXulbuX/wiki) [dim|{CLR['code_border']}](│)
+  [dim|{CLR['code_border']}](╰────────────────────────────────────────────────────╯)
+  [_]"""
+)
+
+
+def show_help() -> None:
+    print(HELP)
+    Console.pause_exit(pause=True, prompt="  [dim](Press any key to exit...)\n\n")

xulbux/color.py

@@ -92,9 +92,13 @@ class rgba:
 
     def __init__(self, r: int, g: int, b: int, a: Optional[float] = None, _validate: bool = True):
         self.r: int
+        """The red channel (`0`–`255`)"""
         self.g: int
+        """The green channel (`0`–`255`)"""
         self.b: int
+        """The blue channel (`0`–`255`)"""
         self.a: Optional[float]
+        """The alpha channel (`0.0`–`1.0`) or `None` if not set"""
         if not _validate:
             self.r, self.g, self.b, self.a = r, g, b, a
             return
@@ -291,9 +295,13 @@ class hsla:
 
     def __init__(self, h: int, s: int, l: int, a: Optional[float] = None, _validate: bool = True):
         self.h: int
+        """The hue channel (`0`–`360`)"""
         self.s: int
+        """The saturation channel (`0`–`100`)"""
         self.l: int
+        """The lightness channel (`0`–`100`)"""
         self.a: Optional[float]
+        """The alpha channel (`0.0`–`1.0`) or `None` if not set"""
         if not _validate:
             self.h, self.s, self.l, self.a = h, s, l, a
             return
@@ -496,9 +504,13 @@ class hexa:
         _a: Optional[float] = None,
     ):
         self.r: int
+        """The red channel (`0`–`255`)"""
         self.g: int
+        """The green channel (`0`–`255`)"""
         self.b: int
+        """The blue channel (`0`–`255`)"""
         self.a: Optional[float]
+        """The alpha channel (`0.0`–`1.0`) or `None` if not set"""
         if all(x is not None for x in (_r, _g, _b)):
             self.r, self.g, self.b, self.a = cast(int, _r), cast(int, _g), cast(int, _b), _a
             return

xulbux/console.py

@@ -5,15 +5,16 @@ You can also use special formatting codes directly inside the log message to cha
 For more detailed information about formatting codes, see the the `format_codes` module documentation.
 """
 
-from .base.consts import COLOR, CHARS
-from .format_codes import FormatCodes, _COMPILED
+from .base.consts import COLOR, CHARS, ANSI
+from .format_codes import FormatCodes, _COMPILED as _FC_COMPILED
 from .string import String
 from .color import Color, Rgba, Hexa
 
-from typing import Callable, Optional, Literal, Mapping, Any, cast
+from typing import Generator, Callable, Optional, Literal, Mapping, Pattern, TypeVar, TextIO, Any, cast
 from prompt_toolkit.key_binding import KeyPressEvent, KeyBindings
 from prompt_toolkit.validation import ValidationError, Validator
 from prompt_toolkit.styles import Style
+from contextlib import contextmanager
 from prompt_toolkit.keys import Keys
 import prompt_toolkit as _pt
 import keyboard as _keyboard
@@ -21,6 +22,17 @@ import getpass as _getpass
 import shutil as _shutil
 import sys as _sys
 import os as _os
+import re as _re
+import io as _io
+
+
+_COMPILED: dict[str, Pattern] = {  # PRECOMPILE REGULAR EXPRESSIONS
+    "label": _re.compile(r"(?i)\{(?:label|l)\}"),
+    "bar": _re.compile(r"(?i)\{(?:bar|b)\}"),
+    "current": _re.compile(r"(?i)\{(?:current|c)\}"),
+    "total": _re.compile(r"(?i)\{(?:total|t)\}"),
+    "percentage": _re.compile(r"(?i)\{(?:percentage|percent|p)\}"),
+}
 
 
 class _ConsoleWidth:
@@ -66,7 +78,9 @@ class ArgResult:
 
     def __init__(self, exists: bool, value: Any | list[Any]):
         self.exists: bool = exists
+        """Whether the argument was found or not."""
         self.value: Any = value
+        """The value given with the found argument."""
 
     def __bool__(self):
         return self.exists
@@ -366,9 +380,12 @@ class Console:
         end: str = "\n",
         title_bg_color: Optional[Rgba | Hexa] = None,
         default_color: Optional[Rgba | Hexa] = None,
-        _console_tabsize: int = 8,
+        tab_size: int = 8,
+        title_px: int = 1,
+        title_mx: int = 2,
     ) -> None:
-        """Will print a formatted log message:
+        """Prints a nicely formatted log message.\n
+        -------------------------------------------------------------------------------------------
         - `title` -⠀the title of the log message (e.g. `DEBUG`, `WARN`, `FAIL`, etc.)
         - `prompt` -⠀the log message
         - `format_linebreaks` -⠀whether to format (indent after) the line breaks or not
@@ -376,38 +393,40 @@ class Console:
         - `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`
-        - `_console_tabsize` -⠀the tab size of the console (default is 8)\n
-        -----------------------------------------------------------------------------------
+        - `tab_size` -⠀the tab size used for the log (default is 8 like console tabs)
+        - `title_px` -⠀the horizontal padding (in chars) to the title (if `title_bg_color` is set)
+        - `title_mx` -⠀the horizontal margin (in chars) to the title\n
+        -------------------------------------------------------------------------------------------
         The log message can be formatted with special formatting codes. For more detailed
         information about formatting codes, see `format_codes` module documentation."""
+        has_title_bg = title_bg_color is not None and Color.is_valid(title_bg_color)
         title = "" if title is None else title.strip().upper()
-        title_len, tab_len = len(title) + 4, _console_tabsize - ((len(title) + 4) % _console_tabsize)
-        if title_bg_color is not None and Color.is_valid(title_bg_color):
-            title_bg_color = Color.to_hexa(title_bg_color)
-            title_color = Color.text_color_for_on_bg(title_bg_color)
-        else:
-            title_color = "_color" if title_bg_color is None else "#000"
+        title_fg = Color.text_color_for_on_bg(
+            Color.to_hexa(title_bg_color)  # type: ignore[assignment]
+        ) if has_title_bg else "_color"
+        px, mx = (" " * title_px) if has_title_bg else "", " " * title_mx
+        tab = " " * (tab_size - 1 - ((len(mx) + (title_len := len(title) + 2 * len(px))) % tab_size))
         if format_linebreaks:
             clean_prompt, removals = FormatCodes.remove_formatting(str(prompt), get_removals=True, _ignore_linebreaks=True)
-            prompt_lst = (String.split_count(l, Console.w - (title_len + tab_len)) for l in str(clean_prompt).splitlines())
+            prompt_lst = (
+                String.split_count(l, Console.w - (title_len + len(tab) + 2 * len(mx))) for l in str(clean_prompt).splitlines()
+            )
             prompt_lst = (
                 item for lst in prompt_lst for item in ([""] if lst == [] else (lst if isinstance(lst, list) else [lst]))
             )
-            prompt = f"\n{' ' * title_len}\t".join(
+            prompt = f"\n{mx}{' ' * title_len}{mx}{tab}".join(
                 Console.__add_back_removed_parts(list(prompt_lst), cast(tuple[tuple[int, str], ...], removals))
             )
-        else:
-            prompt = str(prompt)
         if title == "":
             FormatCodes.print(
-                f'{start}  {f"[{default_color}]" if default_color else ""}{str(prompt)}[_]',
+                f'{start}  {f"[{default_color}]" if default_color else ""}{prompt}[_]',
                 default_color=default_color,
                 end=end,
             )
         else:
             FormatCodes.print(
-                f'{start}  [bold][{title_color}]{f"[BG:{title_bg_color}]" if title_bg_color else ""} {title} [_]'
-                + f'\t{f"[{default_color}]" if default_color else ""}{prompt}[_]',
+                f"{start}{mx}[bold][{title_fg}]{f'[BG:{title_bg_color}]' if title_bg_color else ''}{px}{title}{px}[_]{mx}"
+                + f"{tab}{f'[{default_color}]' if default_color else ''}{prompt}[_]",
                 default_color=default_color,
                 end=end,
             )
@@ -569,7 +588,7 @@ class Console:
         spaces_l = " " * indent
         lines = [
             f"{spaces_l}[bg:{box_bg_color}]{' ' * w_padding}"
-            + _COMPILED["formatting"].sub(lambda m: f"{m.group(0)}[bg:{box_bg_color}]", line) +
+            + _FC_COMPILED["formatting"].sub(lambda m: f"{m.group(0)}[bg:{box_bg_color}]", line) +
             (" " * ((w_padding + max_line_len - len(unfmt)) + pad_w_full)) + "[*]" for line, unfmt in zip(lines, unfmt_lines)
         ]
         pady = " " * (Console.w if w_full else max_line_len + (2 * w_padding))
@@ -724,6 +743,8 @@ class Console:
         FormatCodes.print("[_]" if reset_ansi else "", end=end[1:] if end.startswith("\n") else end)
         return input_string
 
+    T = TypeVar("T")
+
     @staticmethod
     def input(
         prompt: object = "",
@@ -737,7 +758,9 @@ class Console:
         allowed_chars: str = CHARS.ALL,  #type: ignore[assignment]
         allow_paste: bool = True,
         validator: Optional[Callable[[str], Optional[str]]] = None,
-    ) -> str:
+        default_val: Optional[T] = None,
+        output_type: type[T] = str,  # type: ignore[assignment]
+    ) -> T:
         """Acts like a standard Python `input()` a bunch of cool extra features.\n
         ------------------------------------------------------------------------------------
         - `prompt` -⠀the input prompt
@@ -753,12 +776,15 @@ class Console:
         - `allow_paste` -⠀whether to allow pasting text into the input or not
         - `validator` -⠀a function that takes the input string and returns a string error
           message if invalid, or nothing if valid
+        - `default_val` -⠀the default value to return if the input is empty
+        - `output_type` -⠀the type (class) to convert the input to before returning it\n
         ------------------------------------------------------------------------------------
         The input prompt can be formatted with special formatting codes. For more detailed
         information about formatting codes, see the `format_codes` module documentation."""
         result_text = ""
         tried_pasting = False
         filtered_chars = set()
+        has_default = default_val is not None
 
         class InputValidator(Validator):
 
@@ -900,4 +926,282 @@ class Console:
         FormatCodes.print(start, end="")
         session.prompt()
         FormatCodes.print(end, end="")
-        return result_text
+
+        if result_text in ("", None):
+            if has_default: return default_val
+            result_text = ""
+
+        if output_type == str:
+            return result_text  # type: ignore[return-value]
+        else:
+            try:
+                return output_type(result_text)  # type: ignore[call-arg]
+            except (ValueError, TypeError):
+                if has_default: return default_val
+                raise
+
+
+class ProgressBar:
+    """A console progress bar with smooth transitions and customizable appearance.\n
+    -------------------------------------------------------------------------------------------------
+    - `min_width` -⠀the min width of the progress bar in chars
+    - `max_width` -⠀the max width of the progress bar in chars
+    - `bar_format` -⠀the format string used to render the progress bar, containing placeholders:
+      * `{label}` `{l}`
+      * `{bar}` `{b}`
+      * `{current}` `{c}`
+      * `{total}` `{t}`
+      * `{percentage}` `{percent}` `{p}`
+    - `limited_bar_format` -⠀a simplified format string used when the console width is too small
+    - `chars` -⠀a tuple of characters ordered from full to empty progress<br>
+      The first character represents completely filled sections, intermediate
+      characters create smooth transitions, and the last character represents
+      empty sections. Default is a set of Unicode block characters.
+    --------------------------------------------------------------------------------------------------
+    The bar format (also limited) can additionally be formatted with special formatting codes. For
+    more detailed information about formatting codes, see the `format_codes` module documentation."""
+
+    def __init__(
+        self,
+        min_width: int = 10,
+        max_width: int = 50,
+        bar_format: str = "{l} |{b}| [b]({c})/{t} [dim](([i]({p}%)))",
+        limited_bar_format: str = "|{b}|",
+        chars: tuple[str, ...] = ("█", "▉", "▊", "▋", "▌", "▍", "▎", "▏", " "),
+    ):
+        self.active: bool = False
+        """Whether the progress bar is currently active (intercepting stdout) or not."""
+        self.min_width: int
+        """The min width of the progress bar in chars."""
+        self.max_width: int
+        """The max width of the progress bar in chars."""
+        self.bar_format: str
+        """The format string used to render the progress bar."""
+        self.limited_bar_format: str
+        """The simplified format string used when the console width is too small."""
+        self.chars: tuple[str, ...]
+        """A tuple of characters ordered from full to empty progress."""
+
+        self.set_width(min_width, max_width)
+        self.set_bar_format(bar_format, limited_bar_format)
+        self.set_chars(chars)
+
+        self._buffer: list[str] = []
+        self._original_stdout: Optional[TextIO] = None
+        self._current_progress_str: str = ""
+        self._last_line_len: int = 0
+
+    def set_width(self, min_width: Optional[int] = None, max_width: Optional[int] = None) -> None:
+        """Set the width of the progress bar.\n
+        --------------------------------------------------------------
+        - `min_width` -⠀the min width of the progress bar in chars
+        - `max_width` -⠀the max width of the progress bar in chars"""
+        if min_width is not None:
+            if min_width < 1:
+                raise ValueError("Minimum width must be at least 1.")
+            self.min_width = max(1, min_width)
+        if max_width is not None:
+            if max_width < 1:
+                raise ValueError("Maximum width must be at least 1.")
+            self.max_width = max(self.min_width, max_width)
+
+    def set_bar_format(self, bar_format: Optional[str] = None, limited_bar_format: Optional[str] = None) -> None:
+        """Set the format string used to render the progress bar.\n
+        --------------------------------------------------------------------------------------------------
+        - `bar_format` -⠀the format string used to render the progress bar, containing placeholders:
+          * `{label}` `{l}`
+          * `{bar}` `{b}`
+          * `{current}` `{c}`
+          * `{total}` `{t}`
+          * `{percentage}` `{percent}` `{p}`
+        - `limited_bar_format` -⠀a simplified format string used when the console width is too small
+        --------------------------------------------------------------------------------------------------
+        The bar format (also limited) can additionally be formatted with special formatting codes. For
+        more detailed information about formatting codes, see the `format_codes` module documentation."""
+        if bar_format is not None:
+            if not _COMPILED["bar"].search(bar_format):
+                raise ValueError("'bar_format' must contain the '{bar}' or '{b}' placeholder.")
+            self.bar_format = bar_format
+        if limited_bar_format is not None:
+            if not _COMPILED["bar"].search(limited_bar_format):
+                raise ValueError("'limited_bar_format' must contain the '{bar}' or '{b}' placeholder.")
+            self.limited_bar_format = limited_bar_format
+
+    def set_chars(self, chars: tuple[str, ...]) -> None:
+        """Set the characters used to render the progress bar.\n
+        --------------------------------------------------------------------------
+        - `chars` -⠀a tuple of characters ordered from full to empty progress<br>
+          The first character represents completely filled sections, intermediate
+          characters create smooth transitions, and the last character represents
+          empty sections. If None, uses default Unicode block characters."""
+        if len(chars) < 2:
+            raise ValueError("'chars' must contain at least two characters (full and empty).")
+        if not all(len(c) == 1 for c in chars if isinstance(c, str)):
+            raise ValueError("All 'chars' items must be single-character strings.")
+        self.chars = chars
+
+    def show_progress(self, current: int, total: int, label: Optional[str] = None) -> None:
+        """Show or update the progress bar.\n
+        -------------------------------------------------------------------------------------------
+        - `current` -⠀the current progress value (below `0` or greater than `total` hides the bar)
+        - `total` -⠀the total value representing 100% progress (must be greater than `0`)
+        - `label` -⠀an optional label which is inserted at the `{label}` or `{l}` placeholder"""
+        if total <= 0:
+            raise ValueError("Total must be greater than 0.")
+
+        try:
+            if not self.active:
+                self._start_intercepting()
+            self._flush_buffer()
+            self._draw_progress_bar(current, total, label or "")
+            if current < 0 or current > total:
+                self.hide_progress()
+        except Exception:
+            self._emergency_cleanup()
+            raise
+
+    def hide_progress(self) -> None:
+        """Hide the progress bar and restore normal console output."""
+        if self.active:
+            self._clear_progress_line()
+            self._stop_intercepting()
+
+    @contextmanager
+    def progress_context(self, total: int, label: Optional[str] = None) -> Generator[Callable[[int], None], None, None]:
+        """Context manager for automatic cleanup. Returns a function to update progress.\n
+        --------------------------------------------------------------------------------------
+        - `total` -⠀the total value representing 100% progress (must be greater than `0`)
+        - `label` -⠀an optional label which is inserted at the `{label}` or `{l}` placeholder
+        --------------------------------------------------------------------------------------
+        Example usage:
+        ```python
+        with ProgressBar().progress_context(500, "Loading") as update_progress:
+            for i in range(500):
+                # Do some work...
+                update_progress(i)  # Update progress
+        ```"""
+        try:
+
+            def update_progress(current: int) -> None:
+                self.show_progress(current, total, label)
+
+            yield update_progress
+        except Exception:
+            self._emergency_cleanup()
+            raise
+        finally:
+            self.hide_progress()
+
+    def _start_intercepting(self) -> None:
+        self.active = True
+        self._original_stdout = _sys.stdout
+        _sys.stdout = _InterceptedOutput(self)
+
+    def _stop_intercepting(self) -> None:
+        if self._original_stdout:
+            _sys.stdout = self._original_stdout
+            self._original_stdout = None
+        self.active = False
+        self._buffer.clear()
+        self._last_line_len = 0
+        self._current_progress_str = ""
+
+    def _emergency_cleanup(self) -> None:
+        """Emergency cleanup to restore stdout in case of exceptions."""
+        try:
+            self._stop_intercepting()
+        except Exception:
+            pass
+
+    def _flush_buffer(self) -> None:
+        if self._buffer and self._original_stdout:
+            self._clear_progress_line()
+            for content in self._buffer:
+                self._original_stdout.write(content)
+                self._original_stdout.flush()
+            self._buffer.clear()
+
+    def _draw_progress_bar(self, current: int, total: int, label: Optional[str] = None) -> None:
+        if total <= 0 or not self._original_stdout:
+            return
+        percentage = min(100, (current / total) * 100)
+        formatted, bar_width = self._get_formatted_info_and_bar_width(self.bar_format, current, total, percentage, label)
+        if bar_width < self.min_width:
+            formatted, bar_width = self._get_formatted_info_and_bar_width(
+                self.limited_bar_format, current, total, percentage, label
+            )
+        bar = self._create_bar(current, total, max(1, bar_width)) + "[*]"
+        progress_text = _COMPILED["bar"].sub(FormatCodes.to_ansi(bar), formatted)
+        self._current_progress_str = progress_text
+        self._last_line_len = len(progress_text)
+        self._original_stdout.write(f"\r{progress_text}")
+        self._original_stdout.flush()
+
+    def _get_formatted_info_and_bar_width(
+        self,
+        bar_format: str,
+        current: int,
+        total: int,
+        percentage: float,
+        label: Optional[str] = None,
+    ) -> tuple[str, int]:
+        formatted = _COMPILED["label"].sub(label or "", bar_format)
+        formatted = _COMPILED["current"].sub(str(current), formatted)
+        formatted = _COMPILED["total"].sub(str(total), formatted)
+        formatted = _COMPILED["percentage"].sub(f"{percentage:.1f}", formatted)
+        formatted = FormatCodes.to_ansi(formatted)
+        bar_space = Console.w - len(FormatCodes.remove_ansi(_COMPILED["bar"].sub("", formatted)))
+        bar_width = min(bar_space, self.max_width) if bar_space > 0 else 0
+        return formatted, bar_width
+
+    def _create_bar(self, current: int, total: int, bar_width: int) -> str:
+        progress = current / total if total > 0 else 0
+        bar = []
+
+        for i in range(bar_width):
+            pos_progress = (i + 1) / bar_width
+            if progress >= pos_progress:
+                bar.append(self.chars[0])
+            elif progress >= pos_progress - (1 / bar_width):
+                remainder = (progress - (pos_progress - (1 / bar_width))) * bar_width
+                char_idx = len(self.chars) - 1 - min(int(remainder * len(self.chars)), len(self.chars) - 1)
+                bar.append(self.chars[char_idx])
+            else:
+                bar.append(self.chars[-1])
+        return "".join(bar)
+
+    def _clear_progress_line(self) -> None:
+        if self._last_line_len > 0 and self._original_stdout:
+            self._original_stdout.write(f"{ANSI.CHAR}[2K\r")
+            self._original_stdout.flush()
+
+    def _redraw_progress_bar(self) -> None:
+        if self._current_progress_str and self._original_stdout:
+            self._original_stdout.write(f"{self._current_progress_str}")
+            self._original_stdout.flush()
+
+
+class _InterceptedOutput(_io.StringIO):
+    """Custom StringIO that captures output and stores it in the progress bar buffer."""
+
+    def __init__(self, progress_bar: ProgressBar):
+        super().__init__()
+        self.progress_bar = progress_bar
+
+    def write(self, content: str) -> int:
+        try:
+            if content and content != "\r":
+                self.progress_bar._buffer.append(content)
+            return len(content)
+        except Exception:
+            self.progress_bar._emergency_cleanup()
+            raise
+
+    def flush(self) -> None:
+        try:
+            if self.progress_bar.active and self.progress_bar._buffer:
+                self.progress_bar._flush_buffer()
+                self.progress_bar._redraw_progress_bar()
+        except Exception:
+            self.progress_bar._emergency_cleanup()
+            raise

xulbux/format_codes.py

@@ -190,7 +190,7 @@ _COMPILED: dict[str, Pattern] = {  # PRECOMPILE REGULAR EXPRESSIONS
     "ansi_seq": _re.compile(ANSI.CHAR + r"(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])"),
     "formatting": _rx.compile(
         Regex.brackets("[", "]", is_group=True, ignore_in_strings=False)
-        + r"(?:\s*([/\\]?)\s*"
+        + r"(?:([/\\]?)"
         + Regex.brackets("(", ")", is_group=True, strip_spaces=False, ignore_in_strings=False)
         + r")?"
     ),
@@ -317,6 +317,7 @@ class FormatCodes:
             ]
             if auto_reset_txt and not auto_reset_escaped:
                 reset_keys = []
+                default_color_resets = ("_bg", "default") if use_default else ("_bg", "_c")
                 for k in format_keys:
                     k_lower = k.lower()
                     k_set = set(k_lower.split(":"))
@@ -324,7 +325,7 @@ class FormatCodes:
                         if k_set & _PREFIX["BR"]:
                             for i in range(len(k)):
                                 if is_valid_color(k[i:]):
-                                    reset_keys.extend(["_bg", "default"] if use_default else ["_bg", "_c"])
+                                    reset_keys.extend(default_color_resets)
                                     break
                         else:
                             for i in range(len(k)):
@@ -334,7 +335,7 @@ class FormatCodes:
                     elif is_valid_color(k) or any(
                             k_lower.startswith(pref_colon := f"{prefix}:") and is_valid_color(k[len(pref_colon):])
                             for prefix in _PREFIX["BR"]):
-                        reset_keys.append("default" if use_default else "_c")
+                        reset_keys.append(default_color_resets[1])
                     else:
                         reset_keys.append(f"_{k}")
                 ansi_resets = [

xulbux/system.py

@@ -12,7 +12,7 @@ class _IsElevated:
     def __get__(self, obj, owner=None):
         try:
             if _os.name == "nt":
-                return _ctypes.windll.shell32.IsUserAnAdmin() != 0
+                return _ctypes.windll.shell32.IsUserAnAdmin() != 0  # type: ignore[attr-defined]
             elif _os.name == "posix":
                 return _os.geteuid() == 0  # type: ignore[attr-defined]
         except Exception:

{xulbux-1.8.0.dist-info → xulbux-1.8.2.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: xulbux
-Version: 1.8.0
-Summary: A Python library which includes lots of helpful classes, types and functions aiming to make common programming tasks simpler.
+Version: 1.8.2
+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>
 Maintainer-email: XulbuX <xulbux.real@gmail.com>
 License-Expression: MIT

xulbux-1.8.2.dist-info/RECORD

@@ -0,0 +1,20 @@
+xulbux/__init__.py,sha256=NnqeQz_8_t4bkghp5qN3vQEm_Dff6AJBghJsTUVUaks,935
+xulbux/code.py,sha256=CLA3wh6mTvcXTlQgBeFaaLIBciHvXWqVM56rAtfO-JE,6102
+xulbux/color.py,sha256=tTNH30Wf2QNmyopKz4LADdels_TDzDMCptCtm76KkNo,50375
+xulbux/console.py,sha256=b9B1lQzAl5OEhmIlCbTyCyu_WRZwMVOuI-v1GfGtxzo,57308
+xulbux/data.py,sha256=hB9JxrSC7_6kelJ_TwOaapNrlig-jiyNZS3YoiJX8F8,30884
+xulbux/env_path.py,sha256=HGOSffdIDubzczsXe6umyqotrzqhIW83QBkISAamXT8,4157
+xulbux/file.py,sha256=7pa0-WS_DpXq7HRB1fLS6Acd9CM-ozXPpNJvMqCW4fw,2624
+xulbux/format_codes.py,sha256=UwJOH3JJebylYd-MclDvKOG72fhuku63JzZU_eUzMtA,24764
+xulbux/json.py,sha256=Ei5FdCjfM0FrrAEBmuuTcexl7mUY4eirXr-QPct2OS0,7448
+xulbux/path.py,sha256=lLAEVZrW0TAwCewlONFVQcQ_8tVn9LTJZVOZpeGvE5s,7673
+xulbux/regex.py,sha256=_BtMHRDNcD9zF4SL87dQuUVZcYGfZx9H5YNSDiEtzm8,8059
+xulbux/string.py,sha256=QaTo0TQ9m_2USNgQNaVw5ivQt-A1E-e5x8OpIB3xIlY,5561
+xulbux/system.py,sha256=uCjQhqlfOoLkEBdjWn5cLCEnaI4Ac3o9cwRKev07eWI,6612
+xulbux/base/consts.py,sha256=HwgI_Cr_U2QznezN17SP1j-gpyf3tsbu_KHMd8aKzyw,5918
+xulbux/cli/help.py,sha256=wlDTjFhyWQucywMGDmrYIjYn1TV__TwMlYzeSCkQ__U,4403
+xulbux-1.8.2.dist-info/METADATA,sha256=h7DU1OI_NtZNXoq6pFPP1dQhYnDlcbdEbaSsgYajXdc,11042
+xulbux-1.8.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+xulbux-1.8.2.dist-info/entry_points.txt,sha256=aYh89GfiBOB8vw2VPgC6rhBinhnJoAL1kig-3lq_zkg,58
+xulbux-1.8.2.dist-info/top_level.txt,sha256=FkK4EZajwfP36fnlrPaR98OrEvZpvdEOdW1T5zTj6og,7
+xulbux-1.8.2.dist-info/RECORD,,

xulbux-1.8.0.dist-info/RECORD

@@ -1,18 +0,0 @@
-xulbux/__init__.py,sha256=ee9vPsQXG50BOKoVLqUmcClEs-94eYHN3572x0AC3BY,817
-xulbux/code.py,sha256=CLA3wh6mTvcXTlQgBeFaaLIBciHvXWqVM56rAtfO-JE,6102
-xulbux/color.py,sha256=XCB05xBSEz6-dpX9yVkMB2zTSdTH01MfUazJEthL_zM,49741
-xulbux/console.py,sha256=J--5Ma2H3-YPT21pT92J4mNgu-0h_vJJ8M1BLOKbHWc,42773
-xulbux/data.py,sha256=hB9JxrSC7_6kelJ_TwOaapNrlig-jiyNZS3YoiJX8F8,30884
-xulbux/env_path.py,sha256=HGOSffdIDubzczsXe6umyqotrzqhIW83QBkISAamXT8,4157
-xulbux/file.py,sha256=7pa0-WS_DpXq7HRB1fLS6Acd9CM-ozXPpNJvMqCW4fw,2624
-xulbux/format_codes.py,sha256=94VyxnUZI2dS1glteNs7izKYrTI_W2pukFGF5f9k72E,24720
-xulbux/json.py,sha256=Ei5FdCjfM0FrrAEBmuuTcexl7mUY4eirXr-QPct2OS0,7448
-xulbux/path.py,sha256=lLAEVZrW0TAwCewlONFVQcQ_8tVn9LTJZVOZpeGvE5s,7673
-xulbux/regex.py,sha256=_BtMHRDNcD9zF4SL87dQuUVZcYGfZx9H5YNSDiEtzm8,8059
-xulbux/string.py,sha256=QaTo0TQ9m_2USNgQNaVw5ivQt-A1E-e5x8OpIB3xIlY,5561
-xulbux/system.py,sha256=Y5x719Ocwi93VJ6DVE8NR_Js7FQ6QT5wmtjX9FAsw9U,6582
-xulbux-1.8.0.dist-info/METADATA,sha256=Gk3Oj08lJRZuRWrUZ5bkPVjjWy0HIGS4h9UazzDrzP8,11041
-xulbux-1.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-xulbux-1.8.0.dist-info/entry_points.txt,sha256=aYh89GfiBOB8vw2VPgC6rhBinhnJoAL1kig-3lq_zkg,58
-xulbux-1.8.0.dist-info/top_level.txt,sha256=FkK4EZajwfP36fnlrPaR98OrEvZpvdEOdW1T5zTj6og,7
-xulbux-1.8.0.dist-info/RECORD,,