Metadata-Version: 2.4
Name: epitech_console
Version: 0.1.7.2
Summary: Console tools (animation / colored printing / formating / etc...)
Author-email: Nathan Jarjarbin <nathan.amaraggi@epitech.eu>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/Jarjarbin06/epitech_console
Project-URL: Repository, https://github.com/Jarjarbin06/epitech_console/tree/v0.1.3
Project-URL: Issues, https://github.com/Jarjarbin06/epitech_console/issues
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

## Epitech Student's project

<img src="https://github.com/Jarjarbin06/epitech_console/blob/main/src/epitech_logo.png?raw=true" alt="Epitech logo" width="49%" style="display:inline-block; margin-right:1%;">
<img src="https://github.com/Jarjarbin06/epitech_console/blob/main/src/epitech_console_logo.png?raw=true" alt="Epitech Console logo" width="49%" style="display:inline-block;">

# epitech_console v0.1.7.2

[![PyTest Main](https://github.com/Jarjarbin06/epitech_console/actions/workflows/test-package.yml/badge.svg?branch=main)](https://github.com/Jarjarbin06/epitech_console/actions/workflows/test-package.yml)
[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Stars](https://img.shields.io/github/stars/Jarjarbin06/epitech_console?style=social)](https://github.com/Jarjarbin06/epitech_console)

## Description

The `epitech_console` is a friendly Python tool that helps you create cool stuff in your terminal! It's like giving your command-line interface a makeover with fun animations, colorful text, and neat formatting. If you want to make your terminal programs look more interesting and organized, this library is for you!

## Table of Contents

1.  [Description](#Description)
2.  [Features](#Features)
3.  [Tech Stack](#Tech-Stack)
4.  [Installation](#Installation)
5.  [Usage](#Usage)
6.  [Project Structure](#Project-Structure)
7.  [API Reference](#API-Reference)
8.  [Release Note](#Release-Note)
9.  [License](#License)
10. [Important Links](#Important-Links)
11. [Footer](#Footer)

## Features

*   **Cool Text Effects**: Easily add colors, bold text, italics, underlines, and even strikethrough to your terminal text.
*   **Animations**: Make your terminal come alive with simple animations. Great for loading screens or just adding some visual flair!
*   **Progress Bars**: Show the progress of long tasks with customizable progress bars.  Keep your users informed in a visually appealing way.
*   **Timers**: Use the built-in stopwatch to measure how long parts of your code take to run.
*   **Configuration**: Easily manage settings for your application.
*   **Error Handling**:  Clear and helpful error messages to make debugging easier.
*   **Cursor Control**:  Move the cursor around, hide it, or show it as needed.
*   **Line Control**:  Quickly clear lines or the entire screen.

*   **ANSI Escape Sequence Handling**: Provides classes for generating ANSI escape sequences to control text color, formatting, and cursor movement.
*   **Text Formatting**: Includes tools for applying styles like bold, italic, underline, and strikethrough to text.
*   **Animation**: Supports creating and displaying animations in the console.
*   **Progress Bars**: Offers progress bar functionality to visualize task completion.
*   **Stopwatch**: Includes a stopwatch class for measuring elapsed time.
*   **Configuration Management**: Provides a configuration system to handle settings and preferences.
*   **Error Handling**: Custom error class for more informative error messages.
*   **Cursor Manipulation**: Ability to move, show and hide the cursor.
*   **Line Manipulation**: Clear lines, clear screen functionality.

## Tech-Stack

*   **Language**: Python - Because who doesn't love Python?
*   **Frameworks**: Python -  It's all Python, all the way!

## Installation

Ready to get started? Here's how to install `epitech_console`:

1.  **First Things First**: Make sure you have Python 3.8 or newer installed on your computer. You can check your Python version by opening a terminal and typing `python --version`.

2.  **Install with `pip` (Easy Method)**:

    Open your terminal and run this command:

    ```bash
    pip install epitech_console
    ```

    This will automatically download and install the library from PyPI.

    **Alternative: Install from GitHub**:

    If you want the latest version directly from the source, you can install it using `git`:

    ```bash
    git clone https://github.com/Jarjarbin06/epitech_console.git
    cd epitech_console
    ./script/install-package
    ```

    This downloads the code, then the `install-package` script handles the installation.

    These commands install the `epitech_console` package and its dependencies (None currently).

## Usage

Here are some simple examples to get you started with `epitech_console`:

### Basic Text Formatting

```python
from epitech_console import Text, ANSI

epitech_color = ANSI.Color.epitech_fg() + ANSI.Color.rgb_bg(0, 0 ,0)
reset = ANSI.Color.color(ANSI.Color.C_RESET)
my_text = epitech_color + Text.Text("hi").bold() + reset

print(my_text)
```

### Creating an Animation

```python
from epitech_console import Animation, System

my_animation = Animation.Animation(Animation.BasePack.P_FILL_R)
for i in range(5):
    System.Console.print(my_animation.render(delete=True), sleep=0.5)
    my_animation.update()
```

### Creating a custom Animation

```python
from epitech_console import Animation, System

my_animation = Animation.Animation(['Frame 1', 'Frame 2', 'Frame 3'])
for i in range(5):
    System.Console.print(my_animation.render(delete=True), sleep=0.5)
    my_animation.update()
```

### Using Progress Bar

```python
from epitech_console.Animation import ProgressBar, Spinner
from epitech_console import System

my_spinner = Spinner.stick()
my_progress_bar = ProgressBar(length=20, percent_style="mix", spinner=my_spinner)
for i in range(101):
    my_progress_bar.update(percent=i, update_spinner=(i % 5 == 0))
    System.Console.print(my_progress_bar.render(delete=True), sleep=0.05)
```

### Utilizing the Stopwatch

```python
from epitech_console import System

my_stopwatch = System.StopWatch(start=True)
System.Time.sleep(2)
my_stopwatch.stop()
print(f"Elapsed time: {my_stopwatch.elapsed()}")
```

### Create a config.ini file

```python
from epitech_console.System import Config

my_path = "."
if not Config.exist(my_path):
    Config.create(my_path, {
      "GENERALE" : {"theme": "dark", "language": "en"},
      "USER" : {"username": "guest", "email": "my_email@email.com"}
    })
```

This will check and create a `config.ini` file if it doesn't exist.

## Project-Structure

```
REPO/
├── epitech_console/
│   ├── Animation/
│   │   ├── __init__.py
│   │   ├── animation.py
│   │   ├── basepack.py
│   │   ├── progressbar.py
│   │   ├── spinner.py
│   │   └── style.py
│   ├── ANSI/
│   │   ├── __init__.py
│   │   ├── ansi.py
│   │   ├── basepack.py
│   │   ├── color.py
│   │   ├── cursor.py
│   │   └── line.py
│   ├── Error/
│   │   ├── __init__.py
│   │   └── error.py
│   ├── System/
│   │   ├── __init__.py
│   │   ├── config.py
│   │   ├── console.py
│   │   ├── stopwatch.py
│   │   └── time.py
│   ├── Text/
│   │   ├── __init__.py
│   │   ├── format.py
│   │   └── text.py
│   ├── __init__.py
│   └── config.ini
├── script/
│   ├── auto-reload
│   ├── check-package
│   ├── install-package
│   └── uninstall-package
├── .gitignore
├── LICENSE
├── MANIFEST.in
├── pyproject.toml
└── README.md
```

## API-Reference

### Animation Module

*   **Animation**: Class for creating animations.
    *   `Animation(animation: list[str] | str = "")`: Constructor to create an animation.
    *   `update(auto_reset: bool = True)`: Advances the animation by one step.
    *   `render(delete: bool = False)`: Renders the current frame of the animation.

*   **BasePack**: Ready-to-use animations.
	* `def update(style: Style = Style("#", "-", "<", ">", "|", "|"))`: Update the BasePack animations to fit with the given Style (or the default one if no Style given)

*   **ProgressBar**: Class for creating progress bars.
    *   `ProgressBar(length: int, animation: Animation | None = None, style: object = Style("#", "-", "<", ">", "|", "|"), percent_style: str = "bar", spinner: Animation | None = None, spinner_position: str = "a")`: Constructor to create a progress bar.
    *   `update(percent: int = 0, update_spinner: bool = True, auto_reset: bool = True)`: Updates the progress bar to a specified percentage.
    *   `render(color: object | tuple[object, object, object] = Color.color(Color.C_RESET), hide_spinner_at_end: bool = True, delete: bool = False)`: Renders the progress bar.

*   **Spinner**: Class with pre-built spinner animations.
    *   `stick(style: object = Style("#", " ", "#", "#", "", ""))`: Creates a stick spinner.
    *   `plus(style: object = Style("#", " ", "#", "#", "", ""))`: Creates a plus spinner.
    *   `cross(style: object = Style("#", " ", "#", "#", "", ""))`: Creates a cross spinner.

*   **Style**: Class for styling progress bars.
    *   `Style(on: str = "#", off: str = "-", arrow_left: str = "<", arrow_right: str = ">", border_left: str = "|", border_right: str = "|")`: Constructor to create a style.

### ANSI Module

*   **ANSI**: Class for creating ANSI escape sequences.
    *   `ANSI(sequence: str = "")`: Constructor to create an ANSI sequence.
    *   `ESC`: ANSI escape character.

*   **BasePack**: Ready-to-use ANSI escape sequences.
	* `def update()`: Update the BasePack escape sequences(no Style created yet)

*   **Color**: Class for ANSI color codes.
    *   `color_fg`: Returns ANSI sequence for a foreground color.
    * `color_bg`: Returns ANSI sequence for a foreground color.
    *   `rgb_fg(r: int, g: int, b: int)`: Returns ANSI sequence for a foreground RGB color.
    *   `rgb_bg(r: int, g: int, b: int)`: Returns ANSI sequence for a background RGB color.
    *   `epitech_fg(r: int, g: int, b: int)`: Returns ANSI sequence for a foreground colored as Epitech (light).
    *   `epitech_bg(r: int, g: int, b: int)`: Returns ANSI sequence for a background colored as Epitech (light).
    *   `epitech_dark_fg(r: int, g: int, b: int)`: Returns ANSI sequence for a foreground colored as Epitech (dark).
    *   `epitech_dark_bg(r: int, g: int, b: int)`: Returns ANSI sequence for a background colored as Epitech (dark).

*   **Cursor**: Class for cursor manipulation.
    *   `up(n: int = 1)`: Moves the cursor up `n` lines.
    *   `down(n: int = 1)`: Moves the cursor down `n` lines.
    *   `left(n: int = 1)`: Moves the cursor left `n` columns.
    *   `right(n: int = 1)`: Moves the cursor right `n` columns.
    *   `top()`: Moves the cursor to the top left corner.
    *   `previous(n: int = 1)`: Moves the cursor to the beginning of `n` lines before.
    *   `next(n: int = 1)`: Moves the cursor to the beginning of `n` lines after.
    *   `move(x: int = 0, y: int = 0)`: Moves the cursor at position (x, y).
    *   `move_column(n: int = 1)`: Moves the cursor at position y on the same line.
    *   `set()`: Save the position of the cursor.
    *   `reset()`: Load the saved position of the cursor.
    *   `hide()`: Hides the cursor.
    *   `show()`: Shows the cursor.

*   **Line**: Class for line manipulation.
    *   `clear_line()`: Clears the current line.
    *   `clear_start_line()`: Clears the current line from the beginning to the cursor.
    *   `clear_end_line()`: Clears the current line from the cursor to the end.
    *   `clear_screen()`: Clears the entire screen.
    *   `clear()`: Clears the entire screen and bring the cursor to the top left corner.
    *   `clear_previous_line()`: Clears the previous line and bring the cursor to the beginning of the previous line.

### Error Module

*   **Error**: Class for custom error handling.
    *   `Error(message: str = "an error occurred", error: str = "Error", link: tuple[str, int] | None = None)`: Constructor to create an error object.

### System Module

*   **Action**: Class for action saving.
    *   `Action(name: str, function: Callable, *args, **kwargs`: Constructor to create an Action object.

*   **Actions**: Class for actions list saving.
    *   `Actions(actions: list[Action] | Action)`: Constructor to create a Actions object.

*   **Config**: Class for configuration management.
    *   `exist(path: str, file_name: str = "config.ini")`: Checks if a config file exist or is empty.
    *   `create(path: str, data: dict | None = None, file_name: str = "config.ini")`: Creates a new config file.
    *   `read(path: str, file_name: str = "config.ini")`: Read a config file.

*   **Console**: Class for console output.
    *   `print(value: any = "", start: str = "", end: str = "\n", file: any = stdout, sleep: int | float | None = None)`: Prints to the console with optional start, end, file, and sleep parameters.

* **StopWatch**: Class for measuring elapsed time.
    *   `StopWatch(start: bool = False)`: Constructor to create a stopwatch.
    *   `start()`: Starts the stopwatch.
    *   `stop()`: Stops the stopwatch.
    *   `update()`: update the elapsed time stopwatch.
    *   `elapsed(auto_update: bool = False)`: Returns the elapsed time.
    *   `reset()`: Reset the StopWatch back to 0.

*   **Time**: Class for time-related functions.
    *   `wait(sleep: int | float)`: Pauses execution for a specified number of seconds.
    *   `pause(msg: str = "Press enter to continue...")`: Pauses execution until enter is pressed.

### Text Module

*   **Format**: Class for handling text's format.
    *   `reset()`: Clear the format of a text.
    *   `bold()`: Make a text bold.
    *   `italic()`: Make a text italic.
    *   `underline()`: Make a text underlined.
    *   `hide()`: Make a text hidden.
    *   `strikthrough()`: Make a text strikethrough.
    *   `error(title: bool = False)`: Make a text styled as an ERROR (background is colored if title, foreground otherwise).
    *   `warning(title: bool = False)`: Make a text styled as a WARNING (background is colored if title, foreground otherwise).
    *   `ok(title: bool = False)`: Make a text styled as an OK (background is colored if title, foreground otherwise).
    *   `info(title: bool = False)`: Make a text styled as an INFO (background is colored if title, foreground otherwise).
    *   `apply(obj: object, sequence: object | None = None)`: Apply any escape sequence (as a string or an ANSI) to an object (Text, ANSI, Animation, ProgressBar or str).
    *   `tree(d: dict | str | list, title: str | None = None, indent: int = 0`: Get a formated version of a dictionary as bash tree command).
    *   `module_tree()`: Get module's file tree.

*   **Text**: Class for handling text.
    *   `Text(text: object | str = "")`: Constructor to create a text object.
    *   `url_link(url: str, text: str | None = None)`: Creates a link to a url.
    *   `file_link(path: str, line: int | None = None)`: Creates a link to a file and line number.

## Release-Note
* #### v0.1.8:

* #### v0.1.7:
    *   **[FIX]** some mor random bugs
    *   **[FIX]** coding style
    *   **[ADD]** pytests for the whole module (including sub-modules)
    *   **[FIX]** all docstring containing `(optional)`

* #### v0.1.6(2):
    *   **[ADD]** project wiki
    *   **[ADD]** `len()` `Console` compatibility
    *   **[UPDATE]** file tree
    *   **[ADD]** epitech console logo

* #### v0.1.5:
    *   **[ADD]** uninstaller (`uninstall-package`)
    *   **[ADD]** dict tree formating
    *   **[ADD]** `len()` `Animation`, `ANSI` and `Text` compatibility
    *   **[ADD]** New config global settings
    *   **[ADD]** Console stream flush
    *   **[REM]** Useless import
    *   **[ADD]** `Action` and `Actions` classes
    *   **[FIX]** `README` grammar 😅
    *   **[FIX]** Non object class had `object` as parent

* #### v0.1.4:
    *   **[FIX]** Syntax and type error
    *   **[ADD]** package auto-reloader (`install-package` + `check-package`)
    *   **[ADD]** New `Action` class (not implemented yet)
    *   **[ADD]** New import introduction
    *   **[ADD]** New release section in `README`

## License

This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](https://github.com/Jarjarbin06/epitech_console/blob/ad808d437817f8ea2cd44e4a33a38238a41f83c4/LICENSE) file for details.

## Important-Links

*   **Repository**: [https://github.com/Jarjarbin06/epitech_console](https://github.com/Jarjarbin06/epitech_console)

## Footer

*   Repository: [epitech_console](https://github.com/Jarjarbin06/epitech_console)
*   Author: Nathan Jarjarbin
*   Contact: nathan.amaraggi@epitech.eu

⭐️ Like the project? Give it a star!
🐛 Found a bug? Report it in the issues!
