# 😎 Prime Printer 👀
Console I/O Helper - Print Awesome. Make It Prime 🚀
<img src="https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/logo.png"></img>
Easy Usage, Easy handling, BIG Improvement for your needs 🎯
Easy Installation -> https://pypi.org/project/prime-printer/
```bash
pip install prime_printer
```
<br>
**⚡Quick Look⚡**
🖨️ Printing with Delay, Type-Sound, Control, Conditions and Stylings:
<div style="display: flex; gap: 15px; flex-wrap: wrap; justify-content: center;">
<img src="https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_colored_delay_sound_print.gif" style="border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;" onmouseover="this.style.transform='scale(1.05)'" onmouseout="this.style.transform='scale(1)'"/>
<img src="https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_game_menu.gif" style="border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;" onmouseover="this.style.transform='scale(1.05)'" onmouseout="this.style.transform='scale(1)'"/>
<img src="https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_input_with_condition.gif" style="border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;" onmouseover="this.style.transform='scale(1.05)'" onmouseout="this.style.transform='scale(1)'"/> </div>
<br><br>
🖼️ Print Images:
<div style="display: flex; gap: 15px; flex-wrap: wrap; justify-content: center;">
<img src="https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_image_print.gif" width="400" style="border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;" onmouseover="this.style.transform='scale(1.05)'" onmouseout="this.style.transform='scale(1)'"/> </div>
<br><br>
⏳ Print your Process:
<div style="display: flex; gap: 15px; flex-wrap: wrap; justify-content: center;">
<img src="https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_progress_bar_1.gif" style="border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;" onmouseover="this.style.transform='scale(1.05)'" onmouseout="this.style.transform='scale(1)'"/>
<img src="https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_progress_bar_2.gif" style="border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;" onmouseover="this.style.transform='scale(1.05)'" onmouseout="this.style.transform='scale(1)'"/>
<img src="https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_progress_bar_3.gif" style="border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;" onmouseover="this.style.transform='scale(1.05)'" onmouseout="this.style.transform='scale(1)'"/> </div>
<br><br>
**Detailed Features of this Console IO Helper**
<h1 style="float:right">🧐</h1>
- [Constants](#constants)
- [Functions](#functions)
- [awesome_print](#awesome_print)
- [add_special_effect](#add_special_effect)
- [img_to_str](#img_to_str)
- [print_progress_bar](#print_progress_bar)
- [clear](#clear)
- [get_input](#get_input)
- [get_char](#get_char)
- [rgb_to_python](#rgb_to_python)
- [play_sound](#play_sound)
- [Functions not for print](#functions-not-for-print)
- [show_images](#show_images)
> There are also some examples on the bottom of the [core file](./prime_printer/cio_helper.py).
> Note: Works with Windows and Linux.
<br><br>
---
### Constants
All constants are available with:
```python
import prime_printer as prime
my_awesome_txt = prime.BOLD + "AWESOME" + prime.END
```
1. **Colors**: These constants represent foreground colors used for text styling in the terminal. (all RGB colors are available with the [rgb_to_python function](#rgb_to_python))
- `PURPLE`, `CYAN`, `DARKCYAN`, `BLUE`, `GREEN`, `YELLOW`, `MAGENTA`, `RED`, `WHITE`, `BLACK`
2. **Background Colors**: These constants represent background colors used for text styling.
- `BACKGROUND_BLACK`, `BACKGROUND_RED`, `BACKGROUND_GREEN`, `BACKGROUND_YELLOW`, `BACKGROUND_BLUE`, `BACKGROUND_MAGENTA`, `BACKGROUND_CYAN`, `BACKGROUND_WHITE`
3. **Styles**: Constants for various text styles.
- `BOLD`, `UNDERLINE`, `REVERSED`, `HEADER`
4. **Cursor Navigation**: These are functions for moving the cursor around the terminal.
- `UP(n)`, `DOWN(n)`, `RIGHT(n)`, `LEFT(n)`, `NEXT_LINE(n)`, `PREV_LINE(n)`, `SET_COLUMN(n)`, `SET_POSITION(n, m)`
5. **Clearing**: Functions to clear the screen or parts of the screen.
- `CLEAR_SCREEN(n)`, `CLEAR_LINE(n)`
6. **Reset**: The constant for resetting any formatting.
- `END`
7. **Sounds**: A list of sounds stored in the specified directory, typically for use during typing or other user interactions.
- `PATH_TO_SOUND`, `SOUNDS`
8. **Emojis**: A set of predefined emoji constants.
- `EMOJI_SMILE`, `EMOJI_HEART`, `EMOJI_THUMBS_UP`, etc.
9. **Helpful Lists**:
- `NUMBERS`: List of digits `"0"` to `"9"`.
- `ALPHABET`: List of lowercase alphabetic characters `"a"` to `"z"`.
- `CHINESE_SIGNS`: List of common Chinese characters.
- `GREEK_ALPHABET`: List of uppercase and lowercase Greek alphabet characters.
- `COMMON_SIGNS`: A list of common punctuation marks and symbols.
10. **Common User Input List**: This is a comprehensive list for user input, combining emojis, numbers, the alphabet, Chinese signs, Greek letters, and common signs.
- `COMMON_USER_INPUT_LIST` includes: emojis, numbers, alphabet, Chinese characters, Greek alphabet, and common symbols like punctuation marks and signs.
<br><br>
---
### Functions
#### awesome_print
`awesome_print(txt:str, *features: tuple, should_cut_str_in_chars: boll = True, should_play_sound: bool = False, should_add_backspace_at_end: bool = True, print_delay: float = None, print_delay_min: float = None, print_delay_max: float = None)`
Print text to the console with optional typing effects, sounds, styling, and custom delays — just like a cinematic terminal scene.
```python
import prime_printer as prime
prime.awesome_print("Loading complete!", prime.BOLD, prime.GREEN, should_play_sound=True, print_delay_min=0.05, print_delay_max=0.1)
```
---\> Parameters <---
| Name | Type | Default | Description |
|-----------------------------|---------|------------|-----------------------------------------------------------------------------|
| `txt` | `str` | *required* | The text to print. |
| `*features` | `str` | `()` | Optional text styling (e.g., `"BOLD"`, `"RED"`, `"ITALIC"`). |
| `should_cut_str_in_chars` | `bool` | `True` | Decides to cut the input text in parts to process, or not. |
| `should_play_sound` | `bool` | `False` | Whether to play a typing sound per character. |
| `should_add_backspace_at_end` | `bool` | `True` | Whether to add a backspace/newline at the end of the printed text. |
| `print_delay` | `float` | `None` | Fixed delay between each character. If `None`, uses random delay range. |
| `print_delay_min` | `float` | `None` | Minimum random delay (used only if `print_delay` is `None`). |
| `print_delay_max` | `float` | `None` | Maximum random delay (used only if `print_delay` is `None`). |
---\> Sounds <---
Typing sounds play only if `should_play_sound=True` and the delay isn't too short (e.g. `> 0.1s`). A final sound plays at the end for fast modes.
<br><br>
---
#### add_special_effect
`add_special_effect(txt: str, *features: str) -> str`
Applies special styling effects (like color or emphasis) to a given string using terminal control codes or tags.
```python
import prime_printer as prime
styled = prime.add_special_effect("Warning!", prime.RED, prime.BOLD)
print(styled)
```
---\> Parameters <---
| Name | Type | Description |
|--------------|----------|----------------------------------------------------------------|
| `txt` | `str` | The original text to which you want to apply styles. |
| `*features` | `str` | One or more style codes (e.g. `"BOLD"`, `"RED"`, `"ITALIC"`). |
---\> Behavior <---
- If a single tuple of styles is passed (e.g. `(prime.BOLD, prime.GREEN)`), it's automatically unpacked.
- Styles are applied in order, wrapping the entire string each time.
- Automatically resets the styling at the end using `END`.
<br><br>
---
#### img_to_str
`img_to_str(img_path: str, width: int = 60, is_256color: bool = False, is_truecolor: bool = True, is_unicode: bool = True) -> str`
Converts an image into a stylized text-based string for beautiful console prints using ANSI color codes and optional Unicode blocks.
```python
import prime_printer as prime
print(prime.img_to_str("./logo.png", width=80, is_256color=True))
```
---\> Parameters <---
| Name | Type | Default | Description |
|----------------|---------|-------------|-------------------------------------------------------------------------|
| `img_path` | `str` | *required* | Path to the image file to load. |
| `width` | `int` | `60` | Target width of the output in characters. |
| `is_256color` | `bool` | `False` | Whether to use 256-color ANSI mode (for better compatibility). |
| `is_truecolor` | `bool` | `True` | Enables truecolor (24-bit) output if the terminal supports it. |
| `is_unicode` | `bool` | `True` | Uses Unicode blocks for improved resolution and clarity. |
---\> Returns <---
- `str`: The converted image as a string that can be directly printed in the terminal.
> You can use [print_image](#print_image) if you want to print your image directly.
<br><br>
---
#### print_image
`print_image(img_path: str, width: int = 60, is_256color: bool = False, is_truecolor: bool = True, is_unicode: bool = True) -> None`
Prints an image directly to the terminal using colored text blocks — a quick and stylish way to preview images in your console.
```python
import prime_printer as prime
prime.print_image("logo.png", width=80)
```
---\> Parameters <---
| Name | Type | Default | Description |
|----------------|---------|-------------|-------------------------------------------------------------------------|
| `img_path` | `str` | *required* | Path to the image file to be rendered. |
| `width` | `int` | `60` | Desired width of the image in character columns. |
| `is_256color` | `bool` | `False` | Enables 256-color ANSI mode (fallback for limited terminals). |
| `is_truecolor` | `bool` | `True` | Enables truecolor (24-bit color) output if supported. |
| `is_unicode` | `bool` | `True` | Enables Unicode rendering for higher pixel fidelity. |
> Internally uses [`img_to_str()`](#img_to_str) to convert and print.
<br><br>
---
#### print_progress_bar
`print_progress_bar(total, progress, should_clear=False, left_bar_char="|", right_bar_char="|", progress_char="#", empty_char=" ", size=100, should_print=True) -> str`
Displays a customizable progress bar in the console, ideal for visual feedback in loops, tasks, or animations.
```python
import prime_printer as prime
for i in range(101):
prime.print_progress_bar(total=100, progress=i)
time.sleep(0.05)
```
---\> Parameters <---
| Name | Type | Default | Description |
|-------------------|-----------------|-------------|--------------------------------------------------------------------------|
| `total` | `int` / `float` | *required* | Total number representing 100% of the progress. |
| `progress` | `int` / `float` | *required* | Current progress value. |
| `should_clear` | `bool` | `False` | Whether to clear the console before printing. |
| `left_bar_char` | `str` | `"|"` | Character used on the left side of the bar. |
| `right_bar_char` | `str` | `"|"` | Character used on the right side of the bar. |
| `progress_char` | `str` | `"#"` | Character representing the completed progress. |
| `empty_char` | `str` | `" "` | Character representing the remaining portion. |
| `front_message` | `str` | `""` | Message for the progress bar. |
| `back_message` | `str` | `""` | Message behind the progress bar. |
| `size` | `int` | `100` | Total width of the progress bar in characters. |
| `should_print` | `bool` | `True` | If `True`, prints the bar. If `False`, returns the string only. |
---\> Returns <---
- `str`: The generated progress bar string (printed if `should_print=True`).
<br><br>
---
#### clear
`clear() -> None`
Clears the entire console screen and resets the cursor position to the top-left corner. Useful for animations, live updates, or a clean UI.
```python
import prime_printer as prime
prime.clear()
```
---\> Parameters <---
None
---\> Behavior <---
- Uses ANSI escape sequences to clear the screen (`CLEAR_SCREEN(2)`) and reset cursor (`SET_POSITION(0, 0)`).
- Prints the escape string directly to apply the effect.
<br><br>
---
#### get_input
`get_input(message='User: ', end_chars=['\n', '\r'], back_chars=['\u0008', '\b'], should_play_sound=False, *features) -> str`
Custom interactive input function with support for live console feedback, styled text, backspace handling, conditions and optional typing sounds.
```python
import prime_printer as prime
name = prime.get_input("Enter your name: ", should_play_sound=True, RED, BOLD)
```
A bit more advanced are conditions, if the user-input have to pass a given format. Here 2 examples:
```python
import prime_printer as prime
is_int = lambda x: True if all([x in ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] for char in x]) else False
name = prime.get_input("Enter a number: ", condition=is_int)
```
```python
import prime_printer as prime
name = prime.get_input("Do you accept (y/n): ", condition=lambda x: True if x.lower() in ['y', 'n'] else False)
```
---\> Parameters <---
| **Parameter** | **Type** | **Default** | **Description** |
|-----------------------|-----------------|------------------------|---------------------------------------------------------------|
| `message` | `str` | `'User: '` | Prompt message shown to the user. |
| `get_input` | `bool` | `True` | Lower user input during the return. |
| `end_chars` | `List[str]` | `['\n', '\r']` | Characters that indicate input completion. |
| `back_chars` | `List[str]` | `['\u0008', '\b']` | Characters that represent backspace (deletes last input). |
| `should_play_sound` | `bool` | `False` | Whether to play typing sounds during input. |
| `condition` | `Call(x)` | `lambda x: True` | A condition function that the input must pass, else it will ask again. |
| `*features` | `str` (variadic)| _None_ | Optional style features for the input (e.g., `BOLD`, `RED`). |
Let me know if you need further adjustments or more information!
---\> Returns <---
- `str` — The full user input as a string (with carriage returns removed).
---\> Features <---
- Styled real-time typing
- Backspace-aware input
- Optional typewriter-like sound
- Designed for terminal-based UIs or games
- Conditions (like int or y/n)
<br><br>
---
#### get_char
`get_char`
This function allows you to capture a single character of user input from the console, based on the platform.
---\> Parameters <---
- No parameters are required for this function.
---\> Description <---
- On Linux, it uses `termios` and `tty` to configure raw input, reading a single character directly from the console without waiting for the Enter key.
- On Windows, it uses `msvcrt.getch()` to capture the character input.
---\> Returns <---
- A single character (`str`) representing the current key pressed by the user.
<br><br>
---
#### rgb_to_python
`rgb_to_python(r:int, g:int, b:int) -> str`
Converts RGB color values to an ANSI escape sequence for 24-bit colors (truecolor) that can be used to color text in the terminal.
---\> Parameters <---
| Parameter | Type | Description |
|-----------|------|-------------|
| `r` | `int` | The red component of the color (0 to 255). |
| `g` | `int` | The green component of the color (0 to 255). |
| `b` | `int` | The blue component of the color (0 to 255). |
| `background_color` | `int` | Whether to convert to background color or front color. (Defaults to False) |
---\> Returns <---
- **str**: The ANSI escape sequence corresponding to the RGB value, in the format `\033[38;2;r;g;b` for setting the foreground color.
<br><br>
---
#### play_sound
`play_sound(path_to_sound_file)`
This function initializes the pygame mixer, loads a sound file from the specified path, and plays it asynchronously on both Windows and Linux systems.
```python
import prime_printer as prime
path = "sounds/typing_sound.wav"
prime.play_sound(path)
```
In this example, the function will load and play the `typing_sound.wav` file located in the `sounds` directory.
---\> Parameters <---
| **Parameter** | **Type** | **Description** |
|------------------------|-------------|--------------------------------------------|
| `path_to_sound_file` | `str` | The file path to the sound file to be played. It should be a valid path to a `.wav` file. |
<br><br>
---
### Functions not for print
---
#### show_images
`show_images(image_paths, title=None, image_width=5, axis=False, color_space="gray", cmap=None, cols=2, save_to=None, hspace=0.01, wspace=0.01, use_original_sytle=False, invert=False)`
This function visualizes one or multiple images in a flexible grid layout using `matplotlib`. It supports different color spaces, image inversion, custom figure styling, and optional saving of the visualized image.
```python
from image_utils import show_images
paths = ["images/cat.png", "images/dog.png"]
show_images(paths, title="Animals", color_space="RGB", cols=2)
```
In this example, two images will be loaded, converted to RGB color space, and displayed in a 2-column layout with the title "Animals".
---\> Parameters <---
| **Parameter** | **Type** | **Description** |
|--------------------------|-----------------|---------------------------------------------------------------------------------|
| `image_paths` | `List[str]` | List of paths to the images to be visualized. |
| `title` | `str`, optional | Title of the entire image plot. Default is `None`. |
| `image_width` | `int`, optional | Width of each image in inches. Default is `5`. |
| `axis` | `bool`, optional| Whether to display axis ticks and labels. Default is `False`. |
| `color_space` | `str`, optional | Colorspace for displaying images: `"RGB"`, `"BGR"`, `"gray"`, or `"HSV"`. Default is `"gray"`. |
| `cmap` | `str`, optional | Matplotlib colormap to use (mostly for grayscale images). Default is `None`. |
| `cols` | `int`, optional | Number of columns in the plot grid. Default is `2`. |
| `save_to` | `str`, optional | File path to save the final visualization as an image. Default is `None`. |
| `hspace` | `float`, optional| Horizontal spacing between images. Default is `0.01`. |
| `wspace` | `float`, optional| Vertical spacing between images. Default is `0.01`. |
| `use_original_sytle` | `bool`, optional| Whether to use the current matplotlib style. Default is `False`. |
| `invert` | `bool`, optional| Whether to invert the images before displaying. Default is `False`. |
---\> Returns <---
| **Return** | **Type** | **Description** |
|------------|------------------|--------------------------------------|
| `images` | `np.ndarray` | Array of the loaded images. |
Raw data
{
"_id": null,
"home_page": "https://github.com/xXAI-botXx/prime_printer",
"name": "prime-printer",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Printing, Helper",
"author": "Tobia Ippolito",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ea/2c/b5db542d001c348fdff7d1979b8a196bb1055e285d7f129f5e7cfcc8388c/prime_printer-0.0.7.tar.gz",
"platform": null,
"description": "# \ud83d\ude0e Prime Printer \ud83d\udc40\r\nConsole I/O Helper - Print Awesome. Make It Prime \ud83d\ude80\r\n\r\n<img src=\"https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/logo.png\"></img>\r\n\r\nEasy Usage, Easy handling, BIG Improvement for your needs \ud83c\udfaf\r\n\r\nEasy Installation -> https://pypi.org/project/prime-printer/\r\n```bash \r\npip install prime_printer\r\n```\r\n\r\n<br>\r\n\r\n**\u26a1Quick Look\u26a1**\r\n\r\n\ud83d\udda8\ufe0f Printing with Delay, Type-Sound, Control, Conditions and Stylings:\r\n\r\n<div style=\"display: flex; gap: 15px; flex-wrap: wrap; justify-content: center;\"> \r\n<img src=\"https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_colored_delay_sound_print.gif\" style=\"border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;\" onmouseover=\"this.style.transform='scale(1.05)'\" onmouseout=\"this.style.transform='scale(1)'\"/> \r\n<img src=\"https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_game_menu.gif\" style=\"border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;\" onmouseover=\"this.style.transform='scale(1.05)'\" onmouseout=\"this.style.transform='scale(1)'\"/> \r\n<img src=\"https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_input_with_condition.gif\" style=\"border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;\" onmouseover=\"this.style.transform='scale(1.05)'\" onmouseout=\"this.style.transform='scale(1)'\"/> </div>\r\n\r\n<br><br>\r\n\r\n\ud83d\uddbc\ufe0f Print Images:\r\n\r\n<div style=\"display: flex; gap: 15px; flex-wrap: wrap; justify-content: center;\"> \r\n<img src=\"https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_image_print.gif\" width=\"400\" style=\"border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;\" onmouseover=\"this.style.transform='scale(1.05)'\" onmouseout=\"this.style.transform='scale(1)'\"/> </div>\r\n\r\n<br><br>\r\n\r\n\u23f3 Print your Process:\r\n\r\n<div style=\"display: flex; gap: 15px; flex-wrap: wrap; justify-content: center;\"> \r\n<img src=\"https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_progress_bar_1.gif\" style=\"border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;\" onmouseover=\"this.style.transform='scale(1.05)'\" onmouseout=\"this.style.transform='scale(1)'\"/> \r\n<img src=\"https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_progress_bar_2.gif\" style=\"border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;\" onmouseover=\"this.style.transform='scale(1.05)'\" onmouseout=\"this.style.transform='scale(1)'\"/> \r\n<img src=\"https://raw.githubusercontent.com/xXAI-botXx/prime_printer/v_01/res/example_progress_bar_3.gif\" style=\"border-radius: 10px; box-shadow: 0 4px 8px rgba(0,0,0,0.2); transition: transform 0.3s;\" onmouseover=\"this.style.transform='scale(1.05)'\" onmouseout=\"this.style.transform='scale(1)'\"/> </div>\r\n\r\n<br><br>\r\n\r\n**Detailed Features of this Console IO Helper** \r\n<h1 style=\"float:right\">\ud83e\uddd0</h1>\r\n\r\n- [Constants](#constants)\r\n- [Functions](#functions)\r\n - [awesome_print](#awesome_print)\r\n - [add_special_effect](#add_special_effect)\r\n - [img_to_str](#img_to_str)\r\n - [print_progress_bar](#print_progress_bar)\r\n - [clear](#clear)\r\n - [get_input](#get_input)\r\n - [get_char](#get_char)\r\n - [rgb_to_python](#rgb_to_python)\r\n - [play_sound](#play_sound)\r\n- [Functions not for print](#functions-not-for-print)\r\n - [show_images](#show_images)\r\n\r\n\r\n> There are also some examples on the bottom of the [core file](./prime_printer/cio_helper.py).\r\n\r\n> Note: Works with Windows and Linux.\r\n\r\n\r\n\r\n<br><br>\r\n\r\n\r\n---\r\n### Constants\r\n\r\nAll constants are available with:\r\n```python\r\nimport prime_printer as prime\r\n\r\nmy_awesome_txt = prime.BOLD + \"AWESOME\" + prime.END\r\n```\r\n\r\n1. **Colors**: These constants represent foreground colors used for text styling in the terminal. (all RGB colors are available with the [rgb_to_python function](#rgb_to_python))\r\n - `PURPLE`, `CYAN`, `DARKCYAN`, `BLUE`, `GREEN`, `YELLOW`, `MAGENTA`, `RED`, `WHITE`, `BLACK`\r\n\r\n2. **Background Colors**: These constants represent background colors used for text styling.\r\n - `BACKGROUND_BLACK`, `BACKGROUND_RED`, `BACKGROUND_GREEN`, `BACKGROUND_YELLOW`, `BACKGROUND_BLUE`, `BACKGROUND_MAGENTA`, `BACKGROUND_CYAN`, `BACKGROUND_WHITE`\r\n\r\n3. **Styles**: Constants for various text styles.\r\n - `BOLD`, `UNDERLINE`, `REVERSED`, `HEADER`\r\n\r\n4. **Cursor Navigation**: These are functions for moving the cursor around the terminal.\r\n - `UP(n)`, `DOWN(n)`, `RIGHT(n)`, `LEFT(n)`, `NEXT_LINE(n)`, `PREV_LINE(n)`, `SET_COLUMN(n)`, `SET_POSITION(n, m)`\r\n\r\n5. **Clearing**: Functions to clear the screen or parts of the screen.\r\n - `CLEAR_SCREEN(n)`, `CLEAR_LINE(n)`\r\n\r\n6. **Reset**: The constant for resetting any formatting.\r\n - `END`\r\n\r\n7. **Sounds**: A list of sounds stored in the specified directory, typically for use during typing or other user interactions.\r\n - `PATH_TO_SOUND`, `SOUNDS`\r\n\r\n8. **Emojis**: A set of predefined emoji constants.\r\n - `EMOJI_SMILE`, `EMOJI_HEART`, `EMOJI_THUMBS_UP`, etc.\r\n\r\n9. **Helpful Lists**:\r\n - `NUMBERS`: List of digits `\"0\"` to `\"9\"`.\r\n - `ALPHABET`: List of lowercase alphabetic characters `\"a\"` to `\"z\"`.\r\n - `CHINESE_SIGNS`: List of common Chinese characters.\r\n - `GREEK_ALPHABET`: List of uppercase and lowercase Greek alphabet characters.\r\n - `COMMON_SIGNS`: A list of common punctuation marks and symbols.\r\n\r\n10. **Common User Input List**: This is a comprehensive list for user input, combining emojis, numbers, the alphabet, Chinese signs, Greek letters, and common signs.\r\n - `COMMON_USER_INPUT_LIST` includes: emojis, numbers, alphabet, Chinese characters, Greek alphabet, and common symbols like punctuation marks and signs.\r\n\r\n\r\n\r\n<br><br>\r\n\r\n\r\n---\r\n### Functions\r\n\r\n\r\n\r\n\r\n#### awesome_print\r\n\r\n`awesome_print(txt:str, *features: tuple, should_cut_str_in_chars: boll = True, should_play_sound: bool = False, should_add_backspace_at_end: bool = True, print_delay: float = None, print_delay_min: float = None, print_delay_max: float = None)`\r\n\r\nPrint text to the console with optional typing effects, sounds, styling, and custom delays \u2014 just like a cinematic terminal scene.\r\n\r\n```python\r\nimport prime_printer as prime\r\n\r\nprime.awesome_print(\"Loading complete!\", prime.BOLD, prime.GREEN, should_play_sound=True, print_delay_min=0.05, print_delay_max=0.1)\r\n```\r\n\r\n---\\> Parameters <---\r\n\r\n| Name | Type | Default | Description |\r\n|-----------------------------|---------|------------|-----------------------------------------------------------------------------|\r\n| `txt` | `str` | *required* | The text to print. |\r\n| `*features` | `str` | `()` | Optional text styling (e.g., `\"BOLD\"`, `\"RED\"`, `\"ITALIC\"`). |\r\n| `should_cut_str_in_chars` | `bool` | `True` | Decides to cut the input text in parts to process, or not. |\r\n| `should_play_sound` | `bool` | `False` | Whether to play a typing sound per character. |\r\n| `should_add_backspace_at_end` | `bool` | `True` | Whether to add a backspace/newline at the end of the printed text. |\r\n| `print_delay` | `float` | `None` | Fixed delay between each character. If `None`, uses random delay range. |\r\n| `print_delay_min` | `float` | `None` | Minimum random delay (used only if `print_delay` is `None`). |\r\n| `print_delay_max` | `float` | `None` | Maximum random delay (used only if `print_delay` is `None`). |\r\n\r\n\r\n\r\n---\\> Sounds <---\r\n\r\nTyping sounds play only if `should_play_sound=True` and the delay isn't too short (e.g. `> 0.1s`). A final sound plays at the end for fast modes.\r\n\r\n\r\n<br><br>\r\n\r\n\r\n---\r\n#### add_special_effect\r\n\r\n`add_special_effect(txt: str, *features: str) -> str`\r\n\r\nApplies special styling effects (like color or emphasis) to a given string using terminal control codes or tags.\r\n\r\n```python\r\nimport prime_printer as prime\r\n\r\nstyled = prime.add_special_effect(\"Warning!\", prime.RED, prime.BOLD)\r\nprint(styled)\r\n```\r\n\r\n---\\> Parameters <---\r\n\r\n| Name | Type | Description |\r\n|--------------|----------|----------------------------------------------------------------|\r\n| `txt` | `str` | The original text to which you want to apply styles. |\r\n| `*features` | `str` | One or more style codes (e.g. `\"BOLD\"`, `\"RED\"`, `\"ITALIC\"`). |\r\n\r\n\r\n\r\n---\\> Behavior <---\r\n\r\n- If a single tuple of styles is passed (e.g. `(prime.BOLD, prime.GREEN)`), it's automatically unpacked.\r\n- Styles are applied in order, wrapping the entire string each time.\r\n- Automatically resets the styling at the end using `END`.\r\n\r\n\r\n\r\n<br><br>\r\n\r\n\r\n---\r\n#### img_to_str \r\n\r\n`img_to_str(img_path: str, width: int = 60, is_256color: bool = False, is_truecolor: bool = True, is_unicode: bool = True) -> str`\r\n\r\nConverts an image into a stylized text-based string for beautiful console prints using ANSI color codes and optional Unicode blocks.\r\n\r\n```python\r\nimport prime_printer as prime\r\n\r\nprint(prime.img_to_str(\"./logo.png\", width=80, is_256color=True))\r\n```\r\n\r\n---\\> Parameters <---\r\n\r\n| Name | Type | Default | Description |\r\n|----------------|---------|-------------|-------------------------------------------------------------------------|\r\n| `img_path` | `str` | *required* | Path to the image file to load. |\r\n| `width` | `int` | `60` | Target width of the output in characters. |\r\n| `is_256color` | `bool` | `False` | Whether to use 256-color ANSI mode (for better compatibility). |\r\n| `is_truecolor` | `bool` | `True` | Enables truecolor (24-bit) output if the terminal supports it. |\r\n| `is_unicode` | `bool` | `True` | Uses Unicode blocks for improved resolution and clarity. |\r\n\r\n\r\n---\\> Returns <---\r\n\r\n- `str`: The converted image as a string that can be directly printed in the terminal.\r\n\r\n> You can use [print_image](#print_image) if you want to print your image directly.\r\n\r\n\r\n\r\n<br><br>\r\n\r\n\r\n---\r\n#### print_image \r\n\r\n`print_image(img_path: str, width: int = 60, is_256color: bool = False, is_truecolor: bool = True, is_unicode: bool = True) -> None`\r\n\r\nPrints an image directly to the terminal using colored text blocks \u2014 a quick and stylish way to preview images in your console.\r\n\r\n```python\r\nimport prime_printer as prime\r\n\r\nprime.print_image(\"logo.png\", width=80)\r\n```\r\n\r\n---\\> Parameters <---\r\n\r\n| Name | Type | Default | Description |\r\n|----------------|---------|-------------|-------------------------------------------------------------------------|\r\n| `img_path` | `str` | *required* | Path to the image file to be rendered. |\r\n| `width` | `int` | `60` | Desired width of the image in character columns. |\r\n| `is_256color` | `bool` | `False` | Enables 256-color ANSI mode (fallback for limited terminals). |\r\n| `is_truecolor` | `bool` | `True` | Enables truecolor (24-bit color) output if supported. |\r\n| `is_unicode` | `bool` | `True` | Enables Unicode rendering for higher pixel fidelity. |\r\n\r\n\r\n\r\n> Internally uses [`img_to_str()`](#img_to_str) to convert and print.\r\n\r\n\r\n\r\n\r\n<br><br>\r\n\r\n\r\n---\r\n#### print_progress_bar\r\n \r\n`print_progress_bar(total, progress, should_clear=False, left_bar_char=\"|\", right_bar_char=\"|\", progress_char=\"#\", empty_char=\" \", size=100, should_print=True) -> str`\r\n\r\nDisplays a customizable progress bar in the console, ideal for visual feedback in loops, tasks, or animations.\r\n\r\n```python\r\nimport prime_printer as prime\r\n\r\nfor i in range(101):\r\n prime.print_progress_bar(total=100, progress=i)\r\n time.sleep(0.05)\r\n```\r\n\r\n---\\> Parameters <---\r\n\r\n| Name | Type | Default | Description |\r\n|-------------------|-----------------|-------------|--------------------------------------------------------------------------|\r\n| `total` | `int` / `float` | *required* | Total number representing 100% of the progress. |\r\n| `progress` | `int` / `float` | *required* | Current progress value. |\r\n| `should_clear` | `bool` | `False` | Whether to clear the console before printing. |\r\n| `left_bar_char` | `str` | `\"|\"` | Character used on the left side of the bar. |\r\n| `right_bar_char` | `str` | `\"|\"` | Character used on the right side of the bar. |\r\n| `progress_char` | `str` | `\"#\"` | Character representing the completed progress. |\r\n| `empty_char` | `str` | `\" \"` | Character representing the remaining portion. |\r\n| `front_message` | `str` | `\"\"` | Message for the progress bar. |\r\n| `back_message` | `str` | `\"\"` | Message behind the progress bar. |\r\n| `size` | `int` | `100` | Total width of the progress bar in characters. |\r\n| `should_print` | `bool` | `True` | If `True`, prints the bar. If `False`, returns the string only. |\r\n\r\n---\\> Returns <---\r\n- `str`: The generated progress bar string (printed if `should_print=True`).\r\n\r\n\r\n\r\n<br><br>\r\n\r\n\r\n---\r\n#### clear\r\n \r\n`clear() -> None`\r\n\r\nClears the entire console screen and resets the cursor position to the top-left corner. Useful for animations, live updates, or a clean UI.\r\n\r\n```python\r\nimport prime_printer as prime\r\n\r\nprime.clear()\r\n```\r\n\r\n\r\n---\\> Parameters <---\r\n\r\nNone\r\n\r\n\r\n---\\> Behavior <---\r\n\r\n- Uses ANSI escape sequences to clear the screen (`CLEAR_SCREEN(2)`) and reset cursor (`SET_POSITION(0, 0)`).\r\n- Prints the escape string directly to apply the effect.\r\n\r\n\r\n\r\n<br><br>\r\n\r\n\r\n---\r\n#### get_input\r\n\r\n`get_input(message='User: ', end_chars=['\\n', '\\r'], back_chars=['\\u0008', '\\b'], should_play_sound=False, *features) -> str`\r\n\r\nCustom interactive input function with support for live console feedback, styled text, backspace handling, conditions and optional typing sounds.\r\n\r\n```python\r\nimport prime_printer as prime\r\n\r\nname = prime.get_input(\"Enter your name: \", should_play_sound=True, RED, BOLD)\r\n```\r\n\r\nA bit more advanced are conditions, if the user-input have to pass a given format. Here 2 examples:\r\n```python\r\nimport prime_printer as prime\r\n\r\nis_int = lambda x: True if all([x in ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'] for char in x]) else False\r\nname = prime.get_input(\"Enter a number: \", condition=is_int)\r\n```\r\n\r\n```python\r\nimport prime_printer as prime\r\n\r\nname = prime.get_input(\"Do you accept (y/n): \", condition=lambda x: True if x.lower() in ['y', 'n'] else False)\r\n```\r\n\r\n\r\n---\\> Parameters <---\r\n\r\n| **Parameter** | **Type** | **Default** | **Description** |\r\n|-----------------------|-----------------|------------------------|---------------------------------------------------------------|\r\n| `message` | `str` | `'User: '` | Prompt message shown to the user. |\r\n| `get_input` | `bool` | `True` | Lower user input during the return. |\r\n| `end_chars` | `List[str]` | `['\\n', '\\r']` | Characters that indicate input completion. |\r\n| `back_chars` | `List[str]` | `['\\u0008', '\\b']` | Characters that represent backspace (deletes last input). |\r\n| `should_play_sound` | `bool` | `False` | Whether to play typing sounds during input. |\r\n| `condition` | `Call(x)` | `lambda x: True` | A condition function that the input must pass, else it will ask again. |\r\n| `*features` | `str` (variadic)| _None_ | Optional style features for the input (e.g., `BOLD`, `RED`). |\r\n\r\nLet me know if you need further adjustments or more information!\r\n\r\n\r\n\r\n---\\> Returns <---\r\n\r\n- `str` \u2014 The full user input as a string (with carriage returns removed).\r\n\r\n\r\n---\\> Features <---\r\n\r\n- Styled real-time typing\r\n- Backspace-aware input\r\n- Optional typewriter-like sound\r\n- Designed for terminal-based UIs or games\r\n- Conditions (like int or y/n)\r\n\r\n\r\n\r\n\r\n<br><br>\r\n\r\n\r\n---\r\n#### get_char\r\n\r\n`get_char`\r\n\r\nThis function allows you to capture a single character of user input from the console, based on the platform.\r\n\r\n---\\> Parameters <---\r\n- No parameters are required for this function.\r\n\r\n---\\> Description <---\r\n- On Linux, it uses `termios` and `tty` to configure raw input, reading a single character directly from the console without waiting for the Enter key.\r\n- On Windows, it uses `msvcrt.getch()` to capture the character input.\r\n\r\n---\\> Returns <---\r\n- A single character (`str`) representing the current key pressed by the user.\r\n\r\n\r\n\r\n\r\n\r\n<br><br>\r\n\r\n\r\n---\r\n#### rgb_to_python\r\n\r\n`rgb_to_python(r:int, g:int, b:int) -> str`\r\n\r\nConverts RGB color values to an ANSI escape sequence for 24-bit colors (truecolor) that can be used to color text in the terminal.\r\n\r\n\r\n---\\> Parameters <---\r\n\r\n| Parameter | Type | Description |\r\n|-----------|------|-------------|\r\n| `r` | `int` | The red component of the color (0 to 255). |\r\n| `g` | `int` | The green component of the color (0 to 255). |\r\n| `b` | `int` | The blue component of the color (0 to 255). |\r\n| `background_color` | `int` | Whether to convert to background color or front color. (Defaults to False) |\r\n\r\n\r\n---\\> Returns <---\r\n\r\n- **str**: The ANSI escape sequence corresponding to the RGB value, in the format `\\033[38;2;r;g;b` for setting the foreground color.\r\n\r\n\r\n\r\n\r\n\r\n<br><br>\r\n\r\n\r\n---\r\n#### play_sound\r\n\r\n`play_sound(path_to_sound_file)`\r\n\r\nThis function initializes the pygame mixer, loads a sound file from the specified path, and plays it asynchronously on both Windows and Linux systems.\r\n\r\n```python\r\nimport prime_printer as prime\r\n\r\npath = \"sounds/typing_sound.wav\"\r\nprime.play_sound(path)\r\n```\r\n\r\nIn this example, the function will load and play the `typing_sound.wav` file located in the `sounds` directory.\r\n\r\n---\\> Parameters <---\r\n\r\n| **Parameter** | **Type** | **Description** |\r\n|------------------------|-------------|--------------------------------------------|\r\n| `path_to_sound_file` | `str` | The file path to the sound file to be played. It should be a valid path to a `.wav` file. |\r\n\r\n\r\n\r\n\r\n\r\n<br><br>\r\n\r\n---\r\n### Functions not for print\r\n\r\n\r\n---\r\n#### show_images\r\n\r\n`show_images(image_paths, title=None, image_width=5, axis=False, color_space=\"gray\", cmap=None, cols=2, save_to=None, hspace=0.01, wspace=0.01, use_original_sytle=False, invert=False)`\r\n\r\nThis function visualizes one or multiple images in a flexible grid layout using `matplotlib`. It supports different color spaces, image inversion, custom figure styling, and optional saving of the visualized image.\r\n\r\n```python\r\nfrom image_utils import show_images\r\n\r\npaths = [\"images/cat.png\", \"images/dog.png\"]\r\nshow_images(paths, title=\"Animals\", color_space=\"RGB\", cols=2)\r\n```\r\n\r\nIn this example, two images will be loaded, converted to RGB color space, and displayed in a 2-column layout with the title \"Animals\".\r\n\r\n\r\n\r\n---\\> Parameters <---\r\n\r\n| **Parameter** | **Type** | **Description** |\r\n|--------------------------|-----------------|---------------------------------------------------------------------------------|\r\n| `image_paths` | `List[str]` | List of paths to the images to be visualized. |\r\n| `title` | `str`, optional | Title of the entire image plot. Default is `None`. |\r\n| `image_width` | `int`, optional | Width of each image in inches. Default is `5`. |\r\n| `axis` | `bool`, optional| Whether to display axis ticks and labels. Default is `False`. |\r\n| `color_space` | `str`, optional | Colorspace for displaying images: `\"RGB\"`, `\"BGR\"`, `\"gray\"`, or `\"HSV\"`. Default is `\"gray\"`. |\r\n| `cmap` | `str`, optional | Matplotlib colormap to use (mostly for grayscale images). Default is `None`. |\r\n| `cols` | `int`, optional | Number of columns in the plot grid. Default is `2`. |\r\n| `save_to` | `str`, optional | File path to save the final visualization as an image. Default is `None`. |\r\n| `hspace` | `float`, optional| Horizontal spacing between images. Default is `0.01`. |\r\n| `wspace` | `float`, optional| Vertical spacing between images. Default is `0.01`. |\r\n| `use_original_sytle` | `bool`, optional| Whether to use the current matplotlib style. Default is `False`. |\r\n| `invert` | `bool`, optional| Whether to invert the images before displaying. Default is `False`. |\r\n\r\n\r\n\r\n---\\> Returns <---\r\n\r\n| **Return** | **Type** | **Description** |\r\n|------------|------------------|--------------------------------------|\r\n| `images` | `np.ndarray` | Array of the loaded images. |\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Console I/O Helper - Print Awesome. Make It Prime.",
"version": "0.0.7",
"project_urls": {
"Download": "https://github.com/xXAI-botXx/prime_printer/archive/refs/tags/v_03.zip",
"Homepage": "https://github.com/xXAI-botXx/prime_printer"
},
"split_keywords": [
"printing",
" helper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ea2cb5db542d001c348fdff7d1979b8a196bb1055e285d7f129f5e7cfcc8388c",
"md5": "7b2113bbadeb142293507afdec9a6ccf",
"sha256": "5e3d4a09a30dfb6e96fbf4130b9c3eaa7e906e654c6e1aaaf5aa7d3f777b6adb"
},
"downloads": -1,
"filename": "prime_printer-0.0.7.tar.gz",
"has_sig": false,
"md5_digest": "7b2113bbadeb142293507afdec9a6ccf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 2567305,
"upload_time": "2025-04-09T14:46:14",
"upload_time_iso_8601": "2025-04-09T14:46:14.095388Z",
"url": "https://files.pythonhosted.org/packages/ea/2c/b5db542d001c348fdff7d1979b8a196bb1055e285d7f129f5e7cfcc8388c/prime_printer-0.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-09 14:46:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xXAI-botXx",
"github_project": "prime_printer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "climage",
"specs": []
},
{
"name": "pygame",
"specs": []
}
],
"lcname": "prime-printer"
}
JSON
