xulbux 1.6.5__tar.gz → 1.6.7__tar.gz

{xulbux-1.6.5/src/xulbux.egg-info → xulbux-1.6.7}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.2
 Name: xulbux
-Version: 1.6.5
-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
@@ -45,6 +45,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: keyboard>=0.13.5
 Requires-Dist: mouse>=0.7.1
+Requires-Dist: prompt_toolkit>=3.0.41
 Requires-Dist: pyperclip>=1.9.0
 Requires-Dist: regex>=2023.10.3
 Provides-Extra: dev
@@ -52,41 +53,54 @@ Requires-Dist: pytest>=7.4.2; extra == "dev"
 Requires-Dist: black>=23.7.0; extra == "dev"
 Requires-Dist: isort>=5.12.0; extra == "dev"
 Requires-Dist: flake8>=6.1.0; extra == "dev"
+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
 
 | | |
 | :--------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------- |
@@ -103,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.5 → xulbux-1.6.7}/README.md

@@ -1,37 +1,49 @@
 # **$\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
 
 | | |
 | :--------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------- |
@@ -48,7 +60,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.5 → xulbux-1.6.7}/pyproject.toml

@@ -4,15 +4,16 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xulbux"
-version = "1.6.5"
+version = "1.6.7"
 authors = [{ name = "XulbuX", email = "xulbux.real@gmail.com" }]
-description = "A library which includes a lot of really helpful functions."
+description = "A Python library which includes lots of helpful classes, types and functions aiming to make common programming tasks simpler."
 readme = "README.md"
 license = { file = "LICENSE" }
 requires-python = ">=3.10.0"
 dependencies = [
   "keyboard>=0.13.5",
   "mouse>=0.7.1",
+  "prompt_toolkit>=3.0.41",
   "pyperclip>=1.9.0",
   "regex>=2023.10.3",
 ]
@@ -21,6 +22,7 @@ optional-dependencies = { dev = [
   "black>=23.7.0",
   "isort>=5.12.0",
   "flake8>=6.1.0",
+  "flake8-pyproject>=1.2.3",
 ] }
 classifiers = [
   "Intended Audience :: Developers",
@@ -45,6 +47,7 @@ keywords = [
   "methods",
   "cmd",
   "console",
+  "constants",
   "code",
   "color",
   "data",
@@ -103,11 +106,11 @@ use_parentheses = true
 ensure_newline_before_comments = true
 
 [tool.flake8]
+max-complexity = 12
 max-line-length = 127
-extend-ignore = ["E203", "E266", "E501", "W503", "E303"]
-max-complexity = 18
-select = ["B", "C", "E", "F", "W", "T4", "B9"]
-per-file-ignores = ["__init__.py:F401,F403"]
+select = ["E", "F", "W", "C90"]
+extend-ignore = ["E203", "E266", "W503"]
+per-file-ignores = ["__init__.py:F403,F405"]
 
 [tool.setuptools]
 packages = ["xulbux"]

{xulbux-1.6.5 → xulbux-1.6.7}/src/xulbux/__init__.py

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

{xulbux-1.6.5 → xulbux-1.6.7}/src/xulbux/_cli_.py

@@ -1,5 +1,5 @@
 from . import __version__
-from ._consts_ import DEFAULT
+from ._consts_ import COLOR
 from .xx_format_codes import FormatCodes
 from .xx_console import Console
 
@@ -7,20 +7,20 @@ from .xx_console import Console
 def help_command():
     """Show some info about the library, with a brief explanation of how to use it."""
     color = {
-        "lib": DEFAULT.color["ice"],
-        "import": DEFAULT.color["red"],
-        "class": DEFAULT.color["lavender"],
-        "types": DEFAULT.color["lightblue"],
-        "punctuators": DEFAULT.color["darkgray"],
+        "lib": COLOR.ice,
+        "import": COLOR.red,
+        "class": COLOR.lavender,
+        "types": COLOR.lightblue,
+        "punctuators": COLOR.darkgray,
     }
     FormatCodes.print(
         rf"""  [_|b|#7075FF]               __  __
   [b|#7075FF]  _  __ __  __/ / / /_  __  ___  __
   [b|#7075FF] | |/ // / / / / / __ \/ / / | |/ /
   [b|#7075FF] > , </ /_/ / /_/ /_/ / /_/ /> , <
-  [b|#7075FF]/_/|_|\____/\__/\____/\____//_/|_|  [*|BG:{DEFAULT.color['gray']}|#000] v[b]{__version__} [*]
+  [b|#7075FF]/_/|_|\____/\__/\____/\____//_/|_|  [*|BG:{COLOR.gray}|#000] v[b]{__version__} [*]
 
-  [i|{DEFAULT.color['coral']}]A TON OF COOL FUNCTIONS, YOU NEED![*]
+  [i|{COLOR.coral}]A TON OF COOL FUNCTIONS, YOU NEED![*]
 
   [b|#75A2FF]Usage:[*]
     [{color['punctuators']}]# GENERAL LIBRARY[*]
@@ -48,6 +48,6 @@ def help_command():
   [_]
   [dim](Press any key to exit...)
   """,
-        default_color=DEFAULT.text_color,
+        default_color=COLOR.text
     )
     Console.pause_exit(pause=True)

xulbux-1.6.7/src/xulbux/_consts_.py

@@ -0,0 +1,181 @@
+from dataclasses import dataclass
+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."""
+
+    text = "#A5D6FF"
+    """The default text color used in the `xulbux` library."""
+
+    white = "#F1F2FF"
+    lightgray = "#B6B7C0"
+    gray = "#7B7C8D"
+    darkgray = "#67686C"
+    black = "#202125"
+    red = "#FF606A"
+    coral = "#FF7069"
+    orange = "#FF876A"
+    tangerine = "#FF9962"
+    gold = "#FFAF60"
+    yellow = "#FFD260"
+    lime = "#C9F16E"
+    green = "#7EE787"
+    teal = "#50EAAF"
+    cyan = "#3EDEE6"
+    ice = "#77DBEF"
+    lightblue = "#60AAFF"
+    blue = "#8085FF"
+    lavender = "#9B7DFF"
+    purple = "#AD68FF"
+    magenta = "#C860FF"
+    pink = "#F162EF"
+    rose = "#FF609F"
+
+
+class _AllTextCharacters:
+    pass
+
+
+@dataclass
+class CHARS:
+    """Text character sets."""
+
+    all = _AllTextCharacters
+    """Code to signal that all characters are allowed."""
+
+    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 `#`"""
+
+    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."""
+
+    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."""
+
+    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) -> 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 ############
+        "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."""