Metadata-Version: 2.4
Name: ghostprint
Version: 2.0.0
Summary: Cinematic and hacker-style terminal text animations and effects for Python.
Home-page: https://github.com/MRThugh/ghostprint
Author: Ali Kamrani
Author-email: Ali Kamrani <kamrani.exe@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/MRThugh/ghostprint
Project-URL: BugTracker, https://github.com/MRThugh/ghostprint/issues
Project-URL: Repository, https://github.com/MRThugh/ghostprint.git
Keywords: terminal,animation,glitch,cli,hacker-ui,truecolor,gradient,tui
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Terminals
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 👻 GhostPrint

<p align="center">
  <img src="https://img.shields.io/pypi/v/ghostprint?color=blue&label=PyPI" />
  <img src="https://img.shields.io/pypi/pyversions/ghostprint" />
  <img src="https://img.shields.io/github/license/MRThugh/ghostprint" />
  <img src="https://img.shields.io/badge/style-cinematic-black" />
</p>

<p align="center">
  <b>Cinematic terminal effects, interactive TUIs, and fluid screen transitions for Python</b><br/>
  Zero Dependencies • Pure Python • Fully Type-Hinted • Flicker-Free Screen Rendering
</p>

---

## ⚡ 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:

```bash
pip install ghostprint
```

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

```bash
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:

```python
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:

```python
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.

```python
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].

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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`.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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.

```python
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].

```python
from ghostprint import wait_key

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

#### `clear() -> None`
Clears terminal window cross-platform.

```python
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.

```python
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.

```python
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.

```python
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].

```python
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].

```python
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**.

```python
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](https://github.com/MRThugh)  
- **Email:** [kamrani.exe@gmail.com](mailto:kamrani.exe@gmail.com)  

---

## 📄 License

This library is open-source software licensed under the [MIT License](LICENSE).
