Skip to main content

ETForm

ETForm is a Python framework for building native terminal forms and read-only documents with an ncurses interface. Forms collect structured input. Documents render hierarchical manuals, project notes, and other ordered terminal content.

The public API is intentionally small: create a Form to collect values or a Doc to render read-only content, add items in display order, then call run(). ETForm handles terminal rendering, navigation, scrolling, and reusable styled display objects.

Features

  • Native ncurses UI implemented as a CPython extension.
  • Text, boolean, choice, checkbox, integer, and list inputs.
  • Static sections, text blocks, separators, and STable tables for grouping larger forms.
  • Interactive ITable inputs with editable rows and structured table results.
  • Styled text with alignment, color, bold, italicized, dim, underline, blink, strikethrough, and wrapping attributes.
  • Inline text editing with cursor movement and clipboard paste.
  • Scrollable integer fields with optional min and max bounds.
  • File, calendar, and clock picker tools for text and list fields.
  • Static Unicode Braille canvases for compact terminal graphics.
  • Hierarchical read-only documents with headings, paragraphs, code blocks, reusable display objects, margins, boxes, and scrolling.
  • Typed package metadata through py.typed and .pyi stubs.

Install

The distribution and Python import are both named etform. Once published to PyPI, install it with:

python3 -m pip install etform

The planned prebuilt wheels target CPython 3.11-3.14 on glibc-based Linux x86-64 (manylinux_2_28, requiring glibc 2.28 or newer). Other Linux systems may need to build from source. Windows is not supported; macOS builds have not been tested. Python 3.11 or newer is required.

To build from source, ETForm needs a C compiler, Python development headers, wide-character ncurses, and the panel library.

On Debian or Ubuntu:

sudo apt update
sudo apt install python3-dev build-essential libncurses-dev

From a source checkout:

python3 -m pip install .

For editable development:

python3 -m pip install -e .

Clipboard paste uses xclip when available. Running the interface requires an interactive terminal with a suitable terminfo database.

Publishing

The package has not been published by this repository's workflow until a maintainer configures PyPI and publishes a release. Create the etform project or a pending trusted publisher on PyPI for repository canadaluke888/TForm, workflow package.yml, and environment pypi. Review the project's licensing and the licenses of bundled native dependencies before distributing it.

Update VERSION, then create and publish a GitHub release tagged with v followed by that version (for example, v0.17.0). The packaging workflow builds the source distribution and Linux wheels, tests the wheels, and publishes them through PyPI Trusted Publishing. Each PyPI version can only be uploaded once. The workflow also builds downloadable artifacts on pushes, pull requests, and manual runs without publishing them. PyPI names are claimed on first upload.

Quick Start

from etform import BrailleCanvas, Calendar, Clock, FilePicker, Form, Image, STable, Text


form = Form(title="Project Setup")
commands = STable(
    title=Text("Commands", align="center", bold=True, color="yellow"),
    color="cyan",
)
commands.add_column("Command")
commands.add_column("Default")
commands.add_row("Build", "python3 setup.py build_ext --inplace")
commands.add_row("Demo", "python3 examples/form_demo.py")

form.add_section(
    Text("Create a project configuration.", color="cyan", bold=True),
    commands,
    boxed=True,
)

form.add_text_input(
    key="name",
    label=Text("Project Name", color="cyan", bold=True),
    description="The display name for this project.",
)

form.add_int_input(
    key="workers",
    label="Workers",
    default=4,
    min=1,
    max=32,
    scrollable=True,
    description="Number of worker processes.",
)

form.add_choice_input(
    key="environment",
    label="Environment",
    choices=["Development", "Staging", "Production"],
    default="Development",
)

form.add_checkbox_input(
    key="features",
    label="Features",
    options=["Logging", "Metrics", "Tracing"],
    default=["Logging"],
)

form.add_text_input(
    key="config_path",
    label="Config File",
    tools=FilePicker(mode="file", start_dir="."),
)

form.add_text_input(
    key="release_date",
    label="Release Date",
    tools=Calendar(),
)

form.add_text_input(
    key="release_time",
    label="Release Time",
    tools=Clock(format="12h", include_seconds=True),
)

values = form.run()
if values is None:
    print("Canceled")
else:
    print(values)

Run the included demo from the repository root:

python3 examples/form_demo.py

Run the separate document demo with:

python3 examples/doc_demo.py

Core API

Import the framework objects from etform:

from etform import BrailleCanvas, Calendar, Clock, CodeBlock, Doc, FilePicker, Form, Group, ITable, Image, OrderedList, Paragraph, STable, Text, UnorderedList

Doc

Doc is the read-only counterpart to Form. It renders static document items vertically in the order passed to Doc.add() and supports line scrolling, page scrolling, and Home/End navigation. Margins reduce the document viewport without introducing coordinate placement.

from etform import CodeBlock, Doc, Group, OrderedList, Paragraph, Text, UnorderedList

doc = Doc(
    title="Project Notes",
    margin_x=4,
    syntax_highlight=True,
    show_border=True,
)

doc.add(
    Text("Project Notes", align="center", bold=True, color="cyan"),
    Paragraph(
        "ETForm documents support ",
        Text("inline styled text", color="yellow", bold=True),
        " without a markup parser.",
    ),
    UnorderedList(
        "Plain strings become paragraph-style list items",
        Paragraph("Use ", Text("Text", color="cyan"), " for inline spans."),
        OrderedList("Nested ordered item"),
    ),
    CodeBlock(
        code="print('hello from ETForm docs')",
        lang="python",
    ),
)

controls = Group("Controls", boxed=True)
controls.add(
    Paragraph("Use Up and Down to scroll one line at a time."),
    Paragraph("Press Q or Escape to close the document."),
)
doc.add(controls)
doc.run()

The page border uses the document margins as its outer boundaries and scrolls with the document. Its bottom edge is rendered at the actual end of the document rather than at the bottom of the viewport. Disable it with show_border=False.

Doc.add() accepts str, Text, Paragraph, Group, Table, CodeBlock, BrailleCanvas, Image, OrderedList, and UnorderedList, and returns the document for chaining. Plain strings and standalone Text objects are converted to paragraph-style blocks internally. Paragraph is the block-level container for mixed inline runs; Text remains the styled inline unit. OrderedList and UnorderedList are static document renderables and are separate from Form.add_list_input().

Group(label, boxed=False, padding=1) groups normal document items together. It accepts the same renderables through Group.add() and can be added with Doc.add(group). Code blocks preserve indentation and clip safely at the right margin. When syntax_highlight=True, recognized CodeBlock.lang values such as "python", "c", "javascript", "json", and "shell" receive token-based syntax colors. Set it to False to render code as plain text. Press Q or Escape to exit.

Form

Form(title: str) creates a form screen. Add fields in the order they should appear, then call run().

run() returns a dict[str, Any] when the user saves the form, or None when the user exits without saving. Static sections, tables, text sections, and separators are visual only and are not included in the returned dictionary. When static content is taller than the viewport, Up/Down scroll through it in steps without selecting a field. Page Up/Page Down move by larger viewport steps, and Home/End jump to the document boundaries. Field selection resumes when the pending field reaches the visible viewport.

ITable

ITable defines an editable table input. Add column names before attaching it to a form. On entry, the first row is created automatically; type into the selected cell, use the arrow keys to navigate, Ctrl+R to add a row, Ctrl+D to delete the selected row, and Ctrl+E to leave the table editor. Press Ctrl+M to select a source row, use Up/Down to select a destination, and press Enter to swap them. Both rows are highlighted in their column colors; Left/Right changes the visible columns, and Escape cancels the swap. Some terminals send the same key code for Ctrl+M and Enter, so Enter also starts a swap while editing a table. Columns use randomly chosen, contrasting colors that remain stable while the form runs. When the table is wider than the available space, moving between cells reveals the corresponding columns.

dependencies = ITable(key="dependencies", title="Dependencies", show_lines=True)
dependencies.add_column("Package")
dependencies.add_column("Version")
form.add_table_input(dependencies)

The submitted value is a mapping with columns and data lists. Table remains an alias for STable, the static table display used in sections and documents.

Text

Text styles labels, section text, separator labels, and checkbox/list option labels.

Text(
    "Workspace",
    align="center",
    bold=True,
    italicized=True,
    underline=True,
    color="cyan",
    wrap_text=True,
)

Supported alignments are left, center, and right. Supported colors are default, white, cyan, yellow, green, blue, magenta, and red. Text styling is used by labels, section text, separator labels, table titles, checkbox/list option labels, and text input placeholders. dim, underline, and blink map to standard curses attributes. strikethrough is exposed as a style flag and renders when the active curses implementation provides a strikeout attribute.

FilePicker

FilePicker(mode="file", start_dir=".") attaches a file or directory browser to a compatible field.

FilePicker(mode="directory", start_dir=".")

Supported modes are file and directory.

Calendar

Calendar() attaches an interactive date picker to text and list fields. It opens anywhere text input is needed, uses the current YYYY-MM-DD value when available, and returns a valid YYYY-MM-DD date string.

form.add_text_input(
    key="release_date",
    label="Release Date",
    tools=Calendar(),
)

Clock

Clock(format="24h", include_seconds=False) attaches a live digital and Braille analog time picker to text and list fields. It returns HH:MM[:SS] in 24-hour mode or hh:MM[:SS] AM/PM in 12-hour mode.

form.add_text_input(
    key="release_time",
    label="Release Time",
    tools=Clock(format="12h", include_seconds=True),
)

BrailleCanvas

BrailleCanvas(width, height, color="default", padding=1) stores a 2x4-dot Unicode Braille raster per terminal cell. Draw with dot coordinates, then pass the canvas to add_section(); the form stores a static copy.

canvas = BrailleCanvas(24, 8, color="cyan")
canvas.draw_circle(canvas.dot_width // 2, canvas.dot_height // 2, 12)
canvas.draw_line(0, 0, canvas.dot_width - 1, canvas.dot_height - 1)
canvas.draw_image("logo.png")
form.add_section(canvas, boxed=True)

draw_image(path) accepts image formats supported by stb_image, including PNG, JPEG, BMP, GIF, TGA, PSD, HDR, PIC, and PNM. The image is aspect-fitted and centered in the Braille dot grid. Transparent pixels are composited over white. Luminance dithering varies Braille dot density to preserve shading, highlights, and reflections instead of applying a single hard threshold. On 256-color terminals each Braille cell uses the nearest xterm color from the source image; 8-color and monochrome terminals use the canvas's configured fallback color. Since one Braille character has one foreground color, all raised dots within the same 2x4 cell share that color. Drawing overlays existing canvas content; call clear() first when replacement is desired.

Image

Image is the portable, image-focused section API. It decodes once when the object is created and renders through Unicode Braille, so it works without Kitty, Sixel, or other terminal-specific graphics protocols.

image = Image(
    "logo.png",
    width=48,
    color="cyan",
    padding=1,
)
form.add_section(image, boxed=True)

width controls the terminal-cell resolution. When height=None, the height is derived from the source aspect ratio in Braille's 2x4 dot coordinate space. Pass an explicit height to constrain the image to a fixed section area. Images use 256-color cells when available and retain the configured color as the 8-color or monochrome fallback.

Table

Table renders static tabular content inside Doc.add() or Form.add_section().

table = Table(
    title=Text("Command Defaults", align="center", bold=True, color="yellow"),
    color="cyan",
)
table.add_column("Command")
table.add_column("Default")
table.add_row("Build", "python3 setup.py build_ext --inplace")
table.add_separator_row(Text("Validation", color="yellow", dim=True))
table.add_row("Demo", "python3 examples/form_demo.py")

form.add_section(Text("Developer Settings", color="cyan", bold=True), table, boxed=True)

Rows must have the same number of cells as the table has columns. The table title accepts str or Text, renders above the table, and is aligned within the table bounds. Tables keep an outer border and a rule below the header by default, while omitting body row and column grid lines. Set show_lines=True to draw row and column grid lines for headers and normal rows. Separators are always one full-width row without column dividers; they are blank by default, accept a plain string for left-aligned unstyled text, or accept Text for formatted and aligned separator text.

Field Types

Text Input

form.add_text_input(
    key="project_name",
    label="Project Name",
    default="",
    placeholder=Text("None", align="right", color="cyan", italicized=True),
    description="Project display name.",
    field_color="cyan",
)

Text fields return strings. placeholder accepts str or Text and is display-only ghost text shown when the field value is empty. Text placeholders keep their alignment, color, bold, italicized, dim, underline, blink, strikethrough, and wrapping attributes within the input box. default is not rendered or inserted into the field; it is returned only when the user leaves the field empty. When wrap_text=True, the field can grow over multiple display lines and supports vertical cursor movement while editing.

Boolean Input

form.add_bool_input(
    key="enabled",
    label="Enabled",
    default=True,
)

Boolean fields return True or False.

Choice Input

form.add_choice_input(
    key="priority",
    label="Priority",
    choices=["Low", "Normal", "High"],
    default="Normal",
)

Choice fields return the selected string.

Checkbox Input

form.add_checkbox_input(
    key="enabled_tools",
    label="Enabled Tools",
    options=["Formatter", "Linter", "Type Checker", "Test Runner"],
    default=["Formatter", "Linter"],
    tick="dot",
)

Checkbox groups return a dictionary mapping each option label to True or False. Supported tick styles are x, block, and dot.

Integer Input

form.add_int_input(
    key="max_workers",
    label="Max Workers",
    default=8,
    min=1,
    max=64,
    scrollable=True,
)

Integer fields return Python integers. Scrollable integer fields can be adjusted with the arrow keys and can enforce optional min and max bounds.

List Input

form.add_list_input(
    key="environment_files",
    label="Environment Files",
    tools=FilePicker(mode="file", start_dir="."),
)

List fields return list[str]. Without tools, users can add, edit, and delete plain text entries. With a FilePicker, Calendar, or Clock, add and edit actions open the attached tool.

Static Sections and Separators

form.add_section(
    Text("Developer Settings", color="cyan", bold=True),
    table,
    boxed=True,
)
form.add_separator(Text("Build & Test", color="green"), color="yellow")

Static sections accept Text, Table, and plain strings, then render them in order. add_text_section() remains available for compatibility, but add_section() is the preferred static-content API.

Controls

The footer shows context-sensitive controls while the form is running. The main navigation controls are:

  • Up / Down: move between fields.
  • Enter: edit the selected field.
  • I: show the selected field description.
  • Ctrl+S: save and return the form values.
  • Q: exit without saving and return None.

Text editing controls:

  • Left / Right: move the cursor.
  • Home / End: jump to the start or end of the text.
  • Delete / Backspace: remove text.
  • Ctrl+V: paste clipboard text.
  • Enter or Ctrl+E: finish editing.
  • Esc: clear the field and finish editing.

List editing controls:

  • A: add an item.
  • E: edit or replace the selected item.
  • D: delete the selected item.
  • Ctrl+E or Esc: leave list editing.

Checkbox controls:

  • Up / Down: move between options.
  • Space or Enter: toggle the selected option.
  • Ctrl+E or Esc: leave checkbox editing.

File picker controls:

  • Up / Down: move between entries.
  • Enter: open a directory or choose a file.
  • B: move back to the parent directory.
  • Ctrl+E: choose the current directory in directory mode.
  • Esc: close the picker.

Demo

The bundled developer settings demo exercises the major field types:

python3 examples/form_demo.py

When saved, it prints the returned form dictionary as JSON.

Metadata

Release files for etform 0.18.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for etform 0.18.0
File Size Uploaded Provenance Actions
etform-0.18.0.tar.gz 880.8 kB With provenance Details for etform-0.18.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for etform 0.18.0
File Actions
etform-0.18.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.28+ x86-64, Linux glibc 2.17+ x86-64 Details for etform-0.18.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
etform-0.18.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.17+ x86-64, Linux glibc 2.28+ x86-64 Details for etform-0.18.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
etform-0.18.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64, Linux glibc 2.17+ x86-64 Details for etform-0.18.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
etform-0.18.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64, Linux glibc 2.17+ x86-64 Details for etform-0.18.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Total release size: 4.5 MB

Release files / etform-0.18.0.tar.gz

Download URL etform-0.18.0.tar.gz
Size 880.8 kB
Tags Source
SHA-256 checksum
How to use checksums
9f32cdb26f321804a358d28b33faa386f86aa84f56396a4adfc7d7217378c3ad
BLAKE2b-256 checksum
How to use checksums
78265d5cc85fbe69e7b4b9bb3c32e6a728dd911a22785c8cb31c19da4031f484
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / etform-0.18.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Download URL etform-0.18.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Size 894.0 kB
Tags CPython 3.14 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
f05b214456baa3c7dec039876593b4e30e5d6938858535a145afa75beef79940
BLAKE2b-256 checksum
How to use checksums
01a6ac8b291c4486e14edb3d0cdcc995474b0347e36d30186a049bbce441b3d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / etform-0.18.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Download URL etform-0.18.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Size 894.1 kB
Tags CPython 3.13 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
395fc9a75f25669e63a388ed02740713ec2042eaf3d4dbc9fd4553621c925b86
BLAKE2b-256 checksum
How to use checksums
0f46d428659e669d24a4d1ff750ff773f7c0e70122928132b4cd00dd372f830e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / etform-0.18.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Download URL etform-0.18.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Size 893.9 kB
Tags CPython 3.12 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
0df457f8029a804979a260fb5e91372f3e70e4b28a81e0e49bf918a85daae9cf
BLAKE2b-256 checksum
How to use checksums
e18cfc3ec947e6ffd1bf0eaf54ca8e3d4405b661b78a83fb28ae7d90770ca093
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Release files / etform-0.18.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl

Download URL etform-0.18.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
Size 887.7 kB
Tags CPython 3.11 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
80bc6169cd962708c5ebf35834f1039fac7d3caba752611a0a212e80ccb5d38f
BLAKE2b-256 checksum
How to use checksums
e98505829d2a530dbfbc995ee948362fe005ba5d99a988e597228a021cd4857a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for etform 0.18.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for etform-0.18.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.18.0 This release

5 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page