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
• LOLCODE: An esoteric language based on lolspeak

Requirements:

As of 1.3.0, this package no longer bundles precompiled interpreter binaries. Instead, it looks for an interpreter already installed on your system:

• Befunge: an executable named bef98 on your PATH
• LOLCODE: an executable named lci on your PATH (e.g. lci)

If you have an interpreter installed under a different name or location, point to it explicitly with an environment variable instead of relying on PATH lookup:

export FORMATTING_LIBRARY_BEFUNGE_BIN=/path/to/your/bef98
export FORMATTING_LIBRARY_LOLCODE_BIN=/path/to/your/lci

If no interpreter is found, runBefunge/runLOLCODE raise a FileNotFoundError with installation instructions rather than failing silently.

Why the change? Previously this package shipped precompiled Linux/macOS/Windows binaries inside the wheel. That meant installing formatting-library also installed opaque, unauditable executables that were then run by the library on your files. Resolving the interpreter from your own system means you're only ever running binaries you installed and vetted yourself — the package itself stays pure Python.

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)
• Befunge and/or LOLCODE interpreters installed separately and available on PATH (only needed if you use Esoteric/runBefunge/runLOLCODE)

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.