DOCSEARCHbyAlgolia
Submit Docs

PyTermGUI Documentation

repository·master·Indexed 25 days ago

https://github.com/bczsalba/pytermgui

A Python TUI (Terminal User Interface) framework for creating modular, resource-efficient terminal applications. It features a desktop-like window manager, built-in mouse support, and TIM (Terminal Interactive Markup) for expressive styling. The library includes a YAML-based styling engine, a CLI inspector for debugging, and the Termage module for exporting terminal output to SVG and HTML.

Tokens
8.9K
Snippets
20
Records
70
Agent score
80%

What's inside PyTermGUI

  1. Overview of PyTermGUI features

    master

    PyTermGUI is a Python TUI framework providing:

    • Window Manager System: A desktop-inspired system with modals and customizable windows.
    • Mouse Support: Enabled out of the box with zero configuration.
    • TIM (Terminal Interactive Markup): A markup language for expressive, styled terminal text including aliases and macros.
    • Styling Engines: Support for both YAML and Python-based styling.
    • Color Resilience: Automatic color downgrading for older terminals and native NO_COLOR support that maintains design contrast.

  2. Use Terminal Inline Markup (TIM) for text styling

    master
    PyTermGUI includes a markup language called TIM (Terminal Inline Markup) designed for easy text styling without raw ANSI sequences. TIM is supported by most components in the library that display text. It is designed for high performance through smart caching and a fast parsing algorithm, and it allows for granular styling where tags are applied as distinct entities, enabling you to clear specific tags without affecting the rest of the style.

  3. Explore PyTermGUI documentation and examples

    master

    PyTermGUI provides a framework for building Terminal User Interfaces (TUIs) using a modular widget system and high-level abstractions for terminal interactions.

    To get started, you can use the following resources:

    • Walkthroughs: For a set of working examples and practical usage patterns, visit the /walkthroughs section.
    • API Reference: For a complete technical specification of all classes, methods, and types, visit the /reference section.
    • Custom Inputs: Documentation for implementing keyboard and mouse input on widgets is available in the /widgets/custom section.

  4. Planned compositor improvements for stability

    master

    To reduce terminal flickering and instability on lower-power emulators, future versions (8.X.0) will implement a more efficient compositor. This involves:

    • Introducing a canvas class to emulate the terminal's display.
    • Changing the compositor to write to a canvas first, only updating the terminal with the final canvas contents to minimize terminal writes.

  6. Use `auto` syntax to generate widgets

    master

    PyTermGUI supports an auto syntax that allows you to create complex widget hierarchies using standard Python datatypes (strings, lists, dicts, tuples) instead of manual widget instantiation. This is automatically handled by Container and its subclasses like Splitter, Window, and Collapsible.

    Common mappings:

    • str: Creates a Label.
    • list: Creates a vertical stack of widgets.
    • tuple: Creates a horizontal Splitter of widgets.
    • dict: Creates a Splitter where keys are labels and values are the widgets (aligned via parent_align).
    • [label, callback]: Creates a Button.
    • [bool, callback]: Creates a Checkbox.
    • [(label1, label2), callback]: Creates a Toggle.
    from pytermgui import Container

# This automatically generates Labels, Splitters, Buttons, and Checkboxes
container = Container(
    "[bold accent]This is my example",
    "",
    "[surface+1 dim italic]It is very cool, you see",
    "",
    {"My first label": ["Some button"]},
    {"My second label": [False]},
    "",
    ("Left side", "Middle", "Right side"),
    "",
    ["Submit button"]
)

  8. Use the PyTermGUI CLI inspector

    master
    You can use the PyTermGUI command-line interface to inspect functions, signatures, and docstrings. Run the command with the -i or --inspect flag followed by a fully qualified name. You can also provide an expression to evaluate, which is useful for inspecting the type and methods of an object resulting from a function or method call.

  9. Export terminal output to SVG using Termage

    master

    You can capture terminal output and export it as an SVG image by using the Termage module. This process involves entering a Terminal.record context, executing your code, and then using Recorder.export_svg on the resulting terminal object.

    To generate a standard SVG image that includes the terminal window decorations (the "chrome"), use the following pattern:

    termage include=docs/src/exports1.py height=5

    To get a rectangular image containing only your code's output (hiding the window's title bar), specify chrome=false during the export process:

    termage-svg chrome=false include=docs/src/exports1.py height=5

    ```termage include=docs/src/exports1.py height=5```

  12. TIM Markup Basics

    master

    TIM (Terminal Interface Markup) uses a bracketed tag syntax to modify text. Tag groups are denoted by square brackets [...], and all text outside these groups is treated as plain text.

    Nesting: When tag groups are nested, only the innermost tag group is parsed.

    Escaping: You can escape a tag group by prefixing it with a backslash \. Note that the backslash is removed during the first parsing pass.

    [tag1 tag2 ...]My content