Metadata-Version: 2.4
Name: ragnetto-console
Version: 0.1.0
Summary: ANSI console control utility
Author-email: Gabriele Secci <ragnettosoftware@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 🕷️ ragnetto-console

**Ragnetto-Console** is a lightweight Python utility for terminal manipulation using ANSI escape sequences

It provides an easy-to-use interface for colors, cursor positioning, and non-blocking input handling.

This module is part of the ragnetto software suite.


---


## 🚀 Features

*   **ANSI Colors** : Full support for 16 foreground and background colors.
*   **Cursor Control** : Move (X, Y), toggle visibility (ON/OFF), and change shapes (Block, Bar, Underline).
*   **Advanced Input** : Read single keys immediately without pressing Enter (Non-blocking input) with or without Echo.
*   **Cross-platform** : Support for Unix-like systems (Linux/macOS) and Windows (via PowerShell integration).
*   **Terminal Info** : Auto-detect console width and height.


---


## 📦 Installation

Install the module via [PyPI](https://pypi.org/):

```bash
pip install ragnetto-console
```


---


## 🛠️ Quick Start

```python
from ragnetto import console

# Clear screen and set window title
console.clear()
console.title("Ragnetto-Console Demo")

# Write colored text at specific coordinates (X, Y)
console.write("Welcome to Ragnetto-Console!", "LIGHT_GREEN", "BLACK", 10, 5)

# Read a key without waiting for Enter
print("\nPress any key to exit...")
console.getkey()

# Reset terminal styles to default
console.reset()
```

---


## 📖 API Reference

| Function | Description |
| :--- | :--- |
| `console.clear()` | Clears the screen and resets the cursor to the home position. |
| `console.backcolor()` | Set the background text color. |
| `console.forecolor()` | Set the foreground text color. |
| `console.cursor(state)` | Toggles cursor visibility. |
| `console.caret(shape)` | Changes the cursor shape. |
| `console.position(x, y)` | Moves the cursor to the specified coordinates. |
| `console.write(text, [f], [b], [x], [y])` | Writes text with optional colors and coordinates. |
| `console.getkey()` | Reads a single keypress immediately (No-echo). |
| `console.putkey()` | Reads a single keypress and prints it (Echo). |
| `console.title(text)` | Sets the terminal window title. |
| `console.width()` | Returns the current terminal width. |
| `console.height()` | Returns the current terminal height. |
| `console.reset()` | Resets all styles, colors, and cursor states. |

---
## 💎 Constants

### 🎨 Colors

You can use these strings for foreground (`f`) and background (`b`) parameters:

*   **Standard**: `BLACK`, `RED`, `GREEN`, `YELLOW`, `BLUE`, `MAGENTA`, `CYAN`, `WHITE`
*   **Bright**: `GRAY`, `LIGHT_RED`, `LIGHT_GREEN`, `LIGHT_YELLOW`, `LIGHT_BLUE`, `LIGHT_MAGENTA`, `LIGHT_CYAN`, `LIGHT_WHITE`

### 🖱️ Caret Shapes

Values for the `console.caret(shape)` function:


| Constant | Description |
| :--- | :--- |
| `BLOCK_BLINK` | Blinking block cursor |
| `BLOCK_STEADY` | Static block cursor |
| `UNDERLINE_BLINK` | Blinking underline cursor |
| `UNDERLINE_STEADY` | Static underline cursor |
| `BAR_BLINK` | Blinking vertical bar |
| `BAR_STEADY` | Static vertical bar |


### ⚙️ States

Values for `console.cursor(state)`:
*   `1` or `"ON"`: Show cursor.
*   `0` or `"OFF"`: Hide cursor.

---


## 📝 License

Distributed under the MIT License. See LICENSE for more information.

Author: [ragnetto-gab](https://github.com/ragnetto-gab) (Ragnetto&reg;)

E-Mail: [ragnettosoftware@gmail.com](mailto:ragnettosoftware@gmail.com)
