or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

animations.mdcolors-markup.mdfile-loading.mdindex.mdterminal.mdutilities.mdwidgets.mdwindow-management.md
tile.json

tessl/pypi-pytermgui

Python TUI framework with mouse support, modular widget system, customizable and rapid terminal markup language and more

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pytermgui@7.7.x

To install, run

npx @tessl/cli install tessl/pypi-pytermgui@7.7.0

index.mddocs/

PyTermGUI

PyTermGUI is a comprehensive Python terminal user interface (TUI) framework that enables developers to create sophisticated command-line applications with modern UI capabilities. It provides a modular widget system with mouse support, allowing for the creation of interactive terminal applications that feel more like desktop applications.

Package Information

  • Package Name: PyTermGUI
  • Package Type: PyPI
  • Language: Python
  • Version: 7.7.4
  • Installation: pip install PyTermGUI
  • Requirements: Python >=3.8, wcwidth, typing_extensions
  • Optional Dependencies: PyYAML (for YAML file loading)

Core Imports

import pytermgui as ptg

Specific imports for common functionality:

from pytermgui import Widget, Container, Button, Label
from pytermgui import get_terminal, WindowManager
from pytermgui import Color, tim

Basic Usage

import pytermgui as ptg

# Create a simple application window
with ptg.WindowManager() as manager:
    # Create a container with widgets
    window = ptg.Window(
        "[210 bold]Welcome to PyTermGUI",
        "",
        ptg.Button("Click me!", lambda btn: print("Button clicked!")),
        ptg.InputField(),
        "",
        ["Submit", lambda btn: manager.stop()],
        title="My App"
    )
    
    manager.add(window)

Architecture

PyTermGUI follows a layered architecture:

  • Widget System: Base Widget class with inheritance hierarchy for all UI components
  • Layout Management: Container-based layout with automatic sizing and positioning
  • Terminal Interface: Low-level ANSI escape sequence handling and terminal capabilities
  • Markup Language (TIM): Rich text formatting with colors, styles, and layout
  • Event System: Mouse and keyboard event handling with widget focus management
  • Animation Framework: Smooth transitions and animated properties
  • Window Management: Multi-window interface with compositing and layering

Capabilities

Widget System

Core widget functionality including the base Widget class, containers for layout management, and a comprehensive set of interactive UI components like buttons, input fields, checkboxes, sliders, and more.

class Widget:
    def __init__(self, **attrs): ...
    
class Container(Widget):
    def __init__(self, *widgets, **attrs): ...
    def add(self, widget): ...

class Label(Widget):
    def __init__(self, value="", **attrs): ...

class Button(Widget):
    def __init__(self, label, onclick=None, **attrs): ...

class InputField(Widget):
    def __init__(self, value="", prompt="", **attrs): ...

Widget System

Color and Styling

Advanced color management with support for RGB, HEX, indexed terminal colors, and palette generation. Includes the TIM (Terminal Inline Markup) language for rich text formatting.

class Color:
    def __init__(self, value): ...
    @property
    def rgb(self) -> tuple[int, int, int]: ...
    def hex(self) -> str: ...

def str_to_color(color_str: str) -> Color: ...
def foreground(text: str, color: str | Color) -> str: ...
def background(text: str, color: str | Color) -> str: ...

class MarkupLanguage:
    def parse(self, text: str) -> list: ...

Colors and Markup

Terminal Interface

Low-level terminal control including ANSI escape sequences, cursor management, screen control, and input handling with keyboard and mouse support.

class Terminal:
    def __init__(self): ...
    @property
    def size(self) -> tuple[int, int]: ...
    def print(self, *args, **kwargs): ...

def get_terminal() -> Terminal: ...
def getch(timeout: float = None) -> str: ...
def clear(what: str = "screen") -> None: ...
def move_cursor(pos: tuple[int, int]) -> None: ...

Terminal Interface

Window Management

Multi-window interface system with window compositing, event routing, and layout management for complex desktop-like applications.

class WindowManager:
    def __init__(self): ...
    def add(self, window): ...
    def run(self): ...
    def stop(self): ...

class Window(Container):
    def __init__(self, *widgets, title="", **attrs): ...

class Compositor:
    def __init__(self): ...
    def render(self): ...

Window Management

Animation System

Smooth property animations and transitions for creating dynamic user interfaces with configurable easing and timing.

class Animator:
    def schedule(self, animation): ...
    def run(self): ...

class FloatAnimation:
    def __init__(self, duration: float, start: float, end: float): ...

class AttrAnimation:
    def __init__(self, obj, attr: str, duration: float, end_value): ...

def is_animated(obj) -> bool: ...

Animations

File Loading and Serialization

Load widget configurations from YAML/JSON files and serialize widget states for persistence and configuration management.

class YamlLoader:
    def load(self, path: str): ...

class JsonLoader:  
    def load(self, path: str): ...

class Serializer:
    def dump(self, widget) -> dict: ...
    def load(self, data: dict): ...

File Loading

Utilities and Helpers

Text processing utilities, prettification tools, syntax highlighting, and debugging helpers for development and display enhancement.

def strip_ansi(text: str) -> str: ...
def strip_markup(text: str) -> str: ...
def real_length(text: str) -> int: ...
def prettify(obj) -> str: ...
def pprint(*items, **kwargs): ...

class Inspector:
    def inspect(self, obj): ...

Utilities

Types

from typing import Union, Optional, Callable, Any
from enum import Enum, IntEnum

WidgetType = Union[Widget, type[Widget]]
ColorType = Union[str, Color]
BoundCallback = Callable[..., Any]

class SizePolicy(IntEnum):
    """Values according to which Widget sizes are assigned."""
    FILL = 0
    STATIC = 1
    RELATIVE = 2

class CenteringPolicy(IntEnum):
    """Policies to center Container according to."""
    ALL: int
    VERTICAL: int
    HORIZONTAL: int

class HorizontalAlignment(IntEnum):
    """Policies to align widgets horizontally."""
    LEFT = 0
    CENTER = 1
    RIGHT = 2

class VerticalAlignment(IntEnum):
    """Vertical alignment options for widgets."""
    TOP = 0
    CENTER = 1
    BOTTOM = 2

class Overflow(IntEnum):
    """Overflow policies implemented by Container."""
    HIDE = 0
    SCROLL = 1
    RESIZE = 2
    AUTO = 9999

class WidgetChange(Enum):
    """The type of change that happened within a widget."""
    LINES: str
    SIZE: str
    WIDTH: str
    HEIGHT: str

Global Instances

PyTermGUI provides several global instances for common functionality:

# Global terminal instance
terminal: Terminal

# Global TIM markup processor 
tim: MarkupLanguage

# Global animation manager
animator: Animator

# Global input keys instance
keys: Keys