visidata 2.11.1__py3-none-any.whl → 3.0__py3-none-any.whl

visidata/selection.py

@@ -1,10 +1,66 @@
-from visidata import vd, Sheet, Progress, asyncthread, options, rotateRange, Fanout, undoAttrCopyFunc, copy
+from copy import copy
+from visidata import vd, Sheet, Progress, asyncthread, options, rotateRange, Fanout, undoAttrCopyFunc, RowColorizer, GuideSheet
 
 vd.option('bulk_select_clear', False, 'clear selected rows before new bulk selections', replay=True)
 vd.option('some_selected_rows', False, 'if no rows selected, if True, someSelectedRows returns all rows; if False, fails')
 
 Sheet.init('_selectedRows', dict)  # rowid(row) -> row
 
+vd.rowNoters.append(
+        lambda sheet, row: sheet.isSelected(row) and sheet.options.disp_selected_note
+)
+Sheet.colorizers.append( RowColorizer(2, 'color_selected_row', lambda s,c,r,v:
+    r is not None and s.isSelected(r))
+)
+
+class SelectionGuide(GuideSheet):
+    sheettype = Sheet
+    guide_text ='''# Selecting and filtering
+
+Some commands operate only on "selected rows".  For instance, a common command to filter is {help.commands.dup_selected}.
+
+Many g-prefixed commands are like this. For example, use {help.commands.edit_cell}, but use {help.commands.setcol_input}.  Search for "selected rows" in the [:onclick help-commands-all]commands list[/] or the [:onclick sysopen-help]manpage[/] for a full list.
+
+Rows on the **Frequency Table** or **Pivot Table** reference a group of rows from the source sheet.  Selecting a row on those sheets also selects the referenced rows on the underlying source sheet.
+
+Select and unselect rows with these commands:
+
+## One row at a time
+
+- {help.commands.select_row}
+- {help.commands.unselect_row}
+- {help.commands.stoggle_row}
+
+## All rows at the same time
+
+- {help.commands.select_rows}
+- {help.commands.unselect_rows}
+- {help.commands.stoggle_rows}
+
+## By matching patterns
+
+- {help.commands.select_col_regex}
+- {help.commands.unselect_col_regex}
+- {help.commands.select_cols_regex}
+- {help.commands.unselect_cols_regex}
+
+- {help.commands.select_equal_cell}
+- {help.commands.select_equal_row}
+
+## Select by Python expression
+
+Python expressions can use a column value by the column name, if the
+column name is a valid Python identifier (with only letters, digits, and underscores).
+
+- {help.commands.select_expr}
+- {help.commands.unselect_expr}
+
+## Options
+
+- {help.options.bulk_select_clear}
+- {help.options.some_selected_rows}
+'''
+
 @Sheet.api
 def isSelected(self, row):
     'Return True if *row* is selected.'
@@ -174,10 +230,10 @@ Sheet.addCommand('gzt', 'stoggle-after', 'toggle(rows[cursorRowIndex:])', 'toggl
 Sheet.addCommand('gzs', 'select-after', 'select(rows[cursorRowIndex:])', 'select all rows from cursor to bottom')
 Sheet.addCommand('gzu', 'unselect-after', 'unselect(rows[cursorRowIndex:])', 'unselect all rows from cursor to bottom')
 
-Sheet.addCommand('|', 'select-col-regex', 'selectByIdx(vd.searchRegex(sheet, regex=input("select regex: ", type="regex", defaultLast=True), columns="cursorCol"))', 'select rows matching regex in current column')
-Sheet.addCommand('\\', 'unselect-col-regex', 'unselectByIdx(vd.searchRegex(sheet, regex=input("unselect regex: ", type="regex", defaultLast=True), columns="cursorCol"))', 'unselect rows matching regex in current column')
-Sheet.addCommand('g|', 'select-cols-regex', 'selectByIdx(vd.searchRegex(sheet, regex=input("select regex: ", type="regex", defaultLast=True), columns="visibleCols"))', 'select rows matching regex in any visible column')
-Sheet.addCommand('g\\', 'unselect-cols-regex', 'unselectByIdx(vd.searchRegex(sheet, regex=input("unselect regex: ", type="regex", defaultLast=True), columns="visibleCols"))', 'unselect rows matching regex in any visible column')
+Sheet.addCommand('|', 'select-col-regex', 'selectByIdx(searchInputRegex("select", columns="cursorCol"))', 'select rows matching regex in current column')
+Sheet.addCommand('\\', 'unselect-col-regex', 'unselectByIdx(searchInputRegex("unselect", columns="cursorCol"))', 'unselect rows matching regex in current column')
+Sheet.addCommand('g|', 'select-cols-regex', 'selectByIdx(searchInputRegex("select", columns="visibleCols"))', 'select rows matching regex in any visible column')
+Sheet.addCommand('g\\', 'unselect-cols-regex', 'unselectByIdx(searchInputRegex("unselect", columns="visibleCols"))', 'unselect rows matching regex in any visible column')
 
 Sheet.addCommand(',', 'select-equal-cell', 'select(gatherBy(lambda r,c=cursorCol,v=cursorDisplay: c.getDisplayValue(r) == v), progress=False)', 'select rows matching current cell in current column')
 Sheet.addCommand('g,', 'select-equal-row', 'select(gatherBy(lambda r,currow=cursorRow,vcols=visibleCols: all([c.getDisplayValue(r) == c.getDisplayValue(currow) for c in vcols])), progress=False)', 'select rows matching current row in all visible columns')
@@ -189,3 +245,26 @@ Sheet.addCommand('z\\', 'unselect-expr', 'expr=inputExpr("unselect by expr: ");
 
 Sheet.addCommand(None, 'select-error-col', 'select(gatherBy(lambda r,c=cursorCol: c.isError(r)), progress=False)', 'select rows with errors in current column')
 Sheet.addCommand(None, 'select-error', 'select(gatherBy(lambda r,vcols=visibleCols: isinstance(r, TypedExceptionWrapper) or any([c.isError(r) for c in vcols])), progress=False)', 'select rows with errors in any column')
+
+vd.addMenuItems('''
+    Row > Select > current row > select-row
+    Row > Select > all rows > select-rows
+    Row > Select > from top > select-before
+    Row > Select > to bottom > select-after
+    Row > Select > by Python expr > select-expr
+    Row > Select > equal to current cell > select-equal-cell
+    Row > Select > equal to current row > select-equal-row
+    Row > Select > errors > current column > select-error-col
+    Row > Select > errors > any column > select-error
+    Row > Unselect > current row > unselect-row
+    Row > Unselect > all rows > unselect-rows
+    Row > Unselect > from top > unselect-before
+    Row > Unselect > to bottom > unselect-after
+    Row > Unselect > by Python expr > unselect-expr
+    Row > Toggle select > current row > stoggle-row
+    Row > Toggle select > all rows > stoggle-rows
+    Row > Toggle select > from top > stoggle-before
+    Row > Toggle select > to bottom > stoggle-after
+''')
+
+vd.addGuide('SelectionGuide', SelectionGuide)

visidata/settings.py

@@ -1,4 +1,5 @@
 import collections
+import functools
 import sys
 import inspect
 import argparse
@@ -16,6 +17,12 @@ class SettingsMgr(collections.OrderedDict):
         super().__init__()
         self.allobjs = {}
 
+    def __hash__(self):
+        return hash(id(self))
+
+    def __eq__(self, other):
+        return self is other
+
     def objname(self, obj):
         if isinstance(obj, str):
             v = obj
@@ -51,6 +58,7 @@ class SettingsMgr(collections.OrderedDict):
     def setdefault(self, k, v):
         return self.set(k, v, 'default')
 
+    @functools.lru_cache()
     def _mappings(self, obj):
         '''Return list of contexts in order to resolve settings. ordering is, from lowest to highest precedence:
 
@@ -65,7 +73,7 @@ class SettingsMgr(collections.OrderedDict):
         '''
         mappings = []
         if obj:
-            mappings += [self.objname(obj)]
+            mappings += [obj]
             mappings += [self.objname(cls) for cls in inspect.getmro(type(obj))]
 
         mappings += ['global', 'default']
@@ -75,7 +83,7 @@ class SettingsMgr(collections.OrderedDict):
         d = self.get(key, None)
         if d:
             for m in self._mappings(obj or vd.activeSheet):
-                v = d.get(m)
+                v = d.get(self.objname(m))
                 if v:
                     return v
 
@@ -85,6 +93,7 @@ class SettingsMgr(collections.OrderedDict):
             obj = vd.activeSheet
 
         for o in self._mappings(obj):
+            o = self.objname(o)
             for k in self.keys():
                 for o2 in self[k]:
                     if o == o2:
@@ -98,19 +107,25 @@ class SettingsMgr(collections.OrderedDict):
 
 
 class Command:
-    def __init__(self, longname, execstr, helpstr=''):
+    def __init__(self, longname, execstr, helpstr='', module='', deprecated=False):
         self.longname = longname
         self.execstr = execstr
         self.helpstr = helpstr
+        self.module = module
+        self.deprecated = deprecated
 
 
 class Option:
-    def __init__(self, name, value, helpstr=''):
+    def __init__(self, name, value, description='', module='', help='', max_help=10):
+        # description gets shows on the manpage and the optionssheet; help is shown on the sidebar while editing
         self.name = name
         self.value = value
-        self.helpstr = helpstr
+        self.helpstr = description
+        self.extrahelp = help
         self.replayable = False
         self.sheettype = BaseSheet
+        self.module = module
+        self.max_help = max_help
 
     def __str__(self):
         return str(self.value)
@@ -140,10 +155,12 @@ class OptionsObject:
             self._cache[(k, obj or vd.activeSheet)] = opt
         return opt
 
-    def _set(self, k, v, obj=None, helpstr=''):
-        opt = self._get(k) or Option(k, v, '')
+    def _set(self, k, v, obj=None, helpstr='', module=None):
+        k, v = vd._resolve_optalias(k, v)  # to set deprecated and abbreviated options
+
+        opt = self._get(k) or Option(k, v, '', module)
         self._cache.clear()  # invalidate entire cache on any change
-        return self._opts.set(k, Option(k, v, helpstr), obj)
+        return self._opts.set(k, Option(k, v, opt.helpstr or helpstr, opt.module or module), obj)
 
     def is_set(self, k, obj=None):
         d = self._opts.get(k, None)
@@ -176,6 +193,7 @@ class OptionsObject:
     def set(self, optname, value, obj='global'):
         "Override *value* for *optname* in the options context, or in the *obj* context if given."
         opt = self._get(optname)
+        module = None  # keep default
         if opt:
             curval = opt.value
             t = type(curval)
@@ -193,30 +211,44 @@ class OptionsObject:
             if curval != value and self._get(optname, 'default').replayable:
                 if obj != 'default' and type(obj) is not type:  # default and class options set on init aren't recorded
                     if vd.cmdlog:
-                        objname = self._opts.objname(obj)
-                        vd.cmdlog.addRow(vd.cmdlog.newRow(sheet=objname, row=optname,
-                                    keystrokes='', input=str(value),
-                                    longname='set-option', undofuncs=[]))
+                        self.add_option_to_cmdlogs(obj, optname, value, 'set-option')
         else:
             curval = None
             vd.warning('setting unknown option %s' % optname)
+            module = 'unknown'
 
-        return self._set(optname, value, obj)
+        return self._set(optname, value, obj, module=module)
 
     def unset(self, optname, obj=None):
         'Remove setting value for given context.'
         v = self._opts.unset(optname, obj)
         opt = self._get(optname)
         if vd.cmdlog and opt and opt.replayable:
-            objname = self._opts.objname(obj)
-            vd.cmdlog.addRow(vd.cmdlog.newRow(sheet=objname, row=optname,
-                            keystrokes='', input='',
-                            longname='unset-option'))
+            self.add_option_to_cmdlogs(obj, optname, value='', longname='unset-option')
         self._cache.clear()  # invalidate entire cache on any change
         return v
 
-    def setdefault(self, optname, value, helpstr):
-        return self._set(optname, value, 'default', helpstr=helpstr)
+    def add_option_to_cmdlogs(self, obj, optname, value='', longname='set-option'):
+        'Records option-set on cmdlogs'
+        objname = self._opts.objname(obj)
+        # all options are recorded on global cmdlog
+        vd.cmdlog.addRow(vd.cmdlog.newRow(sheet=objname, row=optname,
+                    keystrokes='', input=str(value),
+                    longname=longname, undofuncs=[]))
+        # global options are recorded on all cmdlog_sheet's
+        if obj == 'global':
+            for vs in vd.sheets:
+                vs.cmdlog_sheet.addRow(vd.cmdlog.newRow(sheet=objname, row=optname,
+                            keystrokes='', input=str(value),
+                            longname=longname, undofuncs=[]))
+        # sheet-specific options are recorded on that sheet
+        elif isinstance(obj, BaseSheet):
+            obj.cmdlog_sheet.addRow(vd.cmdlog.newRow(sheet=objname, row=optname,
+                        keystrokes='', input=str(value),
+                        longname=longname, undofuncs=[]))
+
+    def setdefault(self, optname, value, helpstr, module):
+        return self._set(optname, value, 'default', helpstr=helpstr, module=module)
 
     def getall(self, prefix=''):
         'Return dictionary of all options beginning with `prefix` (with `prefix` removed from the name).'
@@ -247,10 +279,27 @@ vd.bindkeys = SettingsMgr()
 vd._options = SettingsMgr()
 
 vd.options = vd.OptionsObject(vd._options)  # global option settings
+vd.option_aliases = {}
 
 
 @VisiData.api
-def option(vd, name, default, helpstr, replay=False, sheettype=BaseSheet):
+def optalias(vd, altname, optname, val=None):
+    'Create an alias `altname` for option `optname`, setting the value to a particular `val` (if not None).'
+    vd.option_aliases[altname] = (optname, val)
+
+
+@VisiData.api
+def _resolve_optalias(vd, optname, optval):
+    while optname in vd.option_aliases:
+        optname, v = vd.option_aliases.get(optname)
+        if v is not None:  # value might be given
+            optval = v
+
+    return optname, optval
+
+
+@VisiData.api
+def option(vd, name, default, description, replay=False, sheettype=BaseSheet, help:str='', max_help=10):
     '''Declare a new option.
 
    - `name`: name of option
@@ -259,12 +308,21 @@ def option(vd, name, default, helpstr, replay=False, sheettype=BaseSheet):
    - `replay`: ``True`` if changes to the option should be stored in the **Command Log**
    - `sheettype`: ``None`` if the option is not sheet-specific, to make it global on CLI
     '''
-    opt = vd.options.setdefault(name, default, helpstr)
+    opt = vd.options.setdefault(name, default, description, vd.importingModule)
     opt.replayable = replay
     opt.sheettype=sheettype
+    opt.extrahelp = help
+    opt.max_help = max_help
     return opt
 
 
+@VisiData.api
+def theme_option(vd, name, *args, **kwargs):
+    if name.startswith('color_'):
+        kwargs.setdefault('help', vd.help_color)
+    return vd.option(name, *args, **kwargs, max_help=-1)
+
+
 @BaseSheet.class_api
 @classmethod
 def addCommand(cls, keystrokes, longname, execstr, helpstr='', **kwargs):
@@ -275,9 +333,9 @@ def addCommand(cls, keystrokes, longname, execstr, helpstr='', **kwargs):
     - *execstr*: Python statement to pass to `exec()`'ed when the command is executed.
     - *helpstr*: help string shown in the **Commands Sheet**.
     '''
-    vd.commands.set(longname, Command(longname, execstr, helpstr=helpstr, **kwargs), cls)
+    vd.commands.set(longname, Command(longname, execstr, helpstr=helpstr, module=vd.importingModule, **kwargs), cls)
     if keystrokes:
-        vd.bindkeys.set(vd.prettykeys(keystrokes), longname, cls)
+        vd.bindkeys.set(vd.prettykeys(keystrokes.replace(' ', '')), longname, cls)
     return longname
 
 def _command(cls, binding, longname, helpstr, **kwargs):
@@ -333,9 +391,12 @@ def loadConfigFile(vd, fn='', _globals=None):
         try:
             with open(p) as fd:
                 code = compile(fd.read(), str(p), 'exec')
+            vd.importingModule = 'visidatarc'
             exec(code, _globals)
         except Exception as e:
             vd.exceptionCaught(e)
+        finally:
+            vd.importingModule = None
 
     vd.addGlobals(_globals)
 
@@ -385,13 +446,15 @@ def loadConfigAndPlugins(vd, args=AttrDict()):
 
         for ep in eps_visidata:
             try:
+                vd.importingModule = ep.name
                 plug = ep.load()
                 sys.modules[f'visidata.plugins.{ep.name}'] = plug
                 vd.debug(f'Plugin {ep.name} loaded')
             except Exception as e:
                 vd.warning(f'Plugin {ep.name} failed to load')
                 vd.exceptionCaught(e)
-                continue
+            finally:
+                vd.importingModule = None
 
         # import plugins from .visidata/plugins before .visidatarc, so plugin options can be overridden
         for modname in (args.imports or vd.options.imports or '').split():
@@ -410,10 +473,84 @@ def loadConfigAndPlugins(vd, args=AttrDict()):
         vd.loadConfigFile(vd.options.config, vd.getGlobals())
 
 
+@VisiData.api
+def importModule(vd, pkgname):
+    'Import the given *pkgname*, setting vd.importingModule to *pkgname* before import and resetting to None after.'
+    modparts = pkgname.split('.')
+    vd.importingModule = modparts[-1]
+    r = importlib.import_module(pkgname)
+    vd.importingModule = None
+    vd.importedModules.append(r)
+    return r
+
+
+@VisiData.api
+def importSubmodules(vd, pkgname):
+    'Import all files below the given *pkgname*'
+    import pkgutil
+    import os.path
+
+    m = vd.importModule(pkgname)
+    for module in pkgutil.walk_packages(m.__path__):
+        vd.importModule(pkgname + '.' + module.name)
+
+
+@VisiData.api
+def importStar(vd, pkgname):
+    'Add all symbols from *pkgname* into visidata globals.'
+    import pkgutil
+    import os.path
+
+    m = vd.importModule(pkgname)
+    vd.addGlobals({pkgname:m})
+    vd.addGlobals(m.__dict__)
+
+
+@VisiData.api
+def importExternal(vd, modname, pipmodname=''):
+    pipmodname = pipmodname or modname
+    try:
+        m = importlib.import_module(modname)
+        vd.addGlobals({modname:m})
+        return m
+    except ModuleNotFoundError as e:
+        vd.fail(f'External package "{modname}" not installed; run: pip install {pipmodname}')
+
+
+@VisiData.api
+def requireOptions(vd, *args, help=''):
+    '''Prompt user to input values for option names in *args* if current values
+    are non-false.  Offer to persist the values to visidatarc.'''
+
+    optvals = {}
+    for optname in args:
+        if not getattr(vd.options, optname):
+            if help:
+                vd.status(help)
+            v = vd.input(f'{optname}: ', record=False, display='password' not in optname)
+            optvals[optname] = v
+
+    vd.setPersistentOptions(**optvals)
+
+
+@VisiData.api
+def setPersistentOptions(vd, **kwargs):
+    '''Set options from *kwargs* and offer to save them to visidatarc.'''
+    for optname, optval in kwargs.items():
+        setattr(vd.options, optname, optval)
+
+    optnames = ' '.join(kwargs.keys())
+    yn = vd.input(f'Save {len(kwargs)} options ({optnames}) to {vd.options.config}? ', record=False)[0:1]
+
+    if yn and yn in 'Yy':
+        with open(str(visidata.Path(vd.options.config)), mode='a') as fp:
+            for optname, optval in kwargs.items():
+                fp.write(f'options.{optname}={repr(optval)}\n')
+
+
 vd.option('visidata_dir', '~/.visidata/', 'directory to load and store additional files', sheettype=None)
 
 BaseSheet.bindkey('^M', '^J')  # for windows ENTER
-BaseSheet.addCommand('gO', 'open-config', 'vd.push(open_txt(Path(options.config)))', 'open options.config as text sheet')
 
 vd.addGlobals({
     'options': vd.options,  # legacy