Skip to content

Commit d767abf

Browse files
xulbuxxulbux
authored
Merge release v1.9.1 into main
Merge version 1.9.1 of “xulbux” into the main branch. For more info on this update, see the change log: https://github.com/XulbuX/PythonLibraryXulbuX/blob/main/CHANGELOG.md#v1-9-1
2 parents 1b34d84 + cd96402 commit d767abf

15 files changed

Lines changed: 601 additions & 194 deletions

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,21 @@
1515
# <br><b>Changelog</b><br>
1616

1717

18+
<span id="v1-9-1" />
19+
20+
## 26.11.2025 `v1.9.1`
21+
* Unified the module and class docstring styles throughout the whole library.
22+
* Moved the Protocol `ProgressUpdater` from the `console` module to the `types` module.
23+
* Added throttling to the `ProgressBar` update methods to impact the actual process' performance as little as possible.
24+
* Added a new class `Spinner` to the `console` module, which is used to display a spinner animation in the console during an ongoing process.
25+
26+
**BREAKING CHANGES:**
27+
* Made the value input into the params `bar_format` and `limited_bar_format` of `ProgressBar` be a list/tuple of strings instead of a single string, so the user can define multiple formats for different console widths.
28+
* Added a new param <code>sep: *str* = " "</code> to the `ProgressBar` class, which is used to join multiple bar-format strings.
29+
* Renamed the class property `Console.wh` to `Console.size`, since it describes the property better.
30+
* Renamed the class property `Console.usr` to `Console.user`, since it describes the property better.
31+
* Added missing type checking to methods in the `path` module.
32+
1833
<span id="v1-9-0" />
1934

2035
## 21.11.2025 `v1.9.0` Big Update 🚀

‎README.md‎

Lines changed: 98 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -42,13 +42,14 @@ When the library is installed, the following commands are available in the conso
4242

4343
## Usage
4444

45-
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()`:
45+
Import the full library under the alias `xx`, so its modules and main classes are accessible with `xx.module.Class`, `xx.MainClass.method()`:
4646
```python
4747
import xulbux as xx
4848
```
49+
4950
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:
5051
```python
51-
# LIBRARY CONSTANTS
52+
# LIBRARY SUB MODULES
5253
from xulbux.base.consts import COLOR, CHARS, ANSI
5354
# Main Classes
5455
from xulbux import Code, Color, Console, ...
@@ -60,21 +61,96 @@ from xulbux.color import rgba, hsla, hexa
6061

6162
## Modules
6263

63-
| Module | Short Description |
64-
| :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |
65-
| [![base](https://img.shields.io/badge/base-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/base) | includes more modules like library constants |
66-
| [![code](https://img.shields.io/badge/code-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/code) | advanced code-string operations (*changing the indent, finding function calls, ...*) |
67-
| [![color](https://img.shields.io/badge/color-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/color) | everything around colors (*converting, blending, searching colors in strings, ...*) |
68-
| [![console](https://img.shields.io/badge/console-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/console) | advanced actions related to the console (*pretty logging, advanced inputs, ...*) |
69-
| [![data](https://img.shields.io/badge/data-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/data) | advanced operations with data structures (*compare, generate path IDs, pretty print, ...*) |
70-
| [![env_path](https://img.shields.io/badge/env__path-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/env_path) | getting and editing the PATH variable (*get paths, check for paths, add paths, ...*) |
71-
| [![file](https://img.shields.io/badge/file-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/file) | advanced working with files (*create files, rename file-extensions, ...*) |
72-
| [![format_codes](https://img.shields.io/badge/format__codes-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/format_codes) | easy pretty printing using custom format codes (*print, inputs, format codes to ANSI, ...*) |
73-
| [![json](https://img.shields.io/badge/json-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/json) | advanced working with json files (*read, create, update, ...*) |
74-
| [![path](https://img.shields.io/badge/path-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/path) | advanced path operations (*get paths, smart-extend relative paths, delete paths, ...*) |
75-
| [![regex](https://img.shields.io/badge/regex-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/regex) | generated regex pattern-templates (*match bracket- and quote pairs, match colors, ...*) |
76-
| [![string](https://img.shields.io/badge/string-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/string) | helpful actions when working with strings. (*normalize, escape, decompose, ...*) |
77-
| [![system](https://img.shields.io/badge/system-B272FC?style=for-the-badge)](https://github.com/XulbuX/PythonLibraryXulbuX/wiki/system) | advanced system actions (*restart with message, check installed Python libs, ...*) |
64+
<table>
65+
<thead>
66+
<tr>
67+
<th align="left">Main Module</th>
68+
<th align="left">Contents</th>
69+
</tr>
70+
</thead>
71+
<tbody>
72+
<tr>
73+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/base"><img src="https://img.shields.io/badge/base-B272FC?style=for-the-badge" alt="base"></a></td>
74+
<td>
75+
<table>
76+
<thead>
77+
<tr>
78+
<th align="left">Sub Module</th>
79+
<th align="left">Contents</th>
80+
</tr>
81+
</thead>
82+
<tbody>
83+
<tr>
84+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/base#consts"><img src="https://img.shields.io/badge/consts-B272FC?style=for-the-badge" alt="consts"></a></td>
85+
<td>Constant values used throughout the library.</td>
86+
</tr>
87+
<tr>
88+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/base#exceptions"><img src="https://img.shields.io/badge/exceptions-B272FC?style=for-the-badge" alt="exceptions"></a></td>
89+
<td>Custom exception classes used throughout the library.</td>
90+
</tr>
91+
<tr>
92+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/base#types"><img src="https://img.shields.io/badge/types-B272FC?style=for-the-badge" alt="types"></a></td>
93+
<td>Custom type definitions used throughout the library.</td>
94+
</tr>
95+
</tbody>
96+
</table>
97+
</td>
98+
</tr>
99+
<tr>
100+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/code"><img src="https://img.shields.io/badge/code-B272FC?style=for-the-badge" alt="code"></a></td>
101+
<td><code>Code</code> class, which includes methods to work with code strings.</td>
102+
</tr>
103+
<tr>
104+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/color"><img src="https://img.shields.io/badge/color-B272FC?style=for-the-badge" alt="color"></a></td>
105+
<td><code>rgba</code> <code>hsla</code> <code>hexa</code> <code>Color</code> classes, which include methods to work with<br>
106+
colors in various formats.</td>
107+
</tr>
108+
<tr>
109+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/console"><img src="https://img.shields.io/badge/console-B272FC?style=for-the-badge" alt="console"></a></td>
110+
<td><code>Console</code> <code>ProgressBar</code> classes, which include methods for logging<br>
111+
and other actions within the console.</td>
112+
</tr>
113+
<tr>
114+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/data"><img src="https://img.shields.io/badge/data-B272FC?style=for-the-badge" alt="data"></a></td>
115+
<td><code>Data</code> class, which includes methods to work with nested data structures.</td>
116+
</tr>
117+
<tr>
118+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/env_path"><img src="https://img.shields.io/badge/env__path-B272FC?style=for-the-badge" alt="env_path"></a></td>
119+
<td><code>EnvPath</code> class, which includes methods to work with the PATH environment variable.</td>
120+
</tr>
121+
<tr>
122+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/file"><img src="https://img.shields.io/badge/file-B272FC?style=for-the-badge" alt="file"></a></td>
123+
<td><code>File</code> class, which includes methods to work with files and file paths.</td>
124+
</tr>
125+
<tr>
126+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/format_codes"><img src="https://img.shields.io/badge/format__codes-B272FC?style=for-the-badge" alt="format_codes"></a></td>
127+
<td><code>FormatCodes</code> class, which includes methods to print and work with strings that contain<br>
128+
special formatting codes, which are then converted to ANSI codes for pretty console output.</td>
129+
</tr>
130+
<tr>
131+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/json"><img src="https://img.shields.io/badge/json-B272FC?style=for-the-badge" alt="json"></a></td>
132+
<td><code>Json</code> class, which includes methods to read, create and update JSON files,<br>
133+
with support for comments inside the JSON data.</td>
134+
</tr>
135+
<tr>
136+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/path"><img src="https://img.shields.io/badge/path-B272FC?style=for-the-badge" alt="path"></a></td>
137+
<td><code>Path</code> class, which includes methods to work with file and directory paths.</td>
138+
</tr>
139+
<tr>
140+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/regex"><img src="https://img.shields.io/badge/regex-B272FC?style=for-the-badge" alt="regex"></a></td>
141+
<td><code>Regex</code> class, which includes methods to dynamically generate complex regex patterns<br>
142+
for common use cases.</td>
143+
</tr>
144+
<tr>
145+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/string"><img src="https://img.shields.io/badge/string-B272FC?style=for-the-badge" alt="string"></a></td>
146+
<td><code>String</code> class, which includes various utility methods for string manipulation and conversion.</td>
147+
</tr>
148+
<tr>
149+
<td><a href="https://github.com/XulbuX/PythonLibraryXulbuX/wiki/system"><img src="https://img.shields.io/badge/system-B272FC?style=for-the-badge" alt="system"></a></td>
150+
<td><code>System</code> class, which includes methods to interact with the underlying operating system.</td>
151+
</tr>
152+
</tbody>
153+
</table>
78154

79155
<br>
80156

@@ -107,11 +183,11 @@ def main() -> None:
107183
)
108184

109185
try:
110-
# TRY TO CONVERT THE INPUT COLOR INTO A hexa() COLOR
186+
# TRY TO CONVERT THE INPUT STRING INTO A hexa() OBJECT
111187
hexa_color = hexa(input_clr)
112188

113189
except ValueError:
114-
# ANNOUNCE THE ERROR AND EXIT THE PROGRAM
190+
# ANNOUNCE THE INVALID INPUT COLOR AND EXIT THE PROGRAM
115191
Console.fail(
116192
"The input HEXA color is invalid.",
117193
end="\n\n",
@@ -125,7 +201,7 @@ def main() -> None:
125201
title_bg_color=COLOR.TANGERINE,
126202
)
127203

128-
# CONVERT THE HEXA COLOR INTO THE TWO OTHER COLOR TYPES
204+
# CONVERT THE HEXA COLOR INTO THE TWO OTHER COLOR FORMATS
129205
rgba_color = hexa_color.to_rgba()
130206
hsla_color = hexa_color.to_hsla()
131207

@@ -135,7 +211,7 @@ def main() -> None:
135211
end="\n\n",
136212
)
137213

138-
# PRETTY PRINT THE COLOR IN DIFFERENT TYPES
214+
# PRETTY PRINT THE COLOR IN DIFFERENT FORMATS
139215
Console.log_box_bordered(
140216
f"[b](HEXA:) [i|white]({hexa_color})",
141217
f"[b](RGBA:) [i|white]({rgba_color})",
@@ -145,6 +221,7 @@ def main() -> None:
145221

146222
if __name__ == "__main__":
147223
main()
224+
148225
```
149226

150227
<br>

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "xulbux"
7-
version = "1.9.0"
7+
version = "1.9.1"
88
authors = [{ name = "XulbuX", email = "xulbux.real@gmail.com" }]
99
maintainers = [{ name = "XulbuX", email = "xulbux.real@gmail.com" }]
1010
description = "A Python library which includes lots of helpful classes, types, and functions aiming to make common programming tasks simpler."

‎src/xulbux/__init__.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
__version__ = "1.9.0"
1+
__version__ = "1.9.1"
22

33
__author__ = "XulbuX"
44
__email__ = "xulbux.real@gmail.com"

‎src/xulbux/base/types.py‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
This module contains all custom type definitions used throughout the library.
33
"""
44

5-
from typing import TYPE_CHECKING, Annotated, TypeAlias, TypedDict, Optional, Union, Any
5+
from typing import TYPE_CHECKING, Annotated, TypeAlias, TypedDict, Optional, Protocol, Union, Any, overload
66
import regex as _rx
77
import re as _re
88

@@ -77,7 +77,6 @@ class AllTextChars:
7777
...
7878

7979

80-
#
8180
################################################## TypedDict ##################################################
8281

8382

@@ -103,3 +102,25 @@ class MissingLibsMsgs(TypedDict):
103102
"""Configuration schema for custom messages in `System.check_libs()` when checking library dependencies."""
104103
found_missing: str
105104
should_install: str
105+
106+
107+
################################################## Protocol ##################################################
108+
109+
110+
class ProgressUpdater(Protocol):
111+
"""Protocol for a progress updater function used in console progress bars."""
112+
113+
@overload
114+
def __call__(self, current: int) -> None:
115+
"""Update the current progress value."""
116+
...
117+
118+
@overload
119+
def __call__(self, current: int, label: str) -> None:
120+
"""Update both current progress value and label."""
121+
...
122+
123+
@overload
124+
def __call__(self, *, label: str) -> None:
125+
"""Update the progress label only (keyword-only)."""
126+
...

0 commit comments

Comments
 (0)