Metadata-Version: 2.4
Name: format_printing
Version: 0.1.0
Summary: Colorful, styled terminal printing for Python
Author-email: Your Name <you@email.com>
License: MIT License
        
        Copyright (c) 2026 Ranveer Singh
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: ansi,cli,color,printing,terminal
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# format_printing

A Python library for rich, styled terminal output — colors, gradients, tables, spinners, progress bars, and more. Works as a drop-in replacement for Python's built-in `print` and `input`.

```bash
pip install format_printing
```

---

## Features

- Colored and styled text (bold, italic, underline, strikethrough, dim)
- Named colors, hex colors, and RGB tuples
- Gradient text (per-character color blending)
- Bordered boxes
- Auto-sized tables from dicts or lists
- Clickable terminal hyperlinks
- Typewriter effect printing
- Spinner animations (context manager or function-wrapping)
- Progress bars (function-wrapping or fixed-duration)

---

## Quick Start

```python
from format_printing import print, print_box, print_gradient, spinner, progress_bar
```

---

## Colors

Colors can be passed as:
- A named string: `"red"`, `"cyan"`, `"neon_pink"`, `"gold"`, etc.
- A hex string: `"#ff6600"`
- An RGB tuple: `(255, 100, 0)`

**Built-in named colors:**
`red`, `orange`, `yellow`, `green`, `blue`, `indigo`, `violet`, `black`, `white`, `brown`, `grey` / `gray`, `cyan`, `magenta`, `neon_pink`, `gold`, `crimson`

---

## API Reference

### `print(*args, color, bg, bold, dim, italic, underline, strikethrough)`

Drop-in replacement for the built-in `print`. Accepts all standard `print` keyword arguments.

```python
from format_printing import print

print("Hello, world!", color="cyan", bold=True)
print("Warning!", color="#ff6600", bg="black", underline=True)
print("Soft text", dim=True)
```

---

### `print_type(*args, color, bg, bold, dim, italic, underline, strikethrough, delay)`

Prints text character by character with a typewriter effect.

```python
from format_printing import print_type

print_type("Loading complete.", color="green", delay=0.05)
```

| Param | Default | Description |
|-------|---------|-------------|
| `delay` | `0.03` | Seconds between each character |

---

### `input(prompt, color, bg, bold, dim, italic, underline, strikethrough)`

Drop-in replacement for the built-in `input` with styled prompts.

```python
from format_printing import input

name = input("Enter your name: ", color="yellow", bold=True)
```

---

### `clear()`

Clears the terminal screen.

```python
from format_printing import clear

clear()
```

---

### `print_box(*args, color, border_color, bold, dim, italic, padding)`

Prints text inside a Unicode bordered box.

```python
from format_printing import print_box

print_box("Operation complete!", color="green", border_color="cyan", padding=2)
```

| Param | Default | Description |
|-------|---------|-------------|
| `padding` | `1` | Horizontal padding inside the box |

---

### `print_gradient(*args, start, end)`

Prints text with a smooth per-character color gradient.

```python
from format_printing import print_gradient

print_gradient("Rainbow text!", start="red", end="blue")
print_gradient("Sunset vibes", start="#ff6600", end="#ffcc00")
```

---

### `print_dual_gradient(*args, text_start, text_end, bg_start, bg_end)`

Prints text with independent gradients for both foreground and background.

```python
from format_printing import print_dual_gradient

print_dual_gradient("Fancy!", text_start="white", text_end="yellow", bg_start="blue", bg_end="magenta")
```

---

### `print_table(data, border_color, header_color)`

Prints an auto-sized, aligned table. Accepts a list of dicts or a list of lists (first row = headers).

```python
from format_printing import print_table

# From dicts
data = [
    {"Name": "Alice", "Role": "Engineer", "Level": "Senior"},
    {"Name": "Bob",   "Role": "Designer", "Level": "Mid"},
]
print_table(data, border_color="grey", header_color="cyan")

# From lists
data = [
    ["Name", "Score"],
    ["Alice", "98"],
    ["Bob",   "87"],
]
print_table(data)
```

---

### `print_link(text, url, color, bold, underline)`

Prints a clickable hyperlink (supported in most modern terminals).

```python
from format_printing import print_link

print_link("Visit PyPI", "https://pypi.org", color="cyan", bold=True)
```

---

### `loading_context(message, color, done)`

A context manager that shows a spinner while a block of code runs.

```python
from format_printing import loading_context
import time

with loading_context("Fetching data", color="cyan", done="Data loaded!"):
    time.sleep(2)
```

| Param | Default | Description |
|-------|---------|-------------|
| `message` | `"Processing"` | Text shown next to the spinner |
| `color` | `"cyan"` | Spinner color |
| `done` | `"Done!"` | Message shown on completion |

---

### `spinner(message, fn, *args, duration, spinner_color, color, done, **kwargs)`

Two modes:

**Fixed duration** — spins for a set number of seconds:
```python
from format_printing import spinner

spinner("Warming up", duration=2.0, spinner_color="magenta")
```

**Function-wrapping** — spins until a function finishes, then returns its result:
```python
from format_printing import spinner
import time

def fetch_data(url):
    time.sleep(2)
    return {"status": "ok"}

result = spinner("Fetching", fetch_data, "https://example.com", done="Fetched!")
print(result)
```

| Param | Default | Description |
|-------|---------|-------------|
| `duration` | `2.0` | Seconds to spin (fixed mode only) |
| `spinner_color` | `"cyan"` | Color of the spinner character |
| `color` | `None` | Color of the message text |
| `done` | `"Done!"` | Completion message |

---

### `progress_bar(fn, *args, message, bar_color, bracket_color, text_color, length, duration, done, **kwargs)`

Two modes:

**Fixed duration** — fills the bar over a set number of seconds:
```python
from format_printing import progress_bar

progress_bar(duration=3.0, message="Installing", bar_color="green")
```

**Function-wrapping** — fills the bar while a function runs:
```python
from format_printing import progress_bar
import time

def process():
    time.sleep(3)
    return "finished"

result = progress_bar(process, message="Processing", done="Complete!")
print(result)
```

| Param | Default | Description |
|-------|---------|-------------|
| `message` | `"Processing"` | Label shown next to the bar |
| `bar_color` | `"green"` | Color of the filled portion |
| `bracket_color` | `"grey"` | Color of the `[ ]` brackets |
| `text_color` | `None` | Color of the message text |
| `length` | `20` | Width of the bar in characters |
| `duration` | `3.0` | Seconds to fill (fixed mode only) |
| `done` | `"Done!"` | Completion message |

---

## License

MIT License — see [LICENSE](LICENSE) for details.