panelmark is a zero-dependency Python library for defining terminal UI layouts using a readable ASCII-art shell language, and for implementing the interaction logic that runs inside them.
panelmark is the core library in the panelmark ecosystem. It has no runtime dependencies on any terminal library. It defines:
| Feature | Status |
|---|---|
| Shell definition language (ASCII-art DSL) | ✅ Fully working |
# line comments and /* */ block comments |
✅ Fully working |
Horizontal splits (= / - border rows) |
✅ Fully working |
Vertical splits — single-line divider (|) |
✅ Fully working |
Vertical splits — double-line divider (||) |
✅ Fully working |
| Equal-width fill splits (all columns fill-width) | ✅ Columns share space equally (differ by at most 1 char) |
Panel headings (__text__ syntax) |
|
Shell state machine (focus, dirty tracking, key dispatch, on_change, bind) |
✅ Fully working |
Draw command abstraction (DrawCommand, RenderContext, WriteCmd, FillCmd, CursorCmd) |
✅ Fully working |
Interaction base class |
✅ Fully working |
See panelmark-tui limitations for the combined limitations list.
- The shell definition language — an ASCII-art syntax for describing layouts
- The layout model — resolved geometry (row, col, width, height) for each named region
- The draw command abstraction — renderer-agnostic
DrawCommandtypes returned by interactions - The
Interactionbase class — the protocol all interactive widgets implement - The
Shellstate machine — focus, dirty tracking, key dispatch, and value observation
To actually display a shell in a terminal, pair panelmark with panelmark-tui, which wraps blessed and provides a full event loop, built-in interactions, and renderer-specific convenience widgets.
pip install panelmark
from panelmark import Shell, Interaction
from panelmark.draw import DrawCommand, RenderContext, WriteCmd, FillCmd
# 1. Define a layout
LAYOUT = """
|=== <bold>My App</> ===|
|{10R $sidebar$ }|{$main$ }|
|==================|
|{2R $status$ }|
|==================|
"""
# 2. Implement an interaction
class Label(Interaction):
def __init__(self, text: str):
self._text = text
@property
def is_focusable(self) -> bool:
return False
def render(self, context: RenderContext, focused: bool = False) -> list[DrawCommand]:
line = self._text[:context.width].ljust(context.width)
return [WriteCmd(row=0, col=0, text=line)]
def handle_key(self, key) -> tuple:
return False, self.get_value()
def get_value(self):
return self._text
def set_value(self, value) -> None:
self._text = str(value)
# 3. Assign interactions to regions
shell = Shell(LAYOUT)
shell.assign("sidebar", Label("Navigation"))
shell.assign("main", Label("Content area"))
shell.assign("status", Label("Ready"))
# 4. Drive with a renderer (e.g. panelmark-tui)
# result = shell.run() ← panelmark_tui.Shell adds run()| Document | Description |
|---|---|
| Shell Language | Shell, region, and panel concepts; state machine methods |
| Shell Language Syntax | Full grammar reference for the ASCII-art layout DSL |
| Shell Language Examples | Annotated examples; custom interactions; portable rendering patterns |
| Draw Commands | DrawCommand types, RenderContext, and the style dict |
| Custom Interactions | Implementing the Interaction ABC |
| Renderer Spec | Renderer compatibility contract, portable library layer, and extension policy |
| Ecosystem Overview | Layered design; package responsibilities; dependency direction |
| Choosing a Renderer | Decision tree for selecting the right package |
panelmark follows a layered design. The core library is renderer-agnostic; renderer-specific packages extend it.
| Package | Role |
|---|---|
| panelmark (this package) | Zero-dependency core: shell language, layout, draw commands, interaction protocol |
| panelmark-tui | Terminal renderer (blessed); portable-library-compatible |
| panelmark-html | Static HTML/CSS renderer; pre-alpha; foundation for panelmark-web |
| panelmark-web | Live web runtime via WebSockets; portable-library-compatible |
See ecosystem overview for the full design rationale and dependency diagram.
MIT