xulbux 1.6.6__tar.gz → 1.6.8__tar.gz

{xulbux-1.6.6/src/xulbux.egg-info → xulbux-1.6.8}/PKG-INFO

@@ -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.8
+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: args,arguments,attributes,classes,cmd,client,code,codes,color,commands,console,consts,constants,convert,conversion,data,debug,easier,env,environment,error,file,format,formatting,functions,helper,hex,hexa,hsl,hsla,info,input,json,library,log,logging,methods,nice,operations,path,presets,pretty,printing,properties,python,re,regex,rgb,rgba,string,structures,system,tools,types,utility,warn,warning,xulbux
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
@@ -57,41 +57,53 @@ 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
 
-| | |
-| :--------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------- |
+| Module                                                                                           | Short Description                                                                                  |
+| :----------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------- |
 | <h3>[`xx_code`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_code)</h3>                 | advanced code-string operations (*changing the indent, finding function calls, ...*)               |
 | <h3>[`xx_color`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_color)</h3>               | everything around colors (*converting, blending, searching colors in strings, ...*)                |
 | <h3>[`xx_console`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_console)</h3>           | advanced actions related to the console (*pretty logging, advanced inputs, ...*)                   |
@@ -99,13 +111,78 @@ from xulbux import rgba, hsla, hexa
 | <h3>[`xx_env_path`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_env_path)</h3>         | getting and editing the PATH variable (*get paths, check for paths, add paths, ...*)               |
 | <h3>[`xx_file`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_file)</h3>                 | advanced working with files (*create files, rename file-extensions, ...*)                          |
 | <h3>[`xx_format_codes`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_format_codes)</h3> | easy pretty printing with custom format codes (*print, inputs, custom format codes to ANSI, ...*)  |
-| <h3>`xx_json`</h3>                                                                                   | advanced working with json files (*read, create, update, ...*)                                     |
-| <h3>`xx_path`</h3>                                                                                   | advanced path operations (*get paths, smart-extend relative paths, delete paths, ...*)             |
-| <h3>`xx_regex`</h3>                                                                                  | generated regex pattern-templates (*match bracket- and quote pairs, match colors, ...*)            |
+| <h3>`xx_json`</h3>                                                                               | advanced working with json files (*read, create, update, ...*)                                     |
+| <h3>`xx_path`</h3>                                                                               | advanced path operations (*get paths, smart-extend relative paths, delete paths, ...*)             |
+| <h3>`xx_regex`</h3>                                                                              | generated regex pattern-templates (*match bracket- and quote pairs, match colors, ...*)            |
 | <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, ...*)                 |
+| <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.8/README.md

@@ -0,0 +1,132 @@
+# **$\color{#8085FF}\Huge\textsf{XulbuX}$**
+
+**$\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 and updates, see the [change log](https://github.com/XulbuX/PythonLibraryXulbuX/blob/main/CHANGELOG.md).
+
+<br>
+
+## Installation
+
+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
+```
+
+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 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 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
+
+| Module                                                                                           | Short Description                                                                                  |
+| :----------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------- |
+| <h3>[`xx_code`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_code)</h3>                 | advanced code-string operations (*changing the indent, finding function calls, ...*)               |
+| <h3>[`xx_color`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_color)</h3>               | everything around colors (*converting, blending, searching colors in strings, ...*)                |
+| <h3>[`xx_console`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_console)</h3>           | advanced actions related to the console (*pretty logging, advanced inputs, ...*)                   |
+| <h3>[`xx_data`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_data)</h3>                 | advanced operations with data structures (*compare, generate path ID's, pretty print/format, ...*) |
+| <h3>[`xx_env_path`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_env_path)</h3>         | getting and editing the PATH variable (*get paths, check for paths, add paths, ...*)               |
+| <h3>[`xx_file`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_file)</h3>                 | advanced working with files (*create files, rename file-extensions, ...*)                          |
+| <h3>[`xx_format_codes`](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/xx_format_codes)</h3> | easy pretty printing with custom format codes (*print, inputs, custom format codes to ANSI, ...*)  |
+| <h3>`xx_json`</h3>                                                                               | advanced working with json files (*read, create, update, ...*)                                     |
+| <h3>`xx_path`</h3>                                                                               | advanced path operations (*get paths, smart-extend relative paths, delete paths, ...*)             |
+| <h3>`xx_regex`</h3>                                                                              | generated regex pattern-templates (*match bracket- and quote pairs, match colors, ...*)            |
+| <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>
+
+--------------------------------------------------------------
+[View this library on PyPI](https://pypi.org/project/XulbuX/)

{xulbux-1.6.6 → xulbux-1.6.8}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xulbux"
-version = "1.6.6"
+version = "1.6.8"
 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"
@@ -35,33 +35,64 @@ classifiers = [
   "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 keywords = [
-  "xulbux",
-  "python",
-  "library",
-  "utility",
-  "helper",
-  "functions",
-  "tools",
+  "args",
+  "arguments",
+  "attributes",
   "classes",
-  "types",
-  "methods",
   "cmd",
-  "console",
+  "client",
   "code",
+  "codes",
   "color",
+  "commands",
+  "console",
+  "consts",
+  "constants",
+  "convert",
+  "conversion",
   "data",
-  "structures",
+  "debug",
+  "easier",
   "env",
   "environment",
+  "error",
   "file",
   "format",
+  "formatting",
+  "functions",
+  "helper",
+  "hex",
+  "hexa",
+  "hsl",
+  "hsla",
+  "info",
+  "input",
   "json",
+  "library",
+  "log",
+  "logging",
+  "methods",
+  "nice",
+  "operations",
   "path",
+  "presets",
+  "pretty",
+  "printing",
+  "properties",
+  "python",
+  "re",
   "regex",
+  "rgb",
+  "rgba",
   "string",
+  "structures",
   "system",
-  "operations",
-  "presets",
+  "tools",
+  "types",
+  "utility",
+  "warn",
+  "warning",
+  "xulbux",
 ]
 
 [project.urls]

{xulbux-1.6.6 → xulbux-1.6.8}/src/xulbux/__init__.py

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

{xulbux-1.6.6 → xulbux-1.6.8}/src/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-1.6.6 → xulbux-1.6.8}/src/xulbux/xx_code.py

@@ -21,14 +21,13 @@ class Code:
         non_zero_indents = [i for i in indents if i > 0]
         return min(non_zero_indents) if non_zero_indents else 0
 
-    @staticmethod
-    def change_tab_size(code: str, new_tab_size: int, remove_empty_lines: bool = False) -> str:
+    def change_tab_size(self, code: str, new_tab_size: int, remove_empty_lines: bool = False) -> str:
         """Replaces all tabs with `new_tab_size` spaces.\n
         ----------------------------------------------------------------------------------
         If `remove_empty_lines` is `True`, empty lines will be removed in the process."""
         code_lines = String.get_lines(code, remove_empty_lines=True)
         lines = code_lines if remove_empty_lines else String.get_lines(code)
-        tab_spaces = Code.get_tab_spaces(code)
+        tab_spaces = self.get_tab_spaces(code)
         if (tab_spaces == new_tab_size) or tab_spaces == 0:
             if remove_empty_lines:
                 return "\n".join(code_lines)