epitech-console 0.1.8

Console tools (animation / colored printing / formating / etc...)

last update : PACKAGE = 2025-12-17 16:07 UTC+1(Paris) ; README = 2025-12-17 16:07 UTC+1(Paris)

epitech_console v0.1.8

Description

epitech_console is a Python library designed to help you create enhanced terminal interfaces. It's improving the appearance and readability of your command-line interface with lightweight animations, colorful text, and neat formatting. If you want to make your terminal programs more readable and visually structured, this library is for you!

Table of Contents

1. Description
2. Features
3. Tech Stack
4. Installation
5. Usage
6. Project Structure
7. API Reference
8. Release Notes
9. License
10. Important Links
11. Footer

Features

• Cool Text Effects: Easily add colors, bold text, italics, underlines, and even strike through to your terminal text.
• Animations: Display simple animations. Useful for loading indicators or status displays.
• Progress Bars: Show the progress of long tasks with customizable progress bars. Provides clear and configurable visual feedback.
• Timers: Use the built-in stopwatch to measure how long parts of your code take to run.
• Configuration: Easily manage settings for your applications.
• Error Handling: Provides structured and readable error messages.
• Cursor Control: Provides methods to move, show, and hide the cursor.
• Line Control: Features for clearing lines or the entire screen.
• ANSI Escape Sequence Handling: Provides classes for generating ANSI escape sequences to control text color, formatting, and cursor movement.

Tech-Stack

• Language: Python - Chosen for its readability and versatility.
• Frameworks: Python - Entirely implemented in Python.

Installation

To begin , install epitech_console:

Prerequisites:

Make sure you have Python 3.11 or newer installed on your computer. You can check your Python version by opening a terminal and typing python --version.

Install from PyPI (recommended):

Open your terminal and run this command:

pip install epitech_console

This will automatically download and install the library from PyPI.

Install from GitHub:

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

git clone -b latest https://github.com/Jarjarbin06/epitech_console.git
make -C epitech_console install

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 examples demonstrating how to use epitech_console:

Basic Text Formatting

from epitech_console.Text import Text
from epitech_console.ANSI import Color
from epitech_console import init, quit

init()

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

print(my_text)

quit(delete_log=True)

Creating an Animation

from epitech_console.Animation import Animation, BasePack
from epitech_console.System import Console
from epitech_console import init, quit

init()

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

quit(delete_log=True)

Creating a custom Animation

from epitech_console.Animation import Animation
from epitech_console.System import Console
from epitech_console import init, quit

init()

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

quit(delete_log=True)

Using simple Progress Bar

from epitech_console.Animation import ProgressBar, Spinner
from epitech_console.System import Console
from epitech_console import init, quit

init()

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))
    Console.print(my_progress_bar.render(delete=True), sleep=0.05)

quit(delete_log=True)

Using advanced Progress Bar with variable size

from epitech_console.Animation import ProgressBar, Style
from epitech_console.ANSI import Line
from epitech_console.System import Console
from epitech_console import init, quit

init()

style : Style = Style(on="=", off=" ", border_left="[", border_right="]")
bar : ProgressBar

for i in range(1001):
	bar = ProgressBar(len(Console) - 15, percent_style="mix", style=style)
	bar.update(i/10)
	Console.print(bar.render(delete=True), sleep=0.01, cut=True)

quit(delete_log=True)

Utilizing the Stopwatch

from time import sleep
from epitech_console.System import StopWatch
from epitech_console import init, quit

init()

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

quit(delete_log=True)

Create a config.ini file

from epitech_console.System import Config
from epitech_console import init, quit

init()

my_path = "."
if not Config.exist(my_path):
    my_config = Config(my_path, {
      "GENERALE" : {"theme": "dark", "language": "en"},
      "USER" : {"username": "guest", "email": "[e-mail]"}
    }, file_name="my_config.ini")

quit(delete_log=True)

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

Project-Structure

REPO/
├── .github/
│   ├── workflows/
│   │   ├── codeql.yml
│   │   └── test-package.yml
├── 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
│   ├── log/
│   ├── System/
│   │   ├── __init__.py
│   │   ├── action.py
│   │   ├── config.py
│   │   ├── console.py
│   │   ├── log.py
│   │   ├── setting.py
│   │   ├── stopwatch.py
│   │   └── time.py
│   ├── Text/
│   │   ├── __init__.py
│   │   ├── format.py
│   │   └── text.py
│   ├── __init__.py
│   └── config.ini
├── script/
│   ├── auto-reload-package
│   ├── check-package
│   ├── install-package
│   ├── test-package
│   └── uninstall-package
├── source/
│   ├── epitech_console_logo.png
│   └── epitech_logo.png
├── tests/
│   ├── tests Animation/
│   │   ├── test_animation_animation.py
│   │   ├── test_animation_basepack.py
│   │   ├── test_animation_progressbar.py
│   │   ├── test_animation_spinner.py
│   │   └── test_animation_style.py
│   ├── tests ANSI/
│   │   ├── test_ansi_ansi.py
│   │   ├── test_ansi_basepack.py
│   │   ├── test_ansi_color.py
│   │   ├── test_ansi_cursor.py
│   │   └── test_ansi_line.py
│   ├── tests Error/
│   │   └── test_error_error.py
│   ├── tests System/
│   │   ├── test_system_action.py
│   │   ├── test_system_config.py
│   │   ├── test_system_console.py
│   │   ├── test_system_stopwatch.py
│   │   └── test_system_time.py
│   └── tests Text/
│   │   ├── test_text_format.py
│   │   └── test_text_text.py
├── .gitignore
├── LICENSE
├── Makefile
├── MANIFEST.in
├── pyproject.toml
└── README.md

API-Reference

. = function ; + = class constructor ; _ = class method ; @ = static method ; # = class variable

• .init(): Initializes the module, BasePacks and Setting classes and the log file (if activated in the config file).
• .quit(show: bool = False, delete_log: bool = False): Uninitializes the module and the log file (if activated in the config file).

Animation Module

• Animation: Class for creating animations.

  • +Animation(animation: list[Any] | 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.
  • _is_last(): Returns whether the current step is the last one.
  • _reset(): Resets the current step to 0.

• BasePack: Predefined animation packs.

  • @update(style: Style = Style("#", "-", "<", ">", "|", "|")): Update the BasePack animations to fit with the given Style (or the default one if no Style given).
  • #P_SLIDE_R: Character sliding to the right.
  • #P_SLIDE_L: Character sliding to the left.
  • #P_SLIDER_R: Slider going right.
  • #P_SLIDER_L: Slider going left.
  • #P_FILL_R: Filling to the right.
  • #P_FILL_R: Filling to the left.
  • #P_EMPTY_R: Emptying to the right.
  • #P_EMPTY_L: Emptying to the left.
  • #P_FULL: Full.
  • #P_EMPTY: Empty.

• ProgressBar: Class for creating progress bars.

  • +ProgressBar(length: int, animation: Animation | None = None, style: Style = 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: ANSI | tuple[ANSI, ANSI, ANSI] = 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: Style = Style("#", " ", "#", "#", "", "")): Creates a stick spinner.
  • @plus(style: Style = Style("#", " ", "#", "#", "", "")): Creates a plus spinner.
  • @cross(style: Style = 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: list[Any | str] | Any | str = ""): Constructor to create an ANSI sequence.
  • #ESC: ANSI escape character.

• BasePack: Ready-to-use ANSI escape sequences.

  • @update(): Update the BasePack escape sequences (currently reserved for future extensions).
  • #P_ERROR: Colors for error title and body.
  • #P_WARNING: Colors for warning title and body.
  • #P_VALID: Colors for valid title and body.
  • #P_INFO: Colors for information title and body.

• Color: Class for ANSI color codes.

  • @color(color: int): Returns ANSI sequence for pre-made color codes.
  • @color_fg(color: int): Returns ANSI sequence for a foreground color.
  • @color_bg(color: int): Returns ANSI sequence for a background 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(): Returns ANSI sequence for a foreground colored as Epitech (light).
  • @epitech_bg(): Returns ANSI sequence for a background colored as Epitech (light).
  • @epitech_dark_fg(): Returns ANSI sequence for a foreground colored as Epitech (dark).
  • @epitech_dark_bg(): Returns ANSI sequence for a background colored as Epitech (dark).
  • #C_RESET: Reset color code.
  • #C_BOLD: Bold color code.
  • #C_ITALIC: Italic color code.
  • #C_UNDERLINE: Underline color code.
  • #C_FLASH_SLOW: Slow flashing color code.
  • #C_FLASH_FAST: Fast flashing color code.
  • #C_HIDDEN: Hidden color code.
  • #C_STRIKETHROUGH: Strikethrough color code.
  • #C_FG_...: Foreground colors.
  • #C_BG_...: Background colors.

• 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(x: int = 0): Moves the cursor at position x on the same line.
  • @set(): Save the position of the cursor.
  • @reset(): Load the saved position of the cursor.
  • @show(): Shows the cursor.
  • @hide(): Hides 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 move the cursor to the top-left corner.
  • @clear_previous_line(n: int = 1): Go to the previous n lines, clear it 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 | None = None): Constructor to create an Actions object.

• Config: Class for configuration management.

  • +Config(path:str, data: dict | None = None, file_name:str = "config.ini"): Constructor to create a Config object (create the config file if it does not exist, read it otherwise).
  • _get(section: str, option: str, wanted_type: type = str): Returns the value of type wanted_type in section section and option option.
  • _delete(cached: bool = False): Deletes the configuration file (and removes cached values unless cached=True).
  • @exist(path: str, file_name: str = "config.ini"): Returns whether a config file named file_name exist in path or not.

• Console: Class for console output.

  • @print(*args, separator: str = " ", start: str = "", end: str = "\n", file: Any = stdout, auto_reset: bool = True, sleep: int | float | None = None, cut: bool = False): Print any objects in the terminal (or in any other file), starting with start and ending with end, if multiple value are to be printed, they will be separated by separator, if cut then the text will be cut to fit in the terminal, optional waiting after printing of sleep seconds.
  • @input(msg: str = "Input", separator: str = " >>> ", wanted_type: type = str): Returns a user text input changed to wanted_type.
  • @flush(stream: Any = stdout): Flush any content in stream.

• Log: Class for log files.

  • +Log(path: str, file_name: str | None = None: Constructor to create a log.
  • _log(status: str, title: str, description: str): Create a formatted log and save it a log file.
  • _comment(comment: str): Create a non formatted log and save it in a log file.
  • _save(log_str: str): Save a log in a log file.
  • _close(delete: bool = False) format the end of the log file and save it, delete the log file if delete_logs.
  • _delete() delete the log file.
  • _read(): Returns the content of a log file.
  • _show(): Print a formatted table of the content of a log_file.

• Setting: Class for module's settings.

  • @update(): Update the Settings.
  • #S_PACKAGE_NAME: Package's name.
  • #S_PACKAGE_VERSION: Package's version.
  • #S_PACKAGE_DESCRIPTION: Package's description.
  • #S_PACKAGE_REPOSITORY: Package's repository URL.
  • #S_SETTING_SHOW_BANNER: Package's show-banner setting.
  • #S_SETTING_AUTO_COLOR: Package's auto-color setting.
  • #S_SETTING_SAFE_MODE: Package's safe-mode setting.
  • #S_SETTING_MINIMAL_MODE: Package's minimal-mode setting.
  • #S_SETTING_DEBUG: Package's debug setting.
  • #S_SETTING_LOG: Package's log setting.
  • #S_LOG_FILE: Package's log_file.

• StopWatch: Class for measuring elapsed time.

  • +StopWatch(start: bool = False): Constructor to create a stopwatch.
  • _start(): Reset and start the stopwatch.
  • _stop(): Update and stop the stopwatch.
  • _update(): Update the elapsed time.
  • _elapsed(auto_update: bool = False): Returns the precise elapsed time.
  • _reset(): Reset the StopWatch back to 0.

• Time: Class for time-related functions.

  • @wait(sleep: int | float): Pauses execution for sleep seconds.
  • @pause(msg: str = "Press enter to continue..."): Pauses execution until enter key 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: Any, sequence: Any | None = None): Apply anything 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 does).
  • @module_tree(): Get module's file tree.

• Text: Class for handling text.

  • +Text(text: Any | 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-Notes

• v0.1.8:

  • [FIX] minor random correction
  • [ADD] pytest tests 100% coverage reached
  • [ADD] some logs in Animation classes
  • [ADD] new logging system
  • [ADD] new pytest tests
  • [ADD] Setting and log classes
  • [FIX] several additional README grammar 😅
  • [FIX] type-hints
  • [UPDATE] test-package workflow

• v0.1.7:

  • [FIX] several additional bugs
  • [FIX] code style improvements
  • [ADD] pytest tests for the whole module (including sub-modules)
  • [FIX] all docstrings containing the word optional

• v0.1.6(2):

  • [ADD] project wiki added
  • [ADD] len() Console compatibility
  • [UPDATE] directory tree
  • [ADD] epitech console logo

• v0.1.5:

  • [ADD] uninstall script (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 classes improperly inherited from object

• 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 file for details.

Important-Links

Files

• Repository: https://github.com/Jarjarbin06/epitech_console/
• PyPI: https://pypi.org/project/epitech-console/

Wiki

• Wiki (take a look): https://github.com/Jarjarbin06/epitech_console/wiki/
• README: https://github.com/Jarjarbin06/epitech_console/blob/main/README.md
• GitHub: https://jarjarbin06.github.io/epitech_console/

Footer

• Repository: epitech_console
• Author: Nathan Jarjarbin
• Contact: [e-mail]

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