formatting-library 1.2.5.1

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

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
• C library integration for performance-critical operations
• Esoteric programming language execution (Befunge, LOLCODE)

Installation

pip install formatting-library

Quick Start

from formatting_library import rainbow_text, slow_print, img_to_ascii

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

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

# 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 formatting_library import img_to_ascii

# Convert any image to colorful ASCII art
ascii_art = img_to_ascii("photo.jpg")
print(ascii_art)

# 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

Esoteric Programming Languages

Execute esoteric programming languages directly from Python:

from formatting_library import Esoteric, runBefunge, runLOLCODE

# Run Befunge programs
Esoteric.runBefunge("hello.bf")

# Run LOLCODE programs
Esoteric.runLOLCODE("hello.lol")

# Or use the convenient aliases
runBefunge("program.bf")
runLOLCODE("script.lol")

Supported Languages:

• Befunge: A two-dimensional esoteric programming language
  • Supported platforms: Linux, macOS
• LOLCODE: An esoteric language based on lolspeak
  • Supported platforms: Linux, macOS, Windows

Requirements:

• Language interpreters are included in the package under _bin/ directory
• Executables are platform-specific and selected automatically

Example Befunge Program (hello.bf):

"!dlroW ,olleH">:#,_@

Example LOLCODE Program (hello.lol):

HAI 1.2
  VISIBLE "Hello, World!"
KTHXBYE

C Library Integration

⚠️ Security Warning: The CBuilder class uses os.system() to compile C code and creates directories on your filesystem. Only use with trusted C source files and in secure environments. The build process will:

• Execute GCC compiler commands via shell
• Create a build/ directory in the specified location
• Generate .so shared library files
• Overwrite existing files with the same name

For performance-critical operations, you can compile and use C libraries:

// main.c
#include <stdio.h>
#include <stdint.h>

void say(char *input) {
    printf("%s\n", input);
}

int fast_multiply(int a, int b) {
    return a * b;
}

# main.py
from formatting_library import CBuilder
import ctypes

# Build the C library
builder = CBuilder(".", "main")

# Define functions with proper types
say = builder.define_function("say", [ctypes.c_char_p])
multiply = builder.define_function("fast_multiply", 
                                 [ctypes.c_int, ctypes.c_int], 
                                 ctypes.c_int)

# Use the functions
say(b"Hello from C!")
result = multiply(42, 24)
print(f"42 * 24 = {result}")

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)
• GCC (for C library compilation)
• Platform-specific esoteric language interpreters (included in package)

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}"))

Esoteric Language Runner

from formatting_library import runBefunge, runLOLCODE

# Create a simple Befunge program
with open("hello.bf", "w") as f:
    f.write("""\
>                                            v
@,*25,++:*:*:+111,,,,,,,,,,,,,"Hello Befunge"<
    """)

# Run it
print("Running Befunge greeting:")
runBefunge("hello.bf")

# Create a LOLCODE program
with open("greeting.lol", "w") as f:
    f.write("""
HAI 1.4
  VISIBLE "O HAI, can I haz cheezburger?"
KTHXBYE
""")

# Run it
print("\nRunning LOLCODE greeting:")
runLOLCODE("greeting.lol")

Performance Comparison

from formatting_library import CBuilder, ctypes
import time

# Python version
def python_factorial(n):
    if n <= 1:
        return 1
    return n * python_factorial(n - 1)

# C version (factorial.c)
builder = CBuilder(".", "factorial")
c_factorial = builder.define_function("factorial", [ctypes.c_int], ctypes.c_int)

# Benchmark
start = time.time()
python_result = python_factorial(20)
python_time = time.time() - start

start = time.time()
c_result = c_factorial(20)
c_time = time.time() - start

print(f"Python: {python_result} ({python_time:.6f}s)")
print(f"C: {c_result} ({c_time:.6f}s)")

License

MIT License - see LICENSE file for details.

Contributing

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