ux3270

IBM 3270-like terminal UI library for Python.

Documentation | PyPI

Overview

Create terminal applications with an IBM 3270-style interaction model: display a form, let the user fill it in, continue when they submit.

Screenshots

The inventory management demo app showcases the library's capabilities:

Main Menu	Inventory List	Data Entry Form
Menu with single-key selection	Work-with list with action codes	Form with field validation

Installation

pip install ux3270

Or with uv:

uv add ux3270

For development of ux3270 itself:

git clone https://github.com/ljosa/ux3270.git
cd ux3270
uv venv && uv pip install -e .

Quick Start

from ux3270.dialog import Menu, Form, Table, TabularEntry, WorkWithList, SelectionList, show_message

# Create a form with help text
form = Form("DATA ENTRY", help_text="Enter your information")
form.add_field("Name", length=30, required=True,
               help_text="Your full name")
form.add_field("Email", length=40)
result = form.show()  # F1 for help, F3 to cancel
if result:
    print(f"Hello, {result['Name']}!")

# Form with F4=Prompt lookup
def select_dept():
    sel = SelectionList("SELECT DEPARTMENT", ["Code", "Name"])
    sel.add_row(Code="ENG", Name="Engineering")
    sel.add_row(Code="SAL", Name="Sales")
    selected = sel.show()
    return selected["Code"] if selected else None

form = Form("ASSIGNMENT")
form.add_field("Department", prompt=select_dept)  # F4 shows list
result = form.show()

# Work-with list (action codes per row)
wwl = WorkWithList("WORK WITH ITEMS", ["ID", "Name", "Status"])
wwl.add_action("2", "Change")
wwl.add_action("4", "Delete")
wwl.add_action("5", "Display")
wwl.set_add_callback(add_new_item)  # F6=Add
wwl.add_row(ID="001", Name="Item 1", Status="Active")
wwl.add_row(ID="002", Name="Item 2", Status="Inactive")
result = wwl.show()  # Returns [{"action": "2", "row": {...}}, ...]
for item in result or []:
    if item["action"] == "2":
        edit_item(item["row"]["ID"])

# Create a menu
menu = Menu("MAIN MENU")
menu.add_item("1", "Option 1", lambda: print("Selected 1"))
menu.add_item("2", "Option 2", lambda: print("Selected 2"))
menu.run()  # Runs until user exits with F3 or X

# Display a table (with pagination)
table = Table("RESULTS", ["ID", "Name", "Status"])
table.add_row("001", "Item 1", "Active")
table.add_row("002", "Item 2", "Inactive")
table.show()  # F7/F8 to page up/down

# Tabular entry (table with editable columns)
te = TabularEntry("PORTFOLIO UPDATE", panel_id="PORT01")
te.add_column("Ticker", width=8)
te.add_column("Name", width=20)
te.add_column("New Amount", width=12, editable=True, required=True)
te.add_column("Previous", width=12)
te.add_row(Ticker="AAPL", Name="Apple Inc", Previous="1,234.56")
te.add_row(Ticker="GOOGL", Name="Alphabet", Previous="5,678.90")
result = te.show()  # Tab between cells, Enter to submit

# Show a message
show_message("Operation completed", msg_type="success")

Demo App

The inventory management system demonstrates the library:

# Load sample data and run
inventory-app --demo

# Or just run (empty database)
inventory-app

# Other options
inventory-app --help

Keyboard Controls

Terminal Width

Tables and lists automatically adapt to terminal width:

• Uses actual terminal width (not hardcoded 80 columns)
• Short columns are preserved at natural width
• Long columns are truncated to fit available space
• Truncated content shows > indicator (e.g., "Very long tex>")

IBM 3270 Colors

The library uses IBM 3270 color conventions:

• Green: Input fields
• Turquoise: Labels (protected fields)
• White: Titles, headers (intensified)
• Red: Error messages
• Yellow: Warnings

Requirements

• Python 3.10+
• Unix-like system (Linux, macOS)
• Terminal with ANSI support

Development

Building and Viewing Documentation Locally

uv run mkdocs serve

Then open http://127.0.0.1:8000 in your browser. The site auto-reloads on changes.

Regenerating Screenshots

Screenshots require Docker with VHS:

./screenshots/generate.sh

Cutting a Release

The version number must be updated in two places that must match:

1. pyproject.toml: The version field (e.g., version = "0.2.0")
2. Git tag: Must be v + version (e.g., v0.2.0)

Release process:

# 1. Update version in pyproject.toml
#    Edit: version = "0.2.0"

# 2. Commit the version bump
git add pyproject.toml
git commit -m "Bump version to 0.2.0"

# 3. Create and push tag (triggers release workflow)
git tag v0.2.0
git push origin main --tags

The GitHub Actions workflow will automatically:

• Build and publish the package to PyPI
• Deploy versioned documentation to GitHub Pages

Documentation Versions

Documentation is versioned using mike. Each release gets its own version, with latest always pointing to the most recent release. Users can switch versions using the dropdown in the docs.

License

MIT