pmemstat 2.3.29__tar.gz → 3.0.2__tar.gz

pmemstat-2.3.29/README.md → pmemstat-3.0.2/PKG-INFO

@@ -1,3 +1,20 @@
+Metadata-Version: 2.4
+Name: pmemstat
+Version: 3.0.2
+Summary: Report Proportional Memory on Linux
+Keywords: proportional memory,RAM,htop,top,monitor
+Author-email: Joe Defen <joedef@duck.com>
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+License-File: LICENSE.txt
+Requires-Dist: psutil > 5.9
+Requires-Dist: console-window >= 1.0.0
+Project-URL: Bug Tracker, https://github.com/joedefen/pmemstat/issues
+Project-URL: Homepage, https://github.com/joedefen/pmemstat
+
 > **Quick Start**: from the CLI
 > * **If `python3 -V` shows v3.11 or later, install with `pipx`**:
 >   * install `pipx` per your distro's guidance
@@ -88,7 +105,20 @@ Explanation of some options and arguments:
 
 
 ## Example Usage with Explanation of Output
-![pmemstat](https://github.com/joedefen/pmemstat/blob/main/images/pmemstat.png?raw=true)
+```
+20:49:12 Tot=7.6G Used=6.2G Avail=1.4G Oth=0 Sh+Tmp=477.7M PIDs=174
+     2.4%/ker MajF/s=2  zRAM=813.2M CR=4.3 eTot:16.8G eUsed:8.8G eAvail:8.0G
+ cpu_pct   pswap   other    data  ptotal   key/info (exe by mem)
+    60.8   2,535     593   3,988   7,116 T 174x --TOTALS in MB --
+───────────────────────────────────────────────────────────────────────────────
+     5.9   1,366      90   2,110   3,567   24x browser
+    16.6      89     117     822   1,028   9x code
+     5.9     270      32     291     593   1x firefox
+     1.6      95      68     335     497   6x exe
+     2.4     150      66      94     310   6x brave
+    16.0      52      73     152     277   3x VQ6B1EUZqoCU04zoRU
+     0.1      39      19      13      70   2x konsole
+```
 
 In the default refreshed window loop, we see
 * a **leader line** with:
@@ -104,14 +134,17 @@ In the default refreshed window loop, we see
     * how many PIDs are contributing to the report vs the total number of PIDs excluding kernel threads
 * a **second leader line for zRAM** only if zRAM is active with:
     * percent cpu consumed by kernel processes (not normalized ... if there 4 CPUs, then the total CPU can 400%). This is important because, with zRAM, this often is mostly the swap process.
+    * **MajF/s** - the number of "major" page faults per second.
+      * 100+/s is high/worrisome.	Indicates significant memory pressure and heavy swapping or repeated large file access. System thrashing/slowdown is likely noticeable slow response.
+      * 1000+/s is extreme.	Indicates severe memory overcommitment, likely with processes constantly fighting for RAM, or an application aggressively accessing disk-mapped memory.
     * **zRAM** - the amount of "Used" RAM that is storing zRAM data
-    * **eTot** - the effective Total RAM and the percent of "Tot" RAM (which would typically be above 100%). The bigger **zRAM**, the more accurate this number.
-    * **eUsed** - the effective Used RAM and percent of "Tot" RAM.
-    * **eAvail** - the effective Available RAM and percent of "Tot" RAM.
+    * **eTot** - the effective Total RAM ... the bigger **zRAM**, the more accurate this number
+    * **eUsed** - the effective Used RAM
+    * **eAvail** - the effective Available RAM
 * a **header line with the reported fields** including:
     * **cpu** - percent CPU (again not normalized to 100%)
     * **pswap** - proportional use of swap (per smaps_rollup)
-    * **other** - partly sums these categories (shown by the key, `o`):
+    * **other** - partly sums these categories (shown by the key, `o`)
       * **shSYSV** - proportional use of System V shared memory (per smaps)
       * **shOth** - proportional use of other shared memory (per smaps)
       * **stack** - exclusive use of stack memory per smaps
@@ -182,4 +215,4 @@ If the `pipx` install is not acceptable, choose the best way to install:
 ```
         PIP_BREAK_SYSTEM_PACKAGES=1 sudo python -m pip install pmemstat
         # to uninstall: sudo python -m pip uninstall pmemstat
-```
+```

pmemstat-2.3.29/PKG-INFO → pmemstat-3.0.2/README.md

@@ -1,19 +1,3 @@
-Metadata-Version: 2.4
-Name: pmemstat
-Version: 2.3.29
-Summary: Report Proportional Memory on Linux
-Keywords: proportional memory,RAM,htop,top,monitor
-Author-email: Joe Defen <joedef@duck.com>
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: POSIX :: Linux
-License-File: LICENSE.txt
-Requires-Dist: psutil>5.9
-Project-URL: Bug Tracker, https://github.com/joedefen/pmemstat/issues
-Project-URL: Homepage, https://github.com/joedefen/pmemstat
-
 > **Quick Start**: from the CLI
 > * **If `python3 -V` shows v3.11 or later, install with `pipx`**:
 >   * install `pipx` per your distro's guidance
@@ -104,7 +88,20 @@ Explanation of some options and arguments:
 
 
 ## Example Usage with Explanation of Output
-![pmemstat](https://github.com/joedefen/pmemstat/blob/main/images/pmemstat.png?raw=true)
+```
+20:49:12 Tot=7.6G Used=6.2G Avail=1.4G Oth=0 Sh+Tmp=477.7M PIDs=174
+     2.4%/ker MajF/s=2  zRAM=813.2M CR=4.3 eTot:16.8G eUsed:8.8G eAvail:8.0G
+ cpu_pct   pswap   other    data  ptotal   key/info (exe by mem)
+    60.8   2,535     593   3,988   7,116 T 174x --TOTALS in MB --
+───────────────────────────────────────────────────────────────────────────────
+     5.9   1,366      90   2,110   3,567   24x browser
+    16.6      89     117     822   1,028   9x code
+     5.9     270      32     291     593   1x firefox
+     1.6      95      68     335     497   6x exe
+     2.4     150      66      94     310   6x brave
+    16.0      52      73     152     277   3x VQ6B1EUZqoCU04zoRU
+     0.1      39      19      13      70   2x konsole
+```
 
 In the default refreshed window loop, we see
 * a **leader line** with:
@@ -120,14 +117,17 @@ In the default refreshed window loop, we see
     * how many PIDs are contributing to the report vs the total number of PIDs excluding kernel threads
 * a **second leader line for zRAM** only if zRAM is active with:
     * percent cpu consumed by kernel processes (not normalized ... if there 4 CPUs, then the total CPU can 400%). This is important because, with zRAM, this often is mostly the swap process.
+    * **MajF/s** - the number of "major" page faults per second.
+      * 100+/s is high/worrisome.	Indicates significant memory pressure and heavy swapping or repeated large file access. System thrashing/slowdown is likely noticeable slow response.
+      * 1000+/s is extreme.	Indicates severe memory overcommitment, likely with processes constantly fighting for RAM, or an application aggressively accessing disk-mapped memory.
     * **zRAM** - the amount of "Used" RAM that is storing zRAM data
-    * **eTot** - the effective Total RAM and the percent of "Tot" RAM (which would typically be above 100%). The bigger **zRAM**, the more accurate this number.
-    * **eUsed** - the effective Used RAM and percent of "Tot" RAM.
-    * **eAvail** - the effective Available RAM and percent of "Tot" RAM.
+    * **eTot** - the effective Total RAM ... the bigger **zRAM**, the more accurate this number
+    * **eUsed** - the effective Used RAM
+    * **eAvail** - the effective Available RAM
 * a **header line with the reported fields** including:
     * **cpu** - percent CPU (again not normalized to 100%)
     * **pswap** - proportional use of swap (per smaps_rollup)
-    * **other** - partly sums these categories (shown by the key, `o`):
+    * **other** - partly sums these categories (shown by the key, `o`)
       * **shSYSV** - proportional use of System V shared memory (per smaps)
       * **shOth** - proportional use of other shared memory (per smaps)
       * **stack** - exclusive use of stack memory per smaps
@@ -198,4 +198,4 @@ If the `pipx` install is not acceptable, choose the best way to install:
 ```
         PIP_BREAK_SYSTEM_PACKAGES=1 sudo python -m pip install pmemstat
         # to uninstall: sudo python -m pip uninstall pmemstat
-```
+```

pmemstat-3.0.2/TODO.md

@@ -0,0 +1,88 @@
+Summary of TODOs:
+* Drop the percents from the zRAM line
+* Add compression ratio (CR)
+* Add Major page faults /s  (MajF:200/s)
+* Document the new features (some insight below)
+
+----
+
+That's an insightful follow-up. You are absolutely correct to be cautious about adding a metric that is difficult to interpret, as it can confuse the user rather than help.
+
+1. Ease of Getting Page Faults
+
+Yes, page fault counts are relatively easy to get in Linux. They are tracked by the kernel.
+
+The most relevant location for a tool like memstat (which is likely capturing data periodically) is often the /proc/vmstat file, which contains system-wide metrics like pgfault (total), pgmajfault (major), and pgminfault (minor).
+
+    Minor Faults (pgminfault): These are extremely common and usually cheap. They occur when a page is accessed for the first time or is shared/already in RAM but needs its entry updated in the process's page table. They are fast and generally not a primary concern for performance.
+
+Major Faults (pgmajfault): These are the ones you should focus on. A major fault happens when the requested page is not in physical RAM and must be read from a backing store, like the disk (or a swap device, which, in your case, is the zRAM device). These incur significant latency due to I/O and are a strong indicator of memory pressure and system slowdown.
+
+Recommendation: If you add page faults, you should only report the Major Faults per second (MajFaults/s). This is the key metric that directly correlates with the I/O cost you want to diagnose alongside zRAM activity.
+
+2. Guidance: When is "Bigger" Bad?
+
+You're looking for absolute thresholds, and while there's no single universally accepted number (it depends on the speed of your I/O and CPU), here is the common guidance for Major Page Faults per second:
+Major Faults/s Range	Interpretation	System Impact
+* 0 - ~10 per second	Normal/Low	Expected during application startup or initial file access. No performance concern.
+* ~10 - ~100 per second	Moderate	Suggests consistent file access or some mild memory pressure. Could cause minor, noticeable latency on disk-bound systems.
+* 100+ per second	High/Worry	Indicates significant memory pressure and heavy swapping or repeated large file access. This is where system thrashing/slowdown is noticeable. On a busy desktop, a sustained rate here means the user is likely complaining about slow response.
+* 1000+ per second	Extreme	Indicates severe memory overcommitment, likely with processes constantly fighting for RAM, or an application aggressively accessing disk-mapped memory.
+
+Guidance: For your tool, the goal is to show the user they are experiencing memory thrashing (when the system is spending more time swapping than doing work). A sustained MajFaults/s of over 100 is a strong indication of this, especially if it coincides with high kernel CPU usage from zRAM compression/decompression.
+
+Final Revised Snippet Example
+
+Focusing on the critical Major Page Faults and the simplified CR:
+```
+15:02:03 Tot=7.6G Used=6.2G Avail=1.4G Oth=0 Sh+Tmp=983.8M PIDs=166
+      1.9/ker zRAM=612.6M CR:2.7 MajF:12/s eTot:16.5G eUsed:7.9G eAvail:8.6G
+ cpu_pct   pswap   other    data  ptotal   key/info (exe by mem)
+    27.1   1,892     680   3,637   6,210 T 166x --TOTALS in MB --
+────────────────────────────────────────────────────────────────────────────────────────────
+... process list ...
+```
+This line is powerful: it shows zRAM is working (CR:2.7), but also shows the direct performance cost (MajF:12/s).
+
+Understanding how to measure and interpret page faults is key to diagnosing memory-related performance issues.
+
+If you are interested in a deeper technical dive into the Linux kernel's page fault mechanism, you can check out Faster & Fewer Page Faults: Kernel Recipes 2023.
+
+
+
+
+
+Your analysis of the process rollup is spot on. For modern applications like browsers (Chrome, Firefox, Edge, etc.), IDEs (VS Code), and even certain large applications (like Electron or Java apps), reporting memory usage per individual PID is misleading. The user wants to know, "How much memory is **Firefox** using?" not "How much memory are its 25 sub-processes using?"
+
+### Advertising Strategy: The Two Pillars
+
+When you draft your announcement, you should clearly highlight these two pillars of `memstat`'s superior diagnostic capability:
+
+1.  **The Process Problem Solved (Rollup/Grouping):**
+
+      * **The Problem:** Standard tools (`top`, `ps`) make modern apps (browsers, IDEs, etc.) look innocent by splitting their memory across dozens of processes.
+      * **The `memstat` Solution:** `memstat` automatically aggregates related processes (based on the executable name, command line, or other heuristics) and presents a single, honest line item for the **total memory, swap, and CPU** used by the entire application group. This instantly reveals the true memory hogs.
+      * *Example to highlight:* "See the true cost of your 50 open browser tabs with a single, clear line."
+
+2.  **The Memory Ceiling Problem Solved (zRAM/Effective Memory):**
+
+      * **The Problem:** When zRAM is active, system monitoring tools report only physical RAM usage, failing to show the massive, hidden memory capacity provided by compression.
+      * **The `memstat` Solution:** The new output line displays the **Estimated Total (`eTot`), Used (`eUsed`), and Available (`eAvail`)** memory by applying the real-time **Compression Ratio (`CR:X.X`)** of your zRAM swap device. You instantly know your system's *effective* memory ceiling and available headroom.
+      * *Example to highlight:* "Don't trust `free`\! If you run zRAM, `memstat` is the only tool that shows you your **true $16.5\text{G}$ effective RAM** and how much is left."
+
+### Revised Snippet (The Final Polish)
+
+This combines all the best suggestions into a powerful, concise output:
+
+```
+15:02:03 Tot=7.6G Used=6.2G Avail=1.4G Oth=0 Sh+Tmp=983.8M PIDs=166
+      1.9/ker zRAM=612.6M CR:2.7 MajF:12/s eTot:16.5G eUsed:7.9G eAvail:8.6G
+ cpu_pct   pswap   other    data  ptotal   key/info (exe by mem)
+    27.1   1,892     680   3,637   6,210 T 166x --TOTALS in MB --
+────────────────────────────────────────────────────────────────────────────────────────────
+      1.0     967     90    2,244   3,300   21x browser <--- Process Rollup Highlight!
+      2.1     220     45      341     605    1x firefox
+...
+```
+
+This output is information-dense, highly diagnostic, and showcases two unique, valuable features that directly address major pain points in Linux performance monitoring. Good luck with the release\!

{pmemstat-2.3.29 → pmemstat-3.0.2}/pmemstat/main.py

@@ -50,7 +50,7 @@ import curses
 from types import SimpleNamespace
 from io import StringIO
 from datetime import datetime, timedelta
-from pmemstat.Window import Window, OptionSpinner
+from console_window import ConsoleWindow, OptionSpinner
 from pmemstat.KillThem import KillThem
 from pmemstat.CpuSmooth import CpuSmooth, SysStat
 
@@ -105,14 +105,15 @@ class ZramProjector:
         self.e_avail = 0
         self.e_used = 0
         self.e_max_used = 0
+        self.ratio = 0.0
         self.limit_pct = 80
         self.devs = {}
         self.DB = False
 
-    def human_pct(self, number):
+    def human_pct(self, number, with_pct=False):
         """ Return the number in human form and as pct total memory. """
         rv = human(number)
-        if number > 0 and self.meminfo.MemTotal > 0:
+        if with_pct and number > 0 and self.meminfo.MemTotal > 0:
             fraction = number/self.meminfo.MemTotal
             pct = int(round(100*fraction))
             rv += f'/{pct}%'
@@ -187,10 +188,10 @@ class ZramProjector:
         self.meminfo.MemZram = stats.mem_used_total
 
         e_used = meminfo.MemUsed - stats.mem_used_total + stats.orig_data_size
-        ratio = None
+        ratio, self.ratio = None, 0.0
         if e_used <= self.e_used: # zram hurts. assume not enuf data to project
             e_used = self.e_used
-            ratio = 3.5 # wild guess for projection
+            self.ratio = ratio = 3.5 # wild guess for projection
             # if self.DB: dump_effective(ns, '(unchg)')
             # return ns
         self.e_used = e_used
@@ -200,7 +201,7 @@ class ZramProjector:
             limit_pct = min(1.0, limit_pct, stats_limit_pct)
             # projected amount of orig used memory that fits in limit
         if ratio is None: # hopefully about 4 ;-)
-            ratio = stats.orig_data_size / stats.mem_used_total
+            self.ratio = ratio = stats.orig_data_size / stats.mem_used_total
         e_max_used = ratio * meminfo.MemTotal * limit_pct/100
             # now limit by disksize
         e_max_used = min(e_max_used, stats.disksize)
@@ -594,6 +595,7 @@ class PmemStat:
         self.kernel_prcs = []
         self.groups = {} # indexed by group key (e.g., cmd)
         self.window = None
+        self.vmstat = None
         self.spin = OptionSpinner()
         self.number = 0  # line number for opts.numbers
         self.units, self.divisor, self.fwidth = 0, 0, 0
@@ -844,6 +846,45 @@ class PmemStat:
         assert not keys, f'ALERT: cannot get vitals ({keys}) from {meminfofile}'
         return meminfoKB
 
+    def get_vmstat(self):
+        def make_ns(now):
+            ns = SimpleNamespace()
+            ns.base_time = now
+            ns.base_value = 0
+            ns.last_time = now
+            ns.last_value = 0
+            ns.rate = 0
+            return ns
+
+        """Get most vital stats from /proc/vmstat'"""
+        infofile = '/proc/vmstat'
+        now = time.monotonic()
+        if not self.vmstat:
+            self.vmstat = {'pgmajfault': make_ns(now)}
+        info = self.vmstat
+        keys = list(info.keys())
+
+        with open(infofile, encoding='utf-8') as fileh:
+            for line in fileh:
+                match = re.match(r'^([^\s]+)\s+(\d+)$', line)
+                if not match:
+                    continue
+                key, value = match.group(1), int(match.group(2))
+                if key not in keys:
+                    continue
+                ns = info[key]
+                ns.base_time, ns.base_value = ns.last_time, ns.last_value
+                ns.last_time, ns.last_value = now, value
+                ns.rate = 0
+                if ns.last_time > ns.base_time:
+                    ns.rate = int(round((ns.last_value - ns.base_value)
+                            / (ns.last_time - ns.base_time)))
+                keys.remove(key)
+                if not keys:
+                    break
+        assert not keys, f'ALERT: cannot get vitals ({keys}) from {infofile}'
+        return self.vmstat
+
     def loop(self, now, is_first, regroup=False):
         """one loop thru all pids"""
         # pylint: disable=too-many-branches
@@ -853,6 +894,7 @@ class PmemStat:
 
         def pr_top_of_report(appKB):
             nonlocal self, meminfoKB, wanted_prcs, total_user_pids, kernel_cpu
+            nonlocal major_fault_rate
             windowed = bool(self.window)
             resume = False
             # print timestamp of report
@@ -889,13 +931,15 @@ class PmemStat:
                 resume = False
                 proj = self.zram_projector
                 if self.opts.cpu:
-                    leader = f'{kernel_cpu:8.1f}/ker '
+                    leader = f'{kernel_cpu:8.1f}%/ker '
                     self.emit(leader, to_head=True, resume=resume)
                     resume = True
+                self.emit(f'MajF/s={major_fault_rate} ', to_head=True, resume=resume)
+                resume = True
                 self.emit(f' zRAM={human(self.zram_projector.meminfo.MemZram)}',
                           to_head=True, attr=curses.A_BOLD, resume=resume)
-                resume = True
                 leader = ''
+                leader += f' CR={proj.ratio:.1f}'
                 leader += f' eTot:{proj.human_pct(proj.e_max_used)}'
                 leader += f' eUsed:{proj.human_pct(proj.e_used)}'
                 leader += f' eAvail:{proj.human_pct(proj.e_avail)}'
@@ -903,7 +947,7 @@ class PmemStat:
                 self.emit(leader, to_head=True, resume=resume)
             elif self.opts.cpu: # second line if reporting cpu
                 resume = False
-                leader = f'{kernel_cpu:8.1f}/ker'
+                leader = f'{kernel_cpu:8.1f}%/ker'
                 sort_kernel_prcs()
                 for prc in self.kernel_prcs[0:2]:
                     nickname = prc.cpu.get_nickname()
@@ -913,6 +957,8 @@ class PmemStat:
             # pylint: disable=too-many-branches
         self.loop_num += 1
         meminfoKB = self.get_meminfo()
+        vmstat = self.get_vmstat()
+        major_fault_rate = vmstat['pgmajfault'].rate
         self.zram_projector.compute_effective(meminfoKB)
         total_user_pids = 0
         total_kernel_pids = 0
@@ -1154,7 +1200,7 @@ class PmemStat:
                           prompt='Set search string, then Enter', obj=self.opts)
 
         keys_we_handle =  [ord('K'), curses.KEY_ENTER, 10] + list(self.spin.keys)
-        self.window = Window(head_line=True, keys=keys_we_handle)
+        self.window = ConsoleWindow(head_line=True, keys=keys_we_handle)
         is_first = True
         was_groupby, regroup = self.opts.groupby, True
         was_others = self.opts.others
@@ -1285,7 +1331,7 @@ def run():
     except KeyboardInterrupt:
         pass
     except Exception as exce:
-        Window.stop_curses()
+        ConsoleWindow.stop_curses()
         print("exception:", str(exce))
         print(traceback.format_exc())
 

{pmemstat-2.3.29 → pmemstat-3.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "flit_core.buildapi"
 
 [project]
 name = "pmemstat"
-version = "2.3.29"
+version = "3.0.2"
 description = "Report Proportional Memory on Linux"
 authors = [
     {name = "Joe Defen", email = "joedef@duck.com"},
@@ -19,7 +19,8 @@ classifiers = [
     "Operating System :: POSIX :: Linux"
 ]
 dependencies = [
-    'psutil>5.9',
+    'psutil > 5.9',
+    'console-window >= 1.0.0',
 ]
 
 [project.urls]

pmemstat-2.3.29/deploy

@@ -1,8 +0,0 @@
-#!/bin/bash
-script_dir=$(dirname "$0")
-set -ex
-cd ${script_dir}
-rm -rf ./dist
-python3 -m pip install build --break-system-packages
-python3 -m build
-pip install -e . --break-system-packages

pmemstat-2.3.29/pmemstat/Window.py

@@ -1,647 +0,0 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""
-Custom Wrapper for python curses.
-"""
-# pylint: disable=too-many-instance-attributes,too-many-arguments
-# pylint: disable=invalid-name,broad-except,too-many-branches
-
-import traceback
-import atexit
-import time
-import curses
-import textwrap
-from types import SimpleNamespace
-from curses.textpad import rectangle, Textbox
-dump_str = None
-
-class OptionSpinner:
-    """Manage a bunch of options where the value is rotate thru
-    a fixed set of values pressing a key."""
-    def __init__(self):
-        """Give the object with the attribute to change its
-        value (e.g., options from argparse or "self" from
-        the object managing the window).
-
-        And array of specs like:
-            ['a - allow auto suggestions', 'allow_auto', True, False],
-            ['/ - filter pattern', 'filter_str', self.filter_str],
-        A spec can have a trailing None + more comments shown after
-        the value.
-        """
-        self.options, self.keys = [], []
-        self.margin = 4 # + actual width (1st column right pos)
-        self.align = self.margin # + actual width (1st column right pos)
-        self.default_obj = SimpleNamespace() # if not given one
-        self.attr_to_option = {} # given an attribute, find its option ns
-        self.key_to_option = {} # given key, options namespace
-        self.keys = set()
-
-    @staticmethod
-    def _make_option_ns():
-        return SimpleNamespace(
-            keys=[],
-            descr='',
-            obj=None,
-            attr='',
-            vals=None,
-            prompt=None,
-            comments=[],
-        )
-
-    def get_value(self, attr, coerce=False):
-        """Get the value of the given attribute."""
-        ns = self.attr_to_option.get(attr, None)
-        obj = ns.obj if ns else None
-        value = getattr(obj, attr, None) if obj else None
-        if value is None and obj and coerce:
-            if ns.vals:
-                if value not in ns.vals:
-                    value = ns.vals[0]
-                    setattr(obj, attr, value)
-            else:
-                if value is None:
-                    value = ''
-                    setattr(ns.obj, ns.attr, '')
-        return value
-
-    def _register(self, ns):
-        """ Create the mappings needed"""
-        assert ns.attr not in self.attr_to_option
-        self.attr_to_option[ns.attr] = ns
-        for key in ns.keys:
-            assert key not in self.key_to_option, f'key ({chr(key)}, {key}) already used'
-            self.key_to_option[key] = ns
-            self.keys.add(key)
-        self.options.append(ns)
-        self.align = max(self.align, self.margin+len(ns.descr))
-        self.get_value(ns.attr, coerce=True)
-
-    def add(self, obj, specs):
-        """ Compatibility Method."""
-        for spec in specs:
-            ns = self._make_option_ns()
-            ns.descr = spec[0]
-            ns.obj = obj
-            ns.attr = spec[1]
-            ns.vals=spec[2:]
-            if None in ns.vals:
-                idx = ns.vals.index(None)
-                ns.vals = ns.vals[:idx]
-                ns.comments = ns.vals[idx+1:]
-            ns.keys = [ord(ns.descr[0])]
-            self._register(ns)
-
-    def add_key(self, attr, descr, obj=None, vals=None, prompt=None, keys=None, comments=None):
-        """ Standard method"""
-        ns = self._make_option_ns()
-        if keys:
-            ns.keys = list(keys) if isinstance(keys, (list, tuple, set)) else [keys]
-        else:
-            ns.keys = [ord(descr[0])]
-        if comments is None:
-            ns.comments = []
-        else:
-            ns.comments = list(comments) if isinstance(keys, (list, tuple)) else [comments]
-        ns.descr = descr
-        ns.attr = attr
-        ns.obj = obj if obj else self.default_obj
-        ns.vals, ns.prompt = vals, prompt
-        assert bool(ns.vals) ^ bool(ns.prompt)
-        self._register(ns)
-
-    def show_help_nav_keys(self, win):
-        """ Get/present standard verbiage for the navigation keys"""
-        for line in Window.get_nav_keys_blurb().splitlines():
-            if line:
-                win.add_header(line)
-
-    def show_help_body(self, win):
-        """ Write the help page section."""
-        win.add_body('Type keys to alter choice:', curses.A_UNDERLINE)
-
-        for ns in self.options:
-            # get / coerce the current value
-            value = self.get_value(ns.attr)
-            assert value is not None, f'cannot get value of {repr(ns.attr)}'
-            choices = ns.vals if ns.vals else [value]
-
-            win.add_body(f'{ns.descr:>{self.align}}: ')
-
-            for choice in choices:
-                shown = f'{choice}'
-                if isinstance(choice, bool):
-                    shown = "ON" if choice else "off"
-                win.add_body(' ', resume=True)
-                win.add_body(shown, resume=True,
-                    attr=curses.A_REVERSE if choice == value else None)
-
-            for comment in ns.comments:
-                win.add_body(f'{"":>{self.align}}:  {comment}')
-
-    def do_key(self, key, win):
-        """Do the automated processing of a key."""
-        ns = self.key_to_option.get(key, None)
-        if ns is None:
-            return None
-        value = self.get_value(ns.attr)
-        if ns.vals:
-            idx = ns.vals.index(value) if value in ns.vals else -1
-            value = ns.vals[(idx+1) % len(ns.vals)] # choose next
-        else:
-            value = win.answer(prompt=ns.prompt, seed=value)
-        setattr(ns.obj, ns.attr, value)
-        return value
-
-class Window:
-    """ Layer above curses to encapsulate what we need """
-    timeout_ms = 200
-    static_scr = None
-    nav_keys = """
-        Navigation:    H/M/L:   top/middle/end-of-page
-            k, UP:  up one row               0, HOME:  first row
-          j, DOWN:  down one row              $, END:  last row
-           Ctrl-u:  half-page up       Ctrl-b, PPAGE:  page up
-           Ctrl-d:  half-page down     Ctrl-f, NPAGE:  page down
-    """
-    def __init__(self, head_line=True, head_rows=50, body_rows=200,
-                 body_cols=200, keys=None, pick_mode=False, pick_size=1):
-        self.scr = self._start_curses()
-
-        self.head = SimpleNamespace(
-            pad=curses.newpad(head_rows, body_cols),
-            rows=head_rows,
-            cols=body_cols,
-            row_cnt=0,  # no. head rows added
-            texts = [],
-            view_cnt=0,  # no. head rows viewable (NOT in body)
-        )
-        self.body = SimpleNamespace(
-            pad = curses.newpad(body_rows, body_cols),
-            rows= body_rows,
-            cols=body_cols,
-            row_cnt = 0,
-            texts = []
-        )
-        self.hor_line_cnt = 1 if head_line else 0 # no. h-lines in header
-        self.scroll_pos = 0  # how far down into body are we?
-        self.max_scroll_pos = 0
-        self.pick_pos = 0 # in highlight mode, where are we?
-        self.last_pick_pos = -1 # last highlighted position
-        self.pick_mode = pick_mode # whether in highlight mode
-        self.pick_size = pick_size # whether in highlight mode
-        self.rows, self.cols = 0, 0
-        self.scroll_view_size = 0  # no. viewable lines of the body
-        self.handled_keys = set(keys) if isinstance(keys, (set, list)) else []
-        self._set_screen_dims()
-        self.calc()
-
-    @staticmethod
-    def get_nav_keys_blurb():
-        """For a help screen, describe the nav keys"""
-        return textwrap.dedent(Window.nav_keys)
-
-    def _set_screen_dims(self):
-        """Recalculate dimensions ... return True if geometry changed."""
-        rows, cols = self.scr.getmaxyx()
-        same = bool(rows == self.rows and cols == self.cols)
-        self.rows, self.cols = rows, cols
-        return same
-
-    @staticmethod
-    def _start_curses():
-        """ Curses initial setup.  Note: not using curses.wrapper because we
-        don't wish to change the colors. """
-        atexit.register(Window.stop_curses)
-        Window.static_scr = scr = curses.initscr()
-        curses.noecho()
-        curses.cbreak()
-        curses.curs_set(0)
-        scr.keypad(1)
-        scr.timeout(Window.timeout_ms)
-        scr.clear()
-        return scr
-
-    def set_pick_mode(self, on=True, pick_size=1):
-        """Set whether in highlight mode."""
-        was_on, was_size = self.pick_mode, self.pick_size
-        self.pick_mode = bool(on)
-        self.pick_size = max(pick_size, 1)
-        if self.pick_mode and (not was_on or was_size != self.pick_size):
-            self.last_pick_pos = -2 # indicates need to clear them all
-
-    @staticmethod
-    def stop_curses():
-        """ Curses shutdown (registered to be called on exit). """
-        if Window.static_scr:
-            curses.nocbreak()
-            curses.echo()
-            Window.static_scr.keypad(0)
-            curses.endwin()
-            Window.static_scr = None
-
-    def calc(self):
-        """Recalculate dimensions ... return True if geometry changed."""
-        same = self._set_screen_dims()
-        self.head.view_cnt = min(self.rows - self.hor_line_cnt, self.head.row_cnt)
-        self.scroll_view_size = self.rows - self.head.view_cnt - self.hor_line_cnt
-        self.max_scroll_pos = max(self.body.row_cnt - self.scroll_view_size, 0)
-        self.body_base = self.head.view_cnt + self.hor_line_cnt
-        return not same
-
-    def _add(self, ns, text, attr=None, resume=False):
-        """ Add text to head/body pad using its namespace"""
-        is_body = bool(id(ns) == id(self.body))
-        if ns.row_cnt < ns.rows:
-            row = max(ns.row_cnt - (1 if resume else 0), 0)
-            if (is_body and self.pick_mode) or attr is None:
-                attr = curses.A_NORMAL
-            if resume:
-                ns.pad.addstr(text, attr)
-                ns.texts[row] += text
-            else:
-                ns.pad.addstr(row, 0, text, attr)
-                ns.texts.append(text)  # text only history
-                ns.row_cnt += 1
-
-    def add_header(self, text, attr=None, resume=False):
-        """Add text to header"""
-        self._add(self.head, text, attr, resume)
-
-    def add_body(self, text, attr=None, resume=False):
-        """ Add text to body (below header and header line)"""
-        self._add(self.body, text, attr, resume)
-
-    def draw(self, y, x, text, text_attr=None, width=None, leftpad=False, header=False):
-        """Draws the given text (as utf-8 or unicode) at position (row=y,col=x)
-        with optional text attributes and width.
-        This is more compatible with my older, simpler Window class.
-        """
-        ns = self.head if header else self.body
-        text_attr = text_attr if text_attr else curses.A_NORMAL
-        if y < 0 or y >= ns.rows or x < 0 or x >= ns.cols:
-            return # nada if out of bounds
-        if y+1 >= ns.row_cnt:
-            ns.row_cnt = y+1
-
-
-        uni = text if isinstance(text, str) else text.decode('utf-8')
-
-        if width is not None:
-            width = min(width, self.cols - x)
-            if width <= 0:
-                return
-            padlen = width - len(uni)
-            if padlen > 0:
-                if leftpad:
-                    uni = padlen * ' ' + uni
-                else:  # rightpad
-                    uni += padlen * ' '
-            text = uni[:width].encode('utf-8')
-        else:
-            text = uni.encode('utf-8')
-
-        try:
-            while y >= len(ns.texts):
-                ns.texts.append('')
-            ns.texts[y] = ns.texts[y][:x].ljust(x) + uni + ns.texts[y][x+len(uni):]
-            ns.pad.addstr(y, x, text, text_attr)
-        except curses.error:
-            # this sucks, but curses returns an error if drawing the last character
-            # on the screen always.  this can happen if resizing screen even if
-            # special care is taken.  So, we just ignore errors.  Anyhow, you cannot
-            # get decent error handling.
-            pass
-
-    def highlight_picked(self):
-        """Highlight the current pick and un-highlight the previous pick."""
-        if not self.pick_mode:
-            return
-        pos0, pos1 = self.last_pick_pos, self.pick_pos
-        if pos0 == -2: # special flag to clear all formatting
-            for row in range(self.body.row_cnt):
-                self.body.pad.addstr(row, 0, self.body.texts[row], curses.A_NORMAL)
-        if pos0 != pos1:
-            if 0 <= pos0 < self.body.row_cnt:
-                for i in range(self.pick_size):
-                    self.body.pad.addstr(pos0+i, 0, self.body.texts[pos0+i], curses.A_NORMAL)
-            if 0 <= pos1 < self.body.row_cnt:
-                for i in range(self.pick_size):
-                    string = self.body.texts[pos1+i]
-                    self.body.pad.addstr(pos1+i, 0, string, curses.A_REVERSE)
-                self.last_pick_pos = pos1
-
-    def _scroll_indicator_row(self):
-        """ Compute the absolute scroll indicator row:
-        - We want the top to be only when scroll_pos==0
-        - We want the bottom to be only when scroll_pos=max_scroll_pos-1
-        """
-        if self.max_scroll_pos <= 1:
-            return self.body_base
-        y2, y1 = self.scroll_view_size-1, 1
-        x2, x1 = self.max_scroll_pos, 1
-        x = self.scroll_pos
-        pos = y1 + (y2-y1)*(x-x1)/(x2-x1)
-        return min(self.body_base + int(max(pos, 0)), self.rows-1)
-
-    def _scroll_indicator_col(self):
-        """ Compute the absolute scroll indicator col:
-        - We want the left to be only when scroll_pos==0
-        - We want the right to be only when scroll_pos=max_scroll_pos-1
-        """
-        if self.pick_mode:
-            return self._calc_indicator(
-                self.pick_pos, 0, self.body.row_cnt-1, 0, self.cols-1)
-        return self._calc_indicator(
-            self.scroll_pos, 0, self.max_scroll_pos, 0, self.cols-1)
-
-    def _calc_indicator(self, pos, pos0, pos9, ind0, ind9):
-        if self.max_scroll_pos <= 0:
-            return -1 # not scrollable
-        if pos9 - pos0 <= 0:
-            return -1 # not scrollable
-        if pos <= pos0:
-            return ind0
-        if pos >= pos9:
-            return ind9
-        ind = int(round(ind0 + (ind9-ind0+1)*(pos-pos0)/(pos9-pos0+1)))
-        return min(max(ind, ind0+1), ind9-1)
-
-    def render(self):
-        """Draw everything added. In a loop cuz curses is a
-        piece of shit."""
-        for _ in range(128):
-            try:
-                self.render_once()
-                return
-            except curses.error:
-                time.sleep(0.16)
-                self._set_screen_dims()
-                continue
-        try:
-            self.render_once()
-        except Exception:
-            Window.stop_curses()
-            print(f"""curses err:
-    head.row_cnt={self.head.row_cnt}
-    head.view_cnt={self.head.view_cnt}
-    hor_line_cnt={self.hor_line_cnt}
-    body.row_cnt={self.body.row_cnt}
-    scroll_pos={self.scroll_pos}
-    max_scroll_pos={self.max_scroll_pos}
-    pick_pos={self.pick_pos}
-    last_pick_pos={self.last_pick_pos}
-    pick_mode={self.pick_mode}
-    pick_size={self.pick_size}
-    rows={self.rows}
-    cols={self.cols}
-""")
-            raise
-
-
-    def render_once(self):
-        """Draw everything added."""
-        self.calc()
-        # if self.scroll_view_size <= 0:
-            # self.scr.refresh()
-        indent = 0
-        if self.body_base < self.rows:
-            ind_pos = 0 if self.pick_mode else self._scroll_indicator_row()
-            if self.pick_mode:
-                self.pick_pos = max(self.pick_pos, 0)
-                self.pick_pos = min(self.pick_pos, self.body.row_cnt-1)
-                if self.pick_pos >= 0:
-                    self.pick_pos -= (self.pick_pos % self.pick_size)
-                if self.pick_pos < 0:
-                    self.scroll_pos = 0
-                elif self.scroll_pos > self.pick_pos:
-                    # light position is below body bottom
-                    self.scroll_pos = self.pick_pos
-                elif self.scroll_pos < self.pick_pos - (self.scroll_view_size - self.pick_size):
-                    # light position is above body top
-                    self.scroll_pos = self.pick_pos - (self.scroll_view_size - self.pick_size)
-                self.scroll_pos = max(self.scroll_pos, 0)
-                self.scroll_pos = min(self.scroll_pos, self.max_scroll_pos)
-                indent = 1
-            else:
-                self.scroll_pos = max(self.scroll_pos, 0)
-                self.scroll_pos = min(self.scroll_pos, self.max_scroll_pos)
-                self.pick_pos = self.scroll_pos + ind_pos - self.body_base
-                # indent = 1 if self.body.row_cnt > self.scroll_view_size else 0
-
-        if indent > 0 and self.pick_mode:
-            self.scr.vline(self.body_base, 0, ' ', self.scroll_view_size)
-            if self.pick_pos >= 0:
-                pos = self.pick_pos - self.scroll_pos + self.body_base
-                self.scr.addstr(pos, 0, '>', curses.A_REVERSE)
-
-        if self.head.view_cnt < self.rows:
-            self.scr.hline(self.head.view_cnt, 0, curses.ACS_HLINE, self.cols)
-            ind_pos = self._scroll_indicator_col()
-            if ind_pos >= 0:
-                bot, cnt = ind_pos, 1
-                if 0 < ind_pos < self.cols-1:
-                    width = self.scroll_view_size/self.body.row_cnt * self.cols
-                    bot = max(int(round(ind_pos-width/2)), 1)
-                    top = min(int(round(ind_pos+width/2)), self.cols-1)
-                    cnt = top - bot
-                # self.scr.addstr(self.head.view_cnt, bot, '-'*cnt, curses.A_REVERSE)
-                # self.scr.hline(self.head.view_cnt, bot, curses.ACS_HLINE, curses.A_REVERSE, cnt)
-                for idx in range(bot, bot+cnt):
-                    self.scr.addch(self.head.view_cnt, idx, curses.ACS_HLINE, curses.A_REVERSE)
-
-        self.scr.refresh()
-
-        if self.rows > 0:
-            last_row = min(self.head.view_cnt, self.rows)-1
-            if last_row >= 0:
-                self.head.pad.refresh(0, 0, 0, indent, last_row, self.cols-1)
-
-        if self.body_base < self.rows:
-            if self.pick_mode:
-                self.highlight_picked()
-            self.body.pad.refresh(self.scroll_pos, 0,
-                  self.body_base, indent, self.rows-1, self.cols-1)
-
-
-    def answer(self, prompt='Type string [then Enter]', seed='', width=80):
-        """Popup"""
-        def mod_key(key):
-            return  7 if key == 10 else key
-
-        # need 3 extra cols for rectangle (so we don't draw in southeast corner)
-        # and 3 rows (top/prompt/bottom)
-        #      +Prompt---    -----------------+
-        #      | Seed-for-answer              |
-        #      +---------Press ENTER to submit+
-        if self.rows < 3 or self.cols < 30:
-            return seed
-        width = min(width, self.cols-3) # max text width
-        row0, row9 = self.rows//2 - 1, self.rows//2 + 1
-        col0 = (self.cols - (width+2)) // 2
-        col9 = col0 + width + 2 - 1
-
-        self.scr.clear()
-        win = curses.newwin(1, width, row0+1, col0+1) # input window
-        rectangle(self.scr, row0, col0, row9, col9)
-        self.scr.addstr(row0, col0+1, prompt[0:width])
-        win.addstr(seed[0:width-1])
-        ending = 'Press ENTER to submit'[:width]
-        self.scr.addstr(row9, col0+1+width-len(ending), ending)
-        self.scr.refresh()
-        curses.curs_set(2)
-        answer = Textbox(win).edit(mod_key).strip()
-        curses.curs_set(0)
-        return answer
-
-    def alert(self, title='ALERT', message='', height=1, width=80):
-        """Alert box"""
-        def mod_key(key):
-            return  7 if key == 10 else key
-
-        # need 3 extra cols for rectangle (so we don't draw in southeast corner)
-        # and 3 rows (top/prompt/bottom)
-        #      +Prompt---    -----------------+
-        #      | First line for message...    |
-        #      | Last line for message.       |
-        #      +-----------Press ENTER  to ack+
-        if self.rows < 2+height or self.cols < 30:
-            return
-        width = min(width, self.cols-3) # max text width
-        row0 = (self.rows+height-1)//2 - 1
-        row9 = row0 + height + 1
-        col0 = (self.cols - (width+2)) // 2
-        col9 = col0 + width + 2 - 1
-
-        self.scr.clear()
-        for row in range(self.rows):
-            self.scr.insstr(row, 0, ' '*self.cols, curses.A_REVERSE)
-        pad = curses.newpad(20, 200)
-        win = curses.newwin(1, 1, row9-1, col9-2) # input window
-        rectangle(self.scr, row0, col0, row9, col9)
-        self.scr.addstr(row0, col0+1, title[0:width], curses.A_REVERSE)
-        pad.addstr(message)
-        ending = 'Press ENTER to ack'[:width]
-        self.scr.addstr(row9, col0+1+width-len(ending), ending)
-        self.scr.refresh()
-        pad.refresh(0, 0, row0+1, col0+1, row9-1, col9-1)
-        Textbox(win).edit(mod_key).strip()
-        return
-
-    def clear(self):
-        """Clear in prep for new screen"""
-        self.scr.clear()
-        self.head.pad.clear()
-        self.body.pad.clear()
-        self.head.texts, self.body.texts, self.last_pick_pos = [], [], -1
-        self.head.row_cnt = self.body.row_cnt = 0
-
-    def prompt(self, seconds=1.0):
-        """Here is where we sleep waiting for commands or timeout"""
-        ctl_b, ctl_d, ctl_f, ctl_u = 2, 4, 6, 21
-        elapsed = 0.0
-        while elapsed < seconds:
-            key = self.scr.getch()
-            if key == curses.ERR:
-                elapsed += self.timeout_ms / 1000
-                continue
-            if key in (curses.KEY_RESIZE, ) or curses.is_term_resized(self.rows, self.cols):
-                # self.scr.erase()
-                self._set_screen_dims()
-                # self.render()
-                break
-
-            # App keys...
-            if key in self.handled_keys:
-                return key # return for handling
-
-            # Navigation Keys...
-            pos = self.pick_pos if self.pick_mode else self.scroll_pos
-            delta = self.pick_size if self.pick_mode else 1
-            was_pos = pos
-            if key in (ord('k'), curses.KEY_UP):
-                pos -= delta
-            elif key in (ord('j'), curses.KEY_DOWN):
-                pos += delta
-            elif key in (ctl_b, curses.KEY_PPAGE):
-                pos -= self.scroll_view_size
-            elif key in (ctl_u, ):
-                pos -= self.scroll_view_size//2
-            elif key in (ctl_f, curses.KEY_NPAGE):
-                pos += self.scroll_view_size
-            elif key in (ctl_d, ):
-                pos += self.scroll_view_size//2
-            elif key in (ord('0'), curses.KEY_HOME):
-                pos = 0
-            elif key in (ord('$'), curses.KEY_END):
-                pos = self.body.row_cnt - 1
-            elif key in (ord('H'), ):
-                pos = self.scroll_pos
-            elif key in (ord('M'), ):
-                pos = self.scroll_pos + self.scroll_view_size//2
-            elif key in (ord('L'), ):
-                pos = self.scroll_pos + self.scroll_view_size-1
-
-            if self.pick_mode:
-                self.pick_pos = pos
-            else:
-                self.scroll_pos = pos
-                self.pick_pos = pos
-
-            if pos != was_pos:
-                self.render()
-            # ignore unhandled keys
-        return None
-
-def no_runner():
-    """Appease sbrun"""
-
-if __name__ == '__main__':
-    def main():
-        """Test program"""
-        def do_key(key):
-            nonlocal spin, win, opts
-            value = spin.do_key(key, win)
-            if key in (ord('p'), ord('s')):
-                win.set_pick_mode(on=opts.pick_mode, pick_size=opts.pick_size)
-            elif key == ord('n'):
-                win.alert(title='Info', message=f'got: {value}')
-            return value
-
-        spin = OptionSpinner()
-        spin.add_key('help_mode', '? - toggle help screen', vals=[False, True])
-        spin.add_key('pick_mode', 'p - toggle pick mode', vals=[False, True])
-        spin.add_key('pick_size', 's - #rows in pick', vals=[1, 2, 3])
-        spin.add_key('name', 'n - select name', prompt='Provide Your Name:')
-        spin.add_key('mult', 'm - row multiplier', vals=[0.5, 0.9, 1.0, 1.1, 2, 4, 16])
-        opts = spin.default_obj
-
-        win = Window(head_line=True, keys=spin.keys)
-        opts.name = "[hit 'n' to enter name]"
-        for loop in range(100000000000):
-            body_size = int(round(win.scroll_view_size*opts.mult))
-            if opts.help_mode:
-                win.set_pick_mode(False)
-                spin.show_help_nav_keys(win)
-                spin.show_help_body(win)
-            else:
-                win.set_pick_mode(opts.pick_mode, opts.pick_size)
-                win.add_header(f'Header: {loop} "{opts.name}"')
-                for idx, line in enumerate(range(body_size//opts.pick_size)):
-                    win.add_body(f'Main pick: {loop}.{line}')
-                    for num in range(1, opts.pick_size):
-                        win.draw(num+idx*opts.pick_size, 0, f'  addon: {loop}.{line}')
-            win.render()
-            do_key(win.prompt(seconds=5))
-            win.clear()
-
-    try:
-        main()
-    except KeyboardInterrupt:
-        pass
-    except Exception as exce:
-        Window.stop_curses()
-        print("exception:", str(exce))
-        print(traceback.format_exc())
-        if dump_str:
-            print(dump_str)