👻 GhostPrint

Cinematic terminal effects, interactive TUIs, and fluid screen transitions for Python
Zero Dependencies • Pure Python • Fully Type-Hinted • Flicker-Free Screen Rendering

---

⚡ Overview

GhostPrint is a robust, zero-dependency Python library designed to build immersive, Hollywood-style CLI tools, setup wizards, and real-time terminal dashboards [README.md].

From dynamic CRT static glitches and interactive multi-select menus to 3D hyperspace starfields and smooth ANSI-safe text wrapping, GhostPrint offers high-performance console formatting while respecting existing terminal scrollback buffers [README.md, setup.py].

---

📦 Installation

Install the package directly from PyPI:

pip install ghostprint

Or install the local development build from source [README.md]:

git clone https://github.com/MRThugh/ghostprint.git
cd ghostprint
pip install .

---

🚀 Interactive Capabilities Demo

GhostPrint has a built-in interactive showcase that demonstrates every single animation, effect, and interface component. Run this command in your Python terminal to experience it:

import ghostprint

# Launches the interactive cinematic capability inspection dashboard
ghostprint.demo()

---

🎨 Global Config & Theme System

GhostPrint v2.0 features a global styling engine. All interface components dynamically lookup default visual styles from ghostprint.Config at runtime. Adjusting the configurations once instantly changes the theme of your entire program:

import ghostprint

# Unify default styling globally
ghostprint.Config.theme_color = ghostprint.MAGENTA
ghostprint.Config.box_style = "round"
ghostprint.Config.spinner_style = "arc"
ghostprint.Config.pointer = "»"

Available Config Properties

Property	Type	Default	Description
theme_color	str	CYAN	Default color for menus, borders, and active selections.
success_color	str	GREEN	Status indicators representing safe or OK outputs.
warning_color	str	YELLOW	Status flags representing alert parameters.
error_color	str	RED	Alert codes representing faults or critical handshakes.
pointer	str	"❯"	Selection indicator in list selectors.
box_style	str	"single"	Border style: "single", "double", "round", "bold", or "block".
spinner_style	str	"dots"	Spinner configuration: "dots", "braille", "line", "arc", or "arrow".
progress_style	str	"blocks"	Block designs: "blocks", "classic", "neon", or "dots".

---

📚 API Reference

1. Colors & Text Formatting

color(text: str, color_code: str) -> str

Wraps a string with standard ANSI terminal escape colors. Always safe and resets automatically.

from ghostprint import color, RED, BOLD

print(color("System Malfunction", RED + BOLD))

gradient(text: str, start_hex: str = None, end_hex: str = None) -> str

Applies a smooth color transition across string characters. If RGB hex parameters are provided, generates a smooth 24-bit TrueColor gradient [README.md].

from ghostprint import gradient

# Smooth cinematic gradient transition
print(gradient("CYBER SECURITY CONSOLE", start_hex="#ff007f", end_hex="#7f00ff"))

markup(text: str) -> str

Translates inline markup tags into ANSI-styled text block. Supports standard nested combinations and RGB TrueColor gradient tags.

from ghostprint import markup

line = markup("System status: [bg_blue][bold][white] ACTIVE [/white][/bold][/bg_blue] on [gradient:#00f2fe:#4facfe]Secure Socket[/gradient]")
print(line)

Supported tags: red, green, yellow, blue, magenta, cyan, white, bold, italic, underline, reverse, bg_red, bg_green, bg_yellow, bg_blue, bg_magenta, bg_cyan, bg_white.

---

2. Layout & UI Effects

box(text: str, style: str = None, auto_wrap: bool = True) -> None

Draws a stylized terminal bounding box. Supports raw newline separations (\n) and automatic console boundary wrapping.

from ghostprint import box

box("Target network authentication completed successfully.\nSecure shell socket mapped.", style="round")

table(headers: list[str], rows: list[list[str]], style: str = None) -> None

Draws auto-aligned columns in a clean structural grid. Safely strips ANSI styling codes during calculation to prevent spacing misalignment.

from ghostprint import table, markup

headers = ["ID", "Process", "Status"]
rows = [
    ["1021", markup("[cyan]Tunnel Proxy[/cyan]"), markup("[green]OK[/green]")],
    ["1094", markup("[cyan]DB Daemon[/cyan]"), markup("[yellow]WARN[/yellow]")],
    ["2011", markup("[cyan]RSA Listener[/cyan]"), markup("[red]FAIL[/red]")]
]
table(headers, rows, style="double")

banner(text: str, fill_char: str = "█", auto_wrap: bool = True) -> None

Renders a high-contrast cinematic visual container around the text block.

from ghostprint import banner

banner("SYSTEM REBOOT INITIATED")

ruler(char: str = "─", color_code: str = None) -> None

Draws a horizontal divider line fitting exactly the active console dimensions.

from ghostprint import ruler, BLUE

ruler(char="═", color_code=BLUE)

---

3. Text & Screen Animations

typewrite(text: str, speed: float = 0.03, end: str = "\n", auto_wrap: bool = True) -> None

Simulates typewriter output. If auto_wrap is active, paragraphs wrap gracefully at terminal width without breaking mid-word.

from ghostprint import typewrite

typewrite("Decrypting satellite uplink transmission packet...", speed=0.02)

loading(text: str = "Loading", duration: float = 3.0, spinner_type: str = None, success_char: str = "✓") -> None

Renders a smooth dynamic loading spinner. Temporarily hides user cursor to keep screen clean.

from ghostprint import loading

loading("Initializing secure handshake", duration=2.5, spinner_type="arc")

progress(duration: float = 3.0, text: str = "Processing", style: str = None, length: int = 30) -> None

Draws an animated progress bar. Fully customizable styles include: blocks, classic, neon, or dots.

from ghostprint import progress

progress(duration=4.0, text="Flushing local system caches", style="neon")

decode(text: str, speed: float = 0.04, color_code: str = None) -> None

Displays a sci-fi hacker decryption effect where characters randomly cycle before locking in.

from ghostprint import decode, GREEN

decode("ACCESS GRANTED", speed=0.05, color_code=GREEN)

flicker_print(text: str, duration: float = 1.0, speed: float = 0.05, active_color: str = None) -> None

Simulates a CRT monitor interference glitch. Scrambles characters, shifts horizontally, and flickers in intensity before stabilizing.

from ghostprint import flicker_print, RED

flicker_print("CRITICAL FILE TAMPERING DETECTED!", duration=1.5, active_color=RED)

stream_logs(count: int = 10, speed: float = 0.05) -> None

Generates a rapid sequence of tech system diagnostics logs.

from ghostprint import stream_logs

stream_logs(count=12, speed=0.06)

---

4. Interactive Utilities

select(options: list[str], prompt: str = "Select:", pointer: str = None, active_color: str = None) -> str | None

Renders an interactive selection menu. Users navigate using Up/Down arrow keys and press Enter to confirm. Returns selected value.

from ghostprint import select

category = select(["Uplink Tunnel", "Local Sandbox", "System Wipe"], prompt="Choose target action:")
print(f"Executing: {category}")

multiselect(options: list[str], prompt: str = "Select options:", pointer: str = None, active_color: str = None, checked_char: str = "■", unchecked_char: str = "□") -> list[str] | None

Displays an interactive list with checkboxes. Use Space to toggle selections and Enter to confirm. Returns a list of selected options.

from ghostprint import multiselect

features = multiselect(["Firewall Bypass", "IP Spoofer", "Cache Purge"], prompt="Select tools to deploy:")
print(f"Deploying tools: {features}")

secure_input(prompt: str = "Password: ", mask: str = "*") -> str

Securely reads a user password by printing a custom masking symbol instead of plain text. Supports Backspace.

from ghostprint import secure_input

credentials = secure_input("Enter Root Access Key: ", mask="■")

wait_key(prompt: str = "Press any key to continue...") -> None

Halts execution until a key is pressed, working instantly without requiring Enter [utils.py].

from ghostprint import wait_key

wait_key("Press any key to initiate self-test...")

clear() -> None

Clears terminal window cross-platform.

from ghostprint import clear

clear()

center(text: str, width: int = None) -> str

Dynamically aligns a text block perfectly centered relative to the active console width.

from ghostprint import center

print(center("System Locked"))

wrap(text: str, width: int = None) -> list[str]

Line wraps a long paragraph while preserving inline ANSI escape styling strings intact.

from ghostprint import wrap

lines = wrap("Your long styled text...", width=50)
for line in lines:
    print(line)

---

5. Advanced Interactive Rendering

Live Context Manager

The Live context manager permits in-place rendering of dynamic, multi-line blocks. Highly efficient and flicker-free because it overwrites exactly the modified output coordinates.

import time
from ghostprint import Live, markup

with Live() as live:
    for i in range(101):
        dashboard = (
            f"=== [bold]System Node Dashboard[/bold] ===\n"
            f"CPU Load: {i}%\n"
            f"Network: [\033[92mActive\033[0m]\n"
            f"Progress: [{i}/100]"
        )
        live.update(markup(dashboard))
        time.sleep(0.05)

---

6. Full-Screen Visual Transitions

matrix_rain(duration: float = 5.0, speed: float = 0.05) -> None

Transitions terminal screen with full-screen classic Matrix falling rain streams. Fully clean teardown on abort [animations.py].

from ghostprint import matrix_rain

matrix_rain(duration=5.0)

starfield(duration: float = 5.0, speed: float = 0.03) -> None

Starts a cinematic 3D Hyperspace Warp Drive starfield on screen. Runs beautifully on modern terminals [animations.py].

from ghostprint import starfield

starfield(duration=4.0)

hacker_typer(code: str, chars_per_key: int = 3, prompt: str = ..., color_code: str = None) -> None

Launches an interactive keypress coding simulation. Smashing any keys streams pre-defined exploit source codes onto the screen. Exit with ESC.

from ghostprint import hacker_typer

source_code = """
#include <sys/socket.h>
int main() {
    int s = socket(AF_INET, SOCK_STREAM, 0);
    connect(s, &addr, sizeof(addr));
    send(s, "PAYLOAD", 7, 0);
}
"""

hacker_typer(source_code)

---

👨‍💻 Author & Contribution

Developed and maintained by Ali Kamrani.

• GitHub: https://github.com/MRThugh
• Email: kamrani.exe@gmail.com

---

📄 License

This library is open-source software licensed under the MIT License.