Metadata-Version: 2.4
Name: stylish-terminal
Version: 1.1.0
Summary: Beautiful terminal styling — colors, gradients, animations, pixel art, themes, and more.
Author: uvqz
License-Expression: MIT
Project-URL: Homepage, https://github.com/uvqz/stylish-terminal
Project-URL: Repository, https://github.com/uvqz/stylish-terminal
Project-URL: Issues, https://github.com/uvqz/stylish-terminal/issues
Keywords: terminal,colors,gradients,animations,ascii,cli,styling
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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.10
Description-Content-Type: text/markdown
Provides-Extra: images
Requires-Dist: Pillow>=9.0; extra == "images"

# Stylish — Python

Beautiful terminal styling library. Colors, gradients, animations, pixel art, tables, and more.

## Installation

```bash
pip install Pillow  # Optional: only needed for image/GIF features
```

## Quick Start

```python
from stylish import stylish, log

stylish("Hello World!").red.bold.print()
stylish("Gradient text").gradient(["#ff0000", "#0000ff"]).print()
log.info("Server started")
```

---

## API Reference

### `stylish(text)` — Create a StyledText

Returns a chainable `StyledText` object. Every method returns `self` for chaining.

```python
stylish("text").red.bold.italic.underline.print()
```

### Colors

#### Named colors (as properties)

```python
stylish("text").red.print()
stylish("text").cyan.print()
stylish("text").gold.print()
stylish("text").emerald.print()
```

Available: `black`, `white`, `red`, `green`, `blue`, `yellow`, `cyan`, `magenta`, `orange`, `pink`, `purple`, `lime`, `teal`, `indigo`, `violet`, `coral`, `salmon`, `gold`, `silver`, `gray`, `navy`, `maroon`, `olive`, `aqua`, `crimson`, `turquoise`, `tomato`, `chocolate`, `skyblue`, `lavender`, `peach`, `mint`, `rose`, `azure`, `emerald`, `ruby`, `sapphire`, `amber`

#### Custom colors

```python
stylish("text").fg("#ff6b35").print()          # Hex
stylish("text").fg(100, 200, 50).print()       # RGB
stylish("text").fg("hsl(280, 80%, 60%)").print()  # HSL
stylish("text").fg("rgb(255, 100, 50)").print()   # RGB string
```

#### Background colors

```python
stylish("text").bg("#2d2d2d").print()          # Custom bg
stylish("text").bg(0, 0, 128).print()          # RGB bg
stylish("text").bg_navy.print()                # Named bg (bg_ prefix)
stylish("text").fg("#fff").bg("#9b59b6").print()  # fg + bg
```

### Modifiers

```python
stylish("text").bold.print()
stylish("text").dim.print()
stylish("text").italic.print()
stylish("text").underline.print()
stylish("text").blink.print()
stylish("text").inverse.print()
stylish("text").hidden.print()
stylish("text").strikethrough.print()

# Combine multiple
stylish("text").red.bold.italic.underline.print()
```

### Gradients

```python
# Horizontal (default)
stylish("text").gradient(["#ff0000", "#ffff00", "#00ff00"]).print()

# Vertical
stylish("multi\nline").gradient(["#ff00ff", "#00ffff"], direction="vertical").print()

# Diagonal
stylish("text").gradient(["#f72585", "#4cc9f0"], direction="diagonal").print()

# Reverse diagonal
stylish("text").gradient(["#00ff00", "#ff0000"], direction="diagonal_reverse").print()

# Rainbow shorthand
stylish("text").rainbow().print()
```

### Themes

10 built-in themes that set gradient + modifiers automatically.

```python
stylish("text").theme("neon").print()
stylish("text").theme("cyberpunk").print()
stylish("text").theme("matrix").print()
```

Available: `neon`, `retro`, `ocean`, `forest`, `sunset`, `cyberpunk`, `pastel`, `fire`, `ice`, `matrix`

#### Custom themes

```python
from stylish.themes import Theme, register

register(Theme(
    name="custom",
    primary="#ff0000",
    secondary="#00ff00",
    accent="#0000ff",
    gradient=["#ff0000", "#00ff00", "#0000ff"],
    modifiers=["bold"],
))
stylish("text").theme("custom").print()
```

### Boxes

```python
stylish("text").box("single").print()
stylish("text").box("double").print()
stylish("text").box("rounded").print()
stylish("text").box("heavy").print()
stylish("text").box("ascii").print()

# With padding
stylish("text").box("rounded", padding=2).print()
```

### Centering

```python
stylish("text").center_x().print()   # Horizontal center
stylish("text").center_y().print()   # Vertical center
stylish("text").center().print()     # Both
```

### Animations

```python
stylish("text").typing(speed=0.03).print()
stylish("text").typewriter(speed=0.03).print()
stylish("text").fade_in(duration=1.0).print()
stylish("text").fade_out(duration=1.0).print()
stylish("text").rainbow_cycle(duration=3.0).print()
stylish("text").glitch(duration=2.0, intensity=0.3).print()
stylish("text").pulse(duration=3.0).print()
stylish("text").wave(duration=3.0).print()
stylish("text").bounce(duration=3.0).print()
```

### Side by Side (`+` operator)

```python
left = stylish("Left\nBlock").red.bold
right = stylish("Right\nBlock").cyan.bold

# Using + operator
(left + right).print()

# Using side_by_side with custom spacing
left.side_by_side(right, spacing=8).print()

# Multiple blocks
a.side_by_side(b, c, d, spacing=4).print()
```

### String Conversion

```python
# Use str() to get the ANSI string for embedding
colored = str(stylish("hello").red.bold)
print(f"He said: {colored}")
```

---

## Modules

### `log` — Styled Logger

```python
from stylish import log

log.info("Message")
log.success("Message")
log.warn("Message")
log.error("Message")
log.debug("Message")

# Scoped logger
db = log.scope("DATABASE")
db.info("Running migration...")

# Configure
log.configure(show_time=False, show_icons=False)
```

### `image` — Image & GIF to Terminal

Requires: `pip install Pillow`

```python
from stylish import image

# Pixel art mode (▀▄ half-blocks with true colors)
image.print_pixels("photo.jpg", width=60)

# ASCII art mode (characters with colors)
image.print_image("photo.jpg", width=80)

# GIF animation (pixel art mode by default)
image.play_gif("animation.gif", width=40, loops=3)
image.play_gif("animation.gif", width=40, loops=3, mode="ascii")

# GIF loop for N seconds
image.play_gif_loop("cube.gif", width=40, duration=10.0)
```

### `progress` — Progress Bars & Spinners

```python
from stylish import progress

# Static progress bar
bar = progress.progress_bar(0.75, width=40, colors=["#ff0000", "#00ff00"])
print(bar)

# Animated progress bar
progress.animated_progress(duration=3.0, width=40, colors=["#ff00ff", "#00ffff"])

# Spinner
progress.spinner("Loading...", style="dots", color="#00ffff", duration=3.0)
```

Spinner styles: `dots`, `line`, `circle`, `square`, `arrow`, `bounce`, `moon`, `clock`, `earth`, `blocks`, `star`

### `figlet` — Big ASCII Text

```python
from stylish import figlet, stylish

text = figlet.big_text("HELLO")
stylish(text).gradient(["#ff0000", "#0000ff"]).print()
```

Supports: A-Z, 0-9, `!?.,-_:/#+@=*'"()<>`

### `table` — Styled Tables

```python
from stylish import table

t = table.table(
    headers=["Name", "Score", "Status"],
    rows=[
        ["Alice", "95", "Pass"],
        ["Bob", "82", "Pass"],
    ],
    style="rounded",          # single, double, rounded, heavy, ascii
    header_color="#ff00ff",
    border_color="#555555",
    stripe=True,
    stripe_color="#1a1a2e",
    align="left",             # left, center, right, or list per column
)
print(t)
```

### `panel` — Panels & Separators

```python
from stylish import panel

# Panel with title
print(panel.panel("Content here", title="Title"))

# Separator line
print(panel.separator())
print(panel.separator(char="═", color="#ff00ff"))

# Titled separator
print(panel.titled_separator("Section Name"))
```

### `extras` — Alerts, Countdown, Input

```python
from stylish import extras

# Alerts
extras.alert("Info message", "info")
extras.alert("Success!", "success")
extras.alert("Warning!", "warning")
extras.alert("Error!", "error")

# Countdown
extras.countdown(5, "Starting in")

# Styled input
name = extras.input_styled("Your name?")
name = extras.typewrite_input("Your name?")
```

### `terminal` — Terminal Control

```python
from stylish import terminal

terminal.title("My App")              # Set window title
terminal.clear()                      # Clear screen
terminal.resize(120, 40)             # Resize terminal
terminal.auto_resize(text, padding=4) # Auto resize to text
terminal.beep()                       # System beep
terminal.notify("Done!")              # Windows notification

cols, rows = terminal.size()          # Get terminal size

# Execute commands
output = terminal.execute("Get-Process python")
output = terminal.execute("ls", shell="bash")
```

### `cursor` — Cursor Control

```python
from stylish import cursor

cursor.hide()
# ... do stuff ...
cursor.show()
```

### `banner` — Combine Blocks

```python
from stylish import banner

combined = banner.combine(text1, text2, text3, spacing=4, align="top")
# align: "top", "center", "bottom"
```

### `Color` — Color Engine

```python
from stylish import Color

c = Color.parse("#ff6b35")
c = Color.parse(255, 107, 53)
c = Color.parse("red")
c = Color.parse("hsl(20, 100%, 60%)")

c.lighten(0.2)
c.darken(0.2)
c.saturate(0.1)
c.desaturate(0.1)
c.complement()
c.hex()  # "#ff6b35"

Color.lerp(c1, c2, 0.5)      # RGB interpolation
Color.lerp_hsl(c1, c2, 0.5)  # HSL interpolation
```
