Kundaliel's Formatting Library

A Python library for terminal text formatting, colors, and ASCII art rendering.

Features

• RGB color support for foreground and background
• Rainbow text effects
• Image to ASCII art conversion
• Animated/slow printing
• Text color codes
• Terminal cursor control and manipulation

Installation

pip install formatting-library

Quick Start

from formatting_library import rainbow_text, slow_print, img_to_ascii, PrintOptions

# Rainbow text
print(rainbow_text("Hello, World!"))

# Slow printing with custom speed
options = PrintOptions(speed=20)
slow_print("This text appears slowly...", options)

# Convert image to ASCII art
ascii_art = img_to_ascii("path/to/image.jpg")
print(ascii_art)

Documentation

Color Functions

from formatting_library import rgb_fore, rgb_back, RGB, RESET

# Using RGB values directly
print(f"{rgb_fore([255, 0, 0])}Red text{RESET}")

# Using RGB class
red = RGB(255, 0, 0)
print(f"{red.to_foreground()}Red text{RESET}")

# Background colors
print(f"{rgb_back([0, 255, 0])}Green background{RESET}")

Rainbow Text

from formatting_library import rainbow_text

# Foreground rainbow
print(rainbow_text("This text has rainbow colors!"))

# Background rainbow
print(rainbow_text("Rainbow background!", background=True))

Terminal Control

from formatting_library import clear_screen, set_cursor_position, Terminal

# Clear the screen
clear_screen()

# Move cursor to specific position
set_cursor_position(10, 5)  # Move cursor to row 10, column 5

# Replace current line
Terminal.replace_current_line("New text on this line")

Text Formatting

from formatting_library import align, substitute

# Text alignment
text = "Hello World"
print(align(text, 20, "center"))   # Center align in 20 characters
print(align(text, 20, "right"))    # Right align
print(align(text, 20, "left"))     # Left align

# Text substitution
original = "Hello World"
modified = substitute(original, "Python", 6)  # Replace from position 6
print(modified)  # Output: "Hello Python"

Slow Printing

from formatting_library import slow_print, PrintOptions, RGB

# Basic slow print
slow_print("This appears character by character!")

# Custom options
options = PrintOptions(
    speed=15.0,  # Characters per second
    text_color=[255, 100, 50],  # Orange text
    background_color=[0, 0, 0],  # Black background
    newline_delay=1.0  # Pause at newlines
)
slow_print("Customized slow text!", options)

Text Color Codes

from formatting_library import formatted

# Use text color codes
text = "&cRed &aGreen &9Blue &lBold &nUnderline &rReset"
print(formatted(text))

# Available codes:
# &0-&f: Colors (0=black, f=white, etc.)
# &l: Bold
# &n: Underline  
# &o: Italic
# &r: Reset

Image to ASCII Art

from PIL import Image
from formatting_library import img_to_ascii

# Convert any image to colorful ASCII art
img: Image = Image.open('karel.jpg').convert('RGB')

width: int
height: int
width, height = img.size

new_width: int = 70
ratio: float = width / new_width

new_size: tuple[int, int] = (new_width, int(height/ratio))
resized: Image = img.resize(new_size)

resized.save('karel_resized.jpg')

print(img_to_ascii('karel_resized.jpg'))

# Works with various image formats: JPG, PNG, GIF, etc.

Print Boxes

from formatting_library import ccb_gen

# Create decorative text boxes
ccb_gen("Important Message")
# Output:
# # ================= #
# # Important Message #
# # ================= #

Advanced Usage

Custom RGB Colors

from formatting_library import RGB, ColorFuncs

# Create RGB color objects
red = RGB(255, 0, 0)
green = RGB(0, 255, 0)
blue = RGB(0, 0, 255)

# Use in dual colors (background + foreground)
print(f"{red.to_dual(blue)}Red background, blue text{RESET}")

# Static methods
print(f"{ColorFuncs.rgb_fore([128, 64, 192])}Custom purple{RESET}")

Terminal Manipulation

from formatting_library import Terminal

# Terminal control
Terminal.scroll_cursor(-3)  # Move cursor up 3 lines
Terminal.replace_line(5, "New content for line 5")
Terminal.set_cursor_position(1, 1)  # Top-left corner

Color Reference

Rainbow Colors

The built-in rainbow uses these RGB values:

• Light Red: (255, 179, 179)
• Light Orange: (255, 217, 179)
• Light Yellow: (255, 255, 179)
• Light Green: (179, 255, 179)
• Light Blue: (179, 179, 255)
• Light Purple: (217, 179, 255)

Text Color Codes

• &0 - Black
• &1 - Dark Blue
• &2 - Dark Green
• &3 - Dark Aqua
• &4 - Dark Red
• &5 - Dark Purple
• &6 - Gold
• &7 - Gray
• &8 - Dark Gray
• &9 - Blue
• &a - Green
• &b - Aqua
• &c - Red
• &d - Light Purple
• &e - Yellow
• &f - White
• &l - Bold
• &n - Underline
• &o - Italic
• &r - Reset

Requirements

• Python 3.8+
• Pillow (for image processing)

Examples

Create a Colorful Banner

from formatting_library import rainbow_text, ccb_gen, clear_screen

clear_screen()
ccb_gen("WELCOME")
print()
print(rainbow_text("- Terminal Formatter Demo -"))
print(rainbow_text("=" * 50))

Animated Greeting

from formatting_library import slow_print, PrintOptions, clear_screen

clear_screen()
options = PrintOptions(speed=10, text_color=[0, 255, 0])
slow_print("Hello! Welcome to Terminal Formatter!", options)

Image Gallery

from formatting_library import img_to_ascii
import os

for filename in os.listdir("images/"):
    if filename.lower().endswith(('.png', '.jpg', '.jpeg')):
        print(f"\n--- {filename} ---")
        print(img_to_ascii(f"images/{filename}"))

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.