Drawing

These functions should rarely be necessary to use. BaseSheet.draw must be overridden on non-tabular sheets.

visidata.BaseSheet.refresh(self)

Recalculate any internal state needed for draw(). Overridable.

visidata.vd.redraw()

Clear the terminal screen and let the next draw cycle recreate the windows and redraw everything.

visidata.BaseSheet.draw(self, scr)

Draw on the terminal window scr. Should be overridden.

class visidata.SuspendCurses[source]

Context manager to leave windowed mode on enter and restore it on exit.

Window

BaseSheet.windowWidth

Width of the current sheet window, in single-width characters.

BaseSheet.windowHeight

Height of the current sheet window, in terminal lines.

visidata.TableSheet.topRowIndex

Top row in the window, as an index into TableSheet.rows. Settable.

visidata.TableSheet.leftVisibleColIndex

Leftmost column in the window (after key columns), as an index into TableSheet.visibleCols. Settable.

Cursor

Every Sheet has a cursor, which makes it easy to interact individual elements and slices of data.

A TableSheet has a row cursor and a column cursor, which overlap on a single cell.

visidata.TableSheet.cursorVisibleColIndex

Column cursor, as an index into TableSheet.visibleCols. Settable.

visidata.TableSheet.cursorRowIndex

Row cursor as an index into TableSheet.rows. Settable.

visidata.BaseSheet.checkCursor(self)

Check cursor and fix if out-of-bounds. Overridable.

TableSheet.cursorCol

Current Column object.

TableSheet.cursorValue

Raw value at current row and column.

TableSheet.cursorTypedValue

Typed value at current row and column.

TableSheet.cursorDisplay

Displayed value (DisplayWrapper.text) at current row and column.

visidata.TableSheet.cursorDown(self, n=1)

Move cursor down n rows (or up if n is negative).

visidata.TableSheet.cursorRight(self, n=1)

Move cursor right n visible columns (or left if n is negative).

visidata.TableSheet.moveToNextRow(vs, func, reverse=False, msg='no different value up this column')

Move cursor to next (prev if reverse) row for which func returns True. Returns False if no row meets the criteria.

visidata.TableSheet.moveToCol(vs, col)

Move cursor to column given by col, which can be either the column number or column name.

visidata.TableSheet.moveToRow(vs, rowstr)

Move cursor to row given by rowstr, which can be either the row number or keystr.

Input

visidata.vd.input(prompt, type=None, defaultLast=False, history=[], dy=0, attr=None, updater=<function <lambda>>, **kwargs)

Display prompt and return line of user input.

  • type: string indicating the type of input to use for history.

  • history: list of strings to use for input history.

  • defaultLast: on empty input, if True, return last history item.

  • display: pass False to not display input (for sensitive input, e.g. a password), and to also prevent recording input as if record is False

  • record: pass False to not record input on cmdlog or input history (for sensitive or inconsequential input).

  • completer: completer(val, idx) is called on TAB to get next completed value.

  • updater: updater(val) is called every keypress or timeout.

  • bindings: dict of keystroke to func(v, i) that returns updated (v, i)

  • dy: number of lines from bottom of pane

  • attr: curses attribute for prompt

  • help: string to include in help

visidata.vd.choose(choices, n=None, type='')

Return a list of 1 to n “key” from elements of choices (see chooseMany).

visidata.vd.chooseOne(choices, type='')

Return one user-selected key from choices.

visidata.vd.chooseMany(choices, type='')

Return a list of 1 or more keys from choices, which is a list of dicts. Each element dict must have a unique “key”, which must be typed directly by the user in non-fancy mode (therefore no spaces). All other items in the dicts are also shown in fancy chooser mode. Use previous choices from the replay input if available. Add chosen keys (space-separated) to the cmdlog as input for the current command.

visidata.vd.confirm(prompt, exc=<class 'visidata.EscapeException'>)

Display prompt on status line and demand input that starts with “Y” or “y” to proceed. Raise exc otherwise. Return True.

visidata.vd.launchEditor(*args)

Launch $EDITOR with args as arguments.

Status

visidata.vd.status(*args, priority=0)

Display args on status until next action.

visidata.vd.warning(*args)

Display args on status as a warning.

visidata.vd.fail(*args)

Abort with ExpectedException, and display args on status as a warning.

visidata.vd.exceptionCaught(exc=None, status=True, **kwargs)

Add exc to list of last errors and add to status history. Show on left status bar if status is True. Reraise exception if options.debug is True.

class visidata.ExpectedException[source]

Controlled Exception from fail() or confirm(). Status or other interface update is done by raiser.

Examples

with SuspendCurses():
    try:
        return subprocess.call('less', '/etc/passwd')
    except Exception as e:
        vd.exceptionCaught(e)

passwd = vd.input("password: ", display=False)

# initial value is the formatted value under the cursor
vd.status(vd.input("text to show: ", value=cursorDisplay))

Colors

The TableSheet allows rows, columns, or individual cells to be colorized according to a Python function.

See Color Docs for information on how to configure specific colors and attributes.

visidata.TableSheet.colorizers

List of Colorizers for this class. Class member.

Do not manually update this list to add colorizers on a specific sheet. Instead use addColorizer and removeColorizer.

visidata.TableSheet.addColorizer(self, c)

Add Colorizer c to the list of colorizers for this sheet.

visidata.TableSheet.removeColorizer(self, c)

Remove Colorizer c from the list of colorizers for this sheet.

class visidata.DisplayWrapper(value=None, *, typedval=None, text='', note=None, notecolor=None, error=None)[source]
class visidata.RowColorizer(precedence: int, coloropt: str, func=<function Colorizer.<lambda>>)[source]
class visidata.ColumnColorizer(precedence: int, coloropt: str, func=<function Colorizer.<lambda>>)[source]
class visidata.CellColorizer(precedence: int, coloropt: str, func=<function Colorizer.<lambda>>)[source]

  • precedence: use color from colorizer with the greatest precedence value.

  • coloropt: name of color option, or None.

  • func: func(sheet, col, row, value) is called for each cell as it is being rendered. Return True when coloropt should be applied to the cell. If coloropt is None, func(...) can return the relevant coloropt (or None) instead.

  • Attributes (underline, bold, reverse) combine, regardless of precedence. Only colors will override other.

  • The value passed to the Colorizer func is a DisplayWrapper, which encapsulates the entirety of a displayed cell. Use val.value to get the typed value (or None), or val.display for the displayed string.

Note

Colorizers are called for headers and separators, in addition to cells. For a header, row will be None; for a separator, col will be None. So a RowColorizer needs to include a check that row is valid, a ColumnColorizer needs to check that col is valid, and a cell colorizer needs to check both. A simple check for non-False (see Examples) is sufficient.

Examples

class DescribeSheet(ColumnsSheet):
    colorizers = [
        # colors key 'rows' on the like key columns
        RowColorizer(7, 'color_key_col', lambda s,c,r,v: r and r in r.sheet.keyCols),
    ]

class OptionsSheet(TableSheet):
    colorizers = [
        # colors cells
        CellColorizer(3, None, lambda s,c,r,v: v.value if r and c in s.columns[1:3] and r.name.startswith('color_') else None)
    ]