epitech-console 0.1.7.2

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

Epitech Student's project

epitech_console v0.1.7.2

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
2. Features
3. Tech Stack
4. Installation
5. Usage
6. Project Structure
7. API Reference
8. Release Note
9. License
10. Important Links
11. 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:

   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:

   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

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

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

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

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

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

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": "[e-mail]"}
    })

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

Important-Links

• Repository: https://github.com/Jarjarbin06/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!