📦 Jarbin-ToolKit:Console v0.1.2.5

Structured terminal interface system providing unified console I/O, ANSI control, text formatting, and animation rendering through a modular Python API

🔹 Short Description

Jarbin-ToolKit Console is a structured terminal abstraction library that unifies console I/O, ANSI sequence generation, text formatting, and animation rendering into a modular, deterministic Python interface.

It provides:

• unified console input/output with format control
• full ANSI sequence generation (color, cursor, line)
• text and animation object model
• progress bar and spinner rendering system
• terminal size and cursor position introspection

It is not a TUI framework, but a structured terminal I/O and rendering abstraction layer.

🔹 Authors

• Nathan (Jarjarbin06)
• Jarbin Studio

🔹 License

GPL v3

🔹 Target Audience

This library is intended for:

• Python developers building CLI tools requiring structured output
• developers designing terminal-based interfaces or debug consoles
• projects requiring deterministic ANSI color and cursor control
• engineers building animated terminal feedback systems (progress bars, spinners)

🔹 Platform Support

• Python ≥ 3.10
• Linux / Windows / macOS compatible
• Terminal introspection features (cursor, key press) require a live TTY (not available in piped or non-interactive environments)

🔹 Purpose

Jarbin-ToolKit Console aims to:

• abstract terminal I/O behind a unified Console interface
• generate ANSI sequences in a structured and composable way
• provide a text object model enabling formatting via method chaining
• render frame-based animations and progress bars in a deterministic model
• expose terminal metadata (size, cursor position) in a safe, cross-platform manner

It is not a curses replacement, but a modular terminal control and rendering toolkit.

🔹 Key Features

• Unified Console static interface for all terminal I/O
• ANSI sequence generation via composable ANSI and Color objects
• Cursor manipulation through Cursor (move, hide, show, save, restore)
• Line manipulation through Line (clear, erase, restore)
• Text object with format chaining (bold, italic, underline, error, warning, etc.)
• Animation object with step-based frame rendering
• ProgressBar object with percent tracking, spinner integration, and style customization
• Spinner factory for standalone spinner animations
• Style object for configuring animation visual characters
• Base animation packs (BasePack) for Animation and ANSI ready-to-use presets
• Alternate screen entry and exit support
• Terminal size and cursor position introspection
• Configurable via Setting (banner, log mode, debug, safe mode)
• Optional log file integration

🔹 Architecture Overview

User Code
   │
   ▼
Console (static interface)
   │
   ├──────────────────────────┐
   ▼                          ▼
Text System               ANSI System
   │                          │
   ├── Text                   ├── ANSI
   └── Format (base)          ├── Color
                              ├── Cursor
                              └── Line
   │                          │
   ▼                          ▼
Animation System          System
   │                          │
   ├── Animation              ├── Setting
   ├── ProgressBar            ├── Log
   ├── Spinner                ├── Config
   ├── Style                  ├── Time / StopWatch
   └── BasePack               └── Error
   │
   ▼
Terminal Rendering Output

🔹 Core Concept

The system is organized around a static Console class that serves as the entry point for all terminal operations. All subsystems are independently usable but designed to compose through a shared object model.

Console

Central static interface to the terminal:

Console.print(*value, separator, start, end, file, auto_reset, cut, sleep)
Console.input(msg, separator, wanted_type)
Console.get_key_press()
Console.get_cursor_position()
Console.get_size()
Console.flush(stream)
Console.enter_alternate_screen(hide_cursor)
Console.exit_alternate_screen(show_cursor)

Exposes stdin, stdout, and stderr as class properties.

ConsoleMeta implements :

• __len__ to return the current terminal column width.
• __enter__ and __exit__ to open and close automatically the alternate screen using with Console: ...

Text

Wraps a string with composable format methods:

text = Text("Hello").bold().underline().error()

Inherits from Format, which provides all formatting operations as instance methods. Compatible with ANSI, Animation, and str through __add__.

ANSI

Wraps an ANSI escape sequence as a composable object:

seq = ANSI(f"{ANSI.ESC}31m")

Composable with Text, Animation, ProgressBar, and str via __add__. All ANSI subsystems return ANSI objects.

Color

Generates ANSI color sequences from preset constants or raw values:

Color(Color.C_FG_RED)
Color.rgb_fg(0, 145, 211)
Color.color_bg(42)

Instantiation via __new__ directly returns an ANSI object.

Animation

Frame-based animation container:

anim = Animation(["frame1", "frame2", "frame3"])
anim.update()
str(anim)

Supports composition via +, step tracking, auto-reset, and direct indexing.

ProgressBar

Percent-driven animation renderer:

bar = ProgressBar(length=20, style=Style(...), spinner=Spinner.stick())
bar.update(50)
bar.render(delete=True)

Configurable percent style (num, bar, mix), percent position (b/a), and spinner position.

🔹 API / Function Documentation

🔹 Console

🔹 Text

🔹 Format (inherited by Text, Animation, ProgressBar)

🔹 ANSI

🔹 Color

🔹 Cursor

🔹 Line

🔹 Animation

🔹 ProgressBar

🔹 Spinner

🔹 Style

🔹 BasePack (Animation)

Pre-built animation sequences updated via BasePack.update(style):

🔹 BasePack (ANSI)

Pre-built color tuples updated via BasePack.update():

🔹 Project Structure

jarbin_toolkit_console/
├── console.py
├── __init__.py
├── Animation/
│   ├── animation.py
│   ├── basepack.py
│   ├── progressbar.py
│   ├── spinner.py
│   ├── style.py
│   └── __init__.py
├── ANSI/
│   ├── ansi.py
│   ├── basepack.py
│   ├── color.py
│   ├── cursor.py
│   ├── line.py
│   └── __init__.py
├── Text/
│   ├── text.py
│   ├── format.py
│   └── __init__.py
└── System/
    ├── setting.py
    └── __init__.py

🔹 Usage

🔹 Basic Print

from jarbin_toolkit_console import Console

Console.print("Hello, world!")
Console.print("Truncated output to terminal size", cut=True)
Console.print("Delayed continuity", sleep=1.5)

🔹 Formatted Text

from jarbin_toolkit_console import Text, Console

msg = Text.Text("Build failed").bold().error()
Console.print(msg)

🔹 ANSI Color

from jarbin_toolkit_console import ANSI, Console

red = ANSI.Color.rgb_fg(200, 50, 50)
reset = ANSI.Color(ANSI.Color.C_RESET)

Console.print(f"{red}Error{reset}: something went wrong")

🔹 Cursor Control

from jarbin_toolkit_console import ANSI, Console

Console.print(ANSI.Cursor.hide(), end="")
Console.print(ANSI.Cursor.move(5, 10), end="")
Console.print("positioned text", end="")
Console.print(ANSI.Cursor.show(), end="")

🔹 Animation

from jarbin_toolkit_console import Animation, Console

anim = Animation.Animation(["[   ]", "[-  ]", "[-- ]", "[---]"])

for _ in range(8):
    Console.print(anim.render(delete=True), sleep=0.2)
    anim.update()

🔹 Progress Bar

from jarbin_toolkit_console import Animation, ANSI, Console

bar = Animation.ProgressBar(20, spinner=Animation.Spinner.stick())

for i in range(101):
    bar.update(i, update_spinner=not(i % 6))
    Console.print(bar.render(hide_spinner_at_end = True) + " " + ANSI.Cursor.previous(), sleep=0.02)

Console.print()

🔹 Alternate Screen

from jarbin_toolkit_console import Console

with Console:
    Console.print("Running in alternate screen...", sleep=2)

🔹 Initialization

import jarbin_toolkit_console as jtc

jtc.init(banner=True)
# ... use the library
jtc.quit()

🔹 Build / Installation

Installation

pip install jarbin-toolkit-console

🔹 Execution Behavior

• All Console methods are strictly static — no instance required
• ANSI sequences are generated lazily at call time — no pre-computation
• Animation and ProgressBar rendering is frame-driven and manual — no background threads
• get_key_press and get_cursor_position require a live TTY — return safe defaults otherwise
• Console.print always returns the final rendered Text object
• Setting.update() is called at module import — all subsystems self-initialize

🔹 Memory Model

• Console holds no state — all operations are stateless static calls
• Text, ANSI, and Animation are immutable by composition — operators always return new objects
• Animation and ProgressBar maintain internal mutable step/percent state
• Setting maintains global configuration as class-level attributes — shared across all imports
• No heap allocation outside standard Python object creation

🔹 Design Philosophy

• static interface over instantiation for console operations
• composable object model for all output types
• explicit ANSI generation — no implicit terminal state assumption
• safe fallback behavior for non-TTY environments
• modular subsystems with no circular runtime dependencies
• deterministic rendering — output is a function of state only

🔹 Current State

⚠️ Core interface is stable and functional

Status:

• Console I/O fully implemented
• ANSI color, cursor, and line control fully implemented
• Text and Format system fully implemented
• Animation and ProgressBar system fully implemented
• Spinner factory implemented
• BasePack presets implemented for Animation and ANSI
• Setting and configuration system implemented

Limitations:

• get_key_press and get_cursor_position unavailable in non-TTY environments
• cut option in Console.print does not handle ANSI sequences correctly
• cut does not adapt dynamically on terminal resize
• No async rendering support
• No layout or grid system

🔹 Limitations

• TTY-dependent features fail silently in piped or headless environments
• cut=True in Console.print produces incorrect results with ANSI sequences
• ProgressBar and Animation rendering assumes single-line output
• No built-in thread safety for shared Animation or ProgressBar state
• Setting is global and shared — not suitable for isolated multi-context use

🔹 Extension / Contribution

Possible extensions:

• async-compatible animation renderer
• multi-line layout and grid rendering system
• TTY-safe ANSI stripping utility
• structured log output formatter built on Format
• theme system layered on Color and BasePack

🔹 Notes

This library is designed as a structured terminal I/O and rendering toolkit, not a full terminal UI framework.

It prioritizes:

• modularity between subsystems
• explicit and composable output construction
• deterministic rendering without hidden terminal state

🔹 Identity Summary

Jarbin-ToolKit Console is:

• a structured terminal I/O abstraction layer
• a composable ANSI sequence generation system
• a deterministic animation and progress rendering toolkit
• a modular, extensible terminal control library

🔹 Final Rule

If output behavior is not explicitly constructed, it does not exist.