toolsan 0.1.1

Удобная библиотека для консольных программ на Python

---

# toolsan — The All-in-One Python Console Power Tool

**toolsan** (Tools an Aid) is a lightweight, zero-dependency Python library that transforms your terminal from boring black-and-white text into a colorful, animated, and highly interactive environment. It's a Swiss Army knife for console applications: colors, animations, emojis, math parsing, fuzzy string matching, and much more.

[![PyPI version](https://img.shields.io/pypi/v/toolsan.svg)](https://pypi.org/project/toolsan/)
[![Python versions](https://img.shields.io/pypi/pyversions/toolsan.svg)](https://pypi.org/project/toolsan/)

---

## 🚀 Installation

```bash
pip install toolsan

---

📖 Quick Start

import toolsan as ts

ts.superprint(f"Hello, World! {ts.smile}", delay=0.05, color=ts.green)

---

🎨 Colors, Styles & Alignment

Text Colors: ts.black, ts.red, ts.green, ts.yellow, ts.blue, ts.purple, ts.cyan, ts.white

Bright Colors: ts.b_black, ts.b_red, ts.b_green, ts.b_yellow, ts.b_blue, ts.b_purple, ts.b_cyan, ts.b_white

Background Colors: ts.bg_black, ts.bg_red, ts.bg_green, ts.bg_yellow, ts.bg_blue, ts.bg_purple, ts.bg_cyan, ts.bg_white

Bright Backgrounds: ts.bg_b_black, ts.bg_b_red, ts.bg_b_green, ts.bg_b_yellow, ts.bg_b_blue, ts.bg_b_purple, ts.bg_b_cyan, ts.bg_b_white

Text Styles: ts.bold, ts.italic, ts.underline, ts.strike

Alignment: ts.left, ts.center, ts.right

---

✍️ Core Functions

ts.superprint()

Prints text letter by letter with delay, color, background, style, and alignment.

ts.superprint("Normal text")
ts.superprint("Red text", color=ts.red)
ts.superprint("Bold blue", color=ts.blue, style=ts.bold)
ts.superprint("Centered title", side=ts.center, color=ts.yellow, style=ts.bold)
ts.superprint("Slow motion", delay=0.1)

ts.smart_input()

Prints a prompt letter by letter and returns user input with optional type conversion.

name = ts.smart_input("Enter your name: ", delay=0.05, color=ts.yellow)
age = ts.smart_input("Your age: ", typ=int, color=ts.blue)

ts.calculate()

A powerful, safe math parser. Supports +, -, *, /, ** (power), %, (), and functions: sin(), cos(), sqrt(), ln(), log(), log10(), factorial (!), constants π and e.

print(ts.calculate("2 + 2 * 2"))        # 6
print(ts.calculate("2^10"))             # 1024
print(ts.calculate("sqrt(16)"))         # 4.0
print(ts.calculate("5!"))               # 120
print(ts.calculate("sin(90)"))          # 1.0
print(ts.calculate("(10 + 5) * 3"))     # 45

ts.sim(word1, word2, threshold=0.6)

Fuzzy string comparison using Levenshtein distance. Returns True if similar.

ts.sim("hello", "hello")    # True
ts.sim("hello", "helo")     # True
ts.sim("cat", "dog")        # False

ts.loadspin(seconds, speed=10, color='')

Displays a loading spinner animation.

ts.loadspin(3, speed=12, color=ts.cyan)
print("Done!")

ts.bgcolor(color=None)

Fills the entire screen with a background color (or resets).

ts.bgcolor(ts.bg_red)
time.sleep(2)
ts.bgcolor()

ts.countdown(seconds, color=None, bgcolor=None, style=None)

A numeric countdown that overwrites the same line.

ts.countdown(5, color=ts.yellow, style=ts.bold)

ts.wait(seconds)

Alias for time.sleep().

ts.wait(1.5)

---

🔧 Utility Functions

ts.between(text, word=None, left=None, right=None)

Checks if a word is positioned between two other words in a list or string.

ts.between("a b c", word="b", left="a", right="c")   # True

ts.order(list, order)

Returns first, last, or a random element from a list.

ts.order([1,2,3], ts.first)   # 1
ts.order([1,2,3], ts.last)    # 3
ts.order([1,2,3], ts.rand)    # random

ts.flatten(*lists)

Flattens multiple lists into one.

ts.flatten([1,2], [3,4])   # [1, 2, 3, 4]

ts.integers_between(low, high)

Returns a list of integers from low to high inclusive.

ts.integers_between(3, 6)   # [3, 4, 5, 6]

ts.random_obj(list)

Returns a random object from a list.

ts.random_obj([1,2,3])   # random item

ts.error(text), ts.warn(text), ts.success(text), ts.info(text)

Return formatted strings with colors.

print(ts.error("Error!"))
print(ts.warn("Warning!"))
print(ts.success("Success!"))
print(ts.info("Info"))

---

😀 Emojis as Variables

Hundreds of emojis are built-in. Just use them as variables.

print(ts.smile, ts.heart, ts.coffee, ts.pizza, ts.cat, ts.rainbow)

Popular ones: ts.heart, ts.star, ts.fire, ts.thumbs_up, ts.skull, ts.dog, ts.cat, ts.sun, ts.moon, ts.umbrella, ts.gift, ts.trophy, ts.money, ts.gem, ts.melon, ts.apple, ts.pizza, ts.burger, ts.coffee, ts.slot_machine, ts.coin.

---

🎰 Full Example: Console Casino

import random
import toolsan as ts

balance = 100
ts.superprint(f"{ts.slot_machine} WELCOME TO THE CASINO {ts.slot_machine}",
              color=ts.gold, side=ts.center, style=ts.bold)

while balance > 0:
    bet = ts.smart_input("Your bet: ", typ=int, color=ts.yellow)
    if bet > balance:
        ts.superprint("Not enough money!", color=ts.red)
        continue

    ts.loadspin(2, speed=15, color=ts.green)
    result = random.randint(1, 6)
    if result > 4:
        win = bet * 2
        balance += win
        ts.superprint(f"You won! {ts.coin} +{win}", color=ts.green, style=ts.bold)
    else:
        balance -= bet
        ts.superprint(f"You lost. {ts.cry} -{bet}", color=ts.red)

    ts.superprint(f"Balance: {balance} rub.", color=ts.blue)
    if balance <= 0:
        ts.superprint("GAME OVER!", color=ts.red, style=ts.bold)

---

📦 Dependencies

None. toolsan uses only the Python standard library.

---

📄 License

MIT License.

---

👤 Author

Vlad — Backend developer, creator of toolsan.

---

🌟 Support

If you find this library useful, star it on GitHub — it really helps.

Happy coding! 🚀

---