cs-tty 20260912__tar.gz

cs_tty-20260912/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: cs-tty
+Version: 20260912
+Summary: Functions related to terminals.
+Keywords: python2,python3
+Author-email: Cameron Simpson <cs@cskk.id.au>
+Description-Content-Type: text/markdown
+Classifier: Environment :: Console
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 2
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Terminals
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Requires-Dist: cs.gimmicks>=20260311
+Project-URL: MonoRepo Commits, https://bitbucket.org/cameron_simpson/css/commits/branch/main
+Project-URL: Monorepo Git Mirror, https://github.com/cameron-simpson/css
+Project-URL: Monorepo Hg/Mercurial Mirror, https://hg.sr.ht/~cameron-simpson/css
+Project-URL: Source, https://github.com/cameron-simpson/css/blob/main/lib/python/cs/tty.py
+
+Functions related to terminals.
+
+*Latest release 20260912*:
+New ttysizepx(fd) function returning the tty size in characters and pixels.
+
+
+
+Short summary:
+
+
+* `modify_termios`: Apply mode changes to a tty. Return the previous tty modes as from `termios.tcgetattr` or `None` if the changes could not be applied. If `strict`, raise an exception instead of returning `None`.
+
+
+* `setupterm`: Run curses.setupterm, needed to be able to use the status line. Uses a global flag to avoid doing this twice.
+
+
+* `stack_termios`: Context manager to apply and restore changes to a tty. Yield the previous tty modes as from `termios.tcgetattr` or `None` if the changes could not be applied. If `strict`, raise an exception instead of yielding `None`.
+
+
+* `status`: Write a message to the terminal's status line.
+
+
+* `statusline`: Update the status line.
+
+
+* `statusline_bs`: Return a byte string to update the status line.
+
+
+* `ttysize`: Return a (rows, columns) tuple for the specified file descriptor.
+
+
+* `ttysizepx`: Return a `(rows,columns,widthpx,heightpx)` tuple for the specified file descriptor being the terminal character rows and columns and pixel width and height respectively.
+
+
+* `WinSize`: WinSize(rows, columns).
+
+
+* `WinSizePX`: WinSizePX(rows, columns, widthpx, heightpx).
+
+# Functions
+
+## modify_termios(fd=0, set_modes=None, clear_modes=None, strict=False)
+
+Apply mode changes to a tty.
+Return the previous tty modes as from `termios.tcgetattr`
+or `None` if the changes could not be applied.
+If `strict`, raise an exception instead of returning `None`.
+
+Parameters:
+* `fd`: optional tty file descriptor, default `0`.
+* `set_modes`: an optional  mapping of attribute name to new value
+  for values to set
+* `clear_modes`: an optional  mapping of attribute name to new value
+  for values to clear
+* `strict`: optional flag, default `False`;
+  if true, raise exceptions from failed `tcgetattr` and `tcsetattr` calls
+  otherwise issue a warning if the errno is not `ENOTTY` and proceed.
+  This aims to provide ease of use in batch mode by default
+  while providing a mode to fail overtly if required.
+
+The attribute names are from
+`iflag`, `oflag`, `cflag`, `lflag`, `ispeed`, `ospeed`, `cc`,
+corresponding to the list entries defined by the `termios.tcgetattr`
+call.
+
+For `set_modes`, the attributes `ispeed`, `ospeed` and `cc`
+are applied directly;
+the other attributes are binary ORed into the existing modes.
+
+For `clear_modes`, the attributes `ispeed`, `ospeed` and `cc`
+cannot be cleared;
+the other attributes are binary removed from the existing modes.
+
+For example, to turn off the terminal echo during some operation:
+
+    old_modes = apply_termios(clear_modes={'lflag': termios.ECHO}):
+        ... do something with tty echo disabled ...
+    if old_modes:
+        termios.tcsetattr(fd, termios.TCSANOW, old_modes)
+
+## setupterm(*args)
+
+Run curses.setupterm, needed to be able to use the status line.
+Uses a global flag to avoid doing this twice.
+
+## stack_termios(fd=0, set_modes=None, clear_modes=None, strict=False)
+
+Context manager to apply and restore changes to a tty.
+Yield the previous tty modes as from `termios.tcgetattr`
+or `None` if the changes could not be applied.
+If `strict`, raise an exception instead of yielding `None`.
+
+Parameters:
+* `fd`: optional tty file descriptor, default `0`.
+* `set_modes`: an optional  mapping of attribute name to new value
+  for values to set
+* `clear_modes`: an optional  mapping of attribute name to new value
+  for values to clear
+* `strict`: optional flag, default `False`;
+  if true, raise exceptions from failed `tcgetattr` and `tcsetattr` calls
+  otherwise issue a warning if the errno is not `ENOTTY` and proceed.
+  This aims to provide ease of use in batch mode by default
+  while providing a mode to fail overtly if required.
+
+The attribute names are from
+`iflag`, `oflag`, `cflag`, `lflag`, `ispeed`, `ospeed`, `cc`,
+corresponding to the list entries defined by the `termios.tcgetattr`
+call.
+
+For `set_modes`, the attributes `ispeed`, `ospeed` and `cc`
+are applied directly;
+the other attributes are binary ORed into the existing modes.
+
+For `clear_modes`, the attributes `ispeed`, `ospeed` and `cc`
+cannot be cleared;
+the other attributes are binary removed from the existing modes.
+
+For example, to turn off the terminal echo during some operation:
+
+    with stack_termios(clear_modes={'lflag': termios.ECHO}):
+        ... do something with tty echo disabled ...
+
+## status(msg, *args, **kwargs)
+
+Write a message to the terminal's status line.
+
+Parameters:
+* `msg`: message string
+* `args`: if not empty, the message is %-formatted with `args`
+* `file`: optional keyword argument specifying the output file.
+  Default: `sys.stderr`.
+
+Hack: if there is no status line use the xterm title bar sequence :-(
+
+## statusline(text, fd=None, reverse=False, xpos=None, ypos=None)
+
+Update the status line.
+
+## statusline_bs(text, reverse=False, xpos=None, ypos=None)
+
+Return a byte string to update the status line.
+
+## ttysize(fd)
+
+Return a (rows, columns) tuple for the specified file descriptor.
+
+If the window size cannot be determined, None will be returned
+for either or both of rows and columns.
+
+This function relies on the UNIX `stty` command.
+
+## ttysizepx(fd)
+
+Return a `(rows,columns,widthpx,heightpx)` tuple for the
+specified file descriptor being the terminal character rows
+and columns and pixel width and height respectively.
+
+This function relies on the `fcntl.ioctl` using `termios.TIOCGWINSZ`.
+
+# Classes
+
+## class WinSize(builtins.tuple)
+
+WinSize(rows, columns)
+
+### `WinSize.__match_args__`
+
+Built-in immutable sequence.
+
+If no argument is given, the constructor returns an empty tuple.
+If iterable is specified the tuple is initialized from iterable's items.
+
+If the argument is a tuple, the return value is the same object.
+
+### `WinSize.__replace__(self, /, **kwds)`
+
+Return a new WinSize object replacing specified fields with new values
+
+### `WinSize.__slots__`
+
+Built-in immutable sequence.
+
+If no argument is given, the constructor returns an empty tuple.
+If iterable is specified the tuple is initialized from iterable's items.
+
+If the argument is a tuple, the return value is the same object.
+
+### `WinSize.columns`
+
+Alias for field number 1
+
+### `WinSize.rows`
+
+Alias for field number 0
+
+## class WinSizePX(builtins.tuple)
+
+WinSizePX(rows, columns, widthpx, heightpx)
+
+### `WinSizePX.__match_args__`
+
+Built-in immutable sequence.
+
+If no argument is given, the constructor returns an empty tuple.
+If iterable is specified the tuple is initialized from iterable's items.
+
+If the argument is a tuple, the return value is the same object.
+
+### `WinSizePX.__replace__(self, /, **kwds)`
+
+Return a new WinSizePX object replacing specified fields with new values
+
+### `WinSizePX.__slots__`
+
+Built-in immutable sequence.
+
+If no argument is given, the constructor returns an empty tuple.
+If iterable is specified the tuple is initialized from iterable's items.
+
+If the argument is a tuple, the return value is the same object.
+
+### `WinSizePX.columns`
+
+Alias for field number 1
+
+### `WinSizePX.heightpx`
+
+Alias for field number 3
+
+### `WinSizePX.rows`
+
+Alias for field number 0
+
+### `WinSizePX.widthpx`
+
+Alias for field number 2
+
+# Release Log
+
+
+
+*Release 20260912*:
+New ttysizepx(fd) function returning the tty size in characters and pixels.
+
+*Release 20210316*:
+* ttysize: discard the Popen object earlier.
+* ttysize: close Popen.stdout after use. seems to leak.
+
+*Release 20201102*:
+New modify_termios and stack_termios to apply (and restore) termios modes.
+
+*Release 20200521*:
+* New status() function dragged in from cs.logutils, which uses cs.upd for status() -- needs some refactoring to match with the other functions in cs.tty -- text vs bytes, stdout vs stderr, etc.
+* Get warning() from cs.gimmicks.
+
+*Release 20190101*:
+Small bugfix for setupterm.
+
+*Release 20170903*:
+add statusline and statusline_s functions; ttysize: support BSD stty output format
+
+*Release 20160828*:
+Use "install_requires" instead of "requires" in DISTINFO, add PyPI category.
+
+*Release 20150116*:
+Initial PyPI release.

cs_tty-20260912/pyproject.toml

@@ -0,0 +1,313 @@
+[project]
+name = "cs-tty"
+description = "Functions related to terminals."
+authors = [
+    { name = "Cameron Simpson", email = "cs@cskk.id.au" },
+]
+keywords = [
+    "python2",
+    "python3",
+]
+dependencies = [
+    "cs.gimmicks>=20260311",
+]
+classifiers = [
+    "Environment :: Console",
+    "Operating System :: POSIX",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 2",
+    "Programming Language :: Python :: 3",
+    "Topic :: Terminals",
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+]
+version = "20260912"
+
+[project.license]
+text = "GNU General Public License v3 or later (GPLv3+)"
+
+[project.urls]
+"Monorepo Hg/Mercurial Mirror" = "https://hg.sr.ht/~cameron-simpson/css"
+"Monorepo Git Mirror" = "https://github.com/cameron-simpson/css"
+"MonoRepo Commits" = "https://bitbucket.org/cameron_simpson/css/commits/branch/main"
+Source = "https://github.com/cameron-simpson/css/blob/main/lib/python/cs/tty.py"
+
+[project.readme]
+text = """
+Functions related to terminals.
+
+*Latest release 20260912*:
+New ttysizepx(fd) function returning the tty size in characters and pixels.
+
+
+
+Short summary:
+
+
+* `modify_termios`: Apply mode changes to a tty. Return the previous tty modes as from `termios.tcgetattr` or `None` if the changes could not be applied. If `strict`, raise an exception instead of returning `None`.
+
+
+* `setupterm`: Run curses.setupterm, needed to be able to use the status line. Uses a global flag to avoid doing this twice.
+
+
+* `stack_termios`: Context manager to apply and restore changes to a tty. Yield the previous tty modes as from `termios.tcgetattr` or `None` if the changes could not be applied. If `strict`, raise an exception instead of yielding `None`.
+
+
+* `status`: Write a message to the terminal's status line.
+
+
+* `statusline`: Update the status line.
+
+
+* `statusline_bs`: Return a byte string to update the status line.
+
+
+* `ttysize`: Return a (rows, columns) tuple for the specified file descriptor.
+
+
+* `ttysizepx`: Return a `(rows,columns,widthpx,heightpx)` tuple for the specified file descriptor being the terminal character rows and columns and pixel width and height respectively.
+
+
+* `WinSize`: WinSize(rows, columns).
+
+
+* `WinSizePX`: WinSizePX(rows, columns, widthpx, heightpx).
+
+# Functions
+
+## modify_termios(fd=0, set_modes=None, clear_modes=None, strict=False)
+
+Apply mode changes to a tty.
+Return the previous tty modes as from `termios.tcgetattr`
+or `None` if the changes could not be applied.
+If `strict`, raise an exception instead of returning `None`.
+
+Parameters:
+* `fd`: optional tty file descriptor, default `0`.
+* `set_modes`: an optional  mapping of attribute name to new value
+  for values to set
+* `clear_modes`: an optional  mapping of attribute name to new value
+  for values to clear
+* `strict`: optional flag, default `False`;
+  if true, raise exceptions from failed `tcgetattr` and `tcsetattr` calls
+  otherwise issue a warning if the errno is not `ENOTTY` and proceed.
+  This aims to provide ease of use in batch mode by default
+  while providing a mode to fail overtly if required.
+
+The attribute names are from
+`iflag`, `oflag`, `cflag`, `lflag`, `ispeed`, `ospeed`, `cc`,
+corresponding to the list entries defined by the `termios.tcgetattr`
+call.
+
+For `set_modes`, the attributes `ispeed`, `ospeed` and `cc`
+are applied directly;
+the other attributes are binary ORed into the existing modes.
+
+For `clear_modes`, the attributes `ispeed`, `ospeed` and `cc`
+cannot be cleared;
+the other attributes are binary removed from the existing modes.
+
+For example, to turn off the terminal echo during some operation:
+
+    old_modes = apply_termios(clear_modes={'lflag': termios.ECHO}):
+        ... do something with tty echo disabled ...
+    if old_modes:
+        termios.tcsetattr(fd, termios.TCSANOW, old_modes)
+
+## setupterm(*args)
+
+Run curses.setupterm, needed to be able to use the status line.
+Uses a global flag to avoid doing this twice.
+
+## stack_termios(fd=0, set_modes=None, clear_modes=None, strict=False)
+
+Context manager to apply and restore changes to a tty.
+Yield the previous tty modes as from `termios.tcgetattr`
+or `None` if the changes could not be applied.
+If `strict`, raise an exception instead of yielding `None`.
+
+Parameters:
+* `fd`: optional tty file descriptor, default `0`.
+* `set_modes`: an optional  mapping of attribute name to new value
+  for values to set
+* `clear_modes`: an optional  mapping of attribute name to new value
+  for values to clear
+* `strict`: optional flag, default `False`;
+  if true, raise exceptions from failed `tcgetattr` and `tcsetattr` calls
+  otherwise issue a warning if the errno is not `ENOTTY` and proceed.
+  This aims to provide ease of use in batch mode by default
+  while providing a mode to fail overtly if required.
+
+The attribute names are from
+`iflag`, `oflag`, `cflag`, `lflag`, `ispeed`, `ospeed`, `cc`,
+corresponding to the list entries defined by the `termios.tcgetattr`
+call.
+
+For `set_modes`, the attributes `ispeed`, `ospeed` and `cc`
+are applied directly;
+the other attributes are binary ORed into the existing modes.
+
+For `clear_modes`, the attributes `ispeed`, `ospeed` and `cc`
+cannot be cleared;
+the other attributes are binary removed from the existing modes.
+
+For example, to turn off the terminal echo during some operation:
+
+    with stack_termios(clear_modes={'lflag': termios.ECHO}):
+        ... do something with tty echo disabled ...
+
+## status(msg, *args, **kwargs)
+
+Write a message to the terminal's status line.
+
+Parameters:
+* `msg`: message string
+* `args`: if not empty, the message is %-formatted with `args`
+* `file`: optional keyword argument specifying the output file.
+  Default: `sys.stderr`.
+
+Hack: if there is no status line use the xterm title bar sequence :-(
+
+## statusline(text, fd=None, reverse=False, xpos=None, ypos=None)
+
+Update the status line.
+
+## statusline_bs(text, reverse=False, xpos=None, ypos=None)
+
+Return a byte string to update the status line.
+
+## ttysize(fd)
+
+Return a (rows, columns) tuple for the specified file descriptor.
+
+If the window size cannot be determined, None will be returned
+for either or both of rows and columns.
+
+This function relies on the UNIX `stty` command.
+
+## ttysizepx(fd)
+
+Return a `(rows,columns,widthpx,heightpx)` tuple for the
+specified file descriptor being the terminal character rows
+and columns and pixel width and height respectively.
+
+This function relies on the `fcntl.ioctl` using `termios.TIOCGWINSZ`.
+
+# Classes
+
+## class WinSize(builtins.tuple)
+
+WinSize(rows, columns)
+
+### `WinSize.__match_args__`
+
+Built-in immutable sequence.
+
+If no argument is given, the constructor returns an empty tuple.
+If iterable is specified the tuple is initialized from iterable's items.
+
+If the argument is a tuple, the return value is the same object.
+
+### `WinSize.__replace__(self, /, **kwds)`
+
+Return a new WinSize object replacing specified fields with new values
+
+### `WinSize.__slots__`
+
+Built-in immutable sequence.
+
+If no argument is given, the constructor returns an empty tuple.
+If iterable is specified the tuple is initialized from iterable's items.
+
+If the argument is a tuple, the return value is the same object.
+
+### `WinSize.columns`
+
+Alias for field number 1
+
+### `WinSize.rows`
+
+Alias for field number 0
+
+## class WinSizePX(builtins.tuple)
+
+WinSizePX(rows, columns, widthpx, heightpx)
+
+### `WinSizePX.__match_args__`
+
+Built-in immutable sequence.
+
+If no argument is given, the constructor returns an empty tuple.
+If iterable is specified the tuple is initialized from iterable's items.
+
+If the argument is a tuple, the return value is the same object.
+
+### `WinSizePX.__replace__(self, /, **kwds)`
+
+Return a new WinSizePX object replacing specified fields with new values
+
+### `WinSizePX.__slots__`
+
+Built-in immutable sequence.
+
+If no argument is given, the constructor returns an empty tuple.
+If iterable is specified the tuple is initialized from iterable's items.
+
+If the argument is a tuple, the return value is the same object.
+
+### `WinSizePX.columns`
+
+Alias for field number 1
+
+### `WinSizePX.heightpx`
+
+Alias for field number 3
+
+### `WinSizePX.rows`
+
+Alias for field number 0
+
+### `WinSizePX.widthpx`
+
+Alias for field number 2
+
+# Release Log
+
+
+
+*Release 20260912*:
+New ttysizepx(fd) function returning the tty size in characters and pixels.
+
+*Release 20210316*:
+* ttysize: discard the Popen object earlier.
+* ttysize: close Popen.stdout after use. seems to leak.
+
+*Release 20201102*:
+New modify_termios and stack_termios to apply (and restore) termios modes.
+
+*Release 20200521*:
+* New status() function dragged in from cs.logutils, which uses cs.upd for status() -- needs some refactoring to match with the other functions in cs.tty -- text vs bytes, stdout vs stderr, etc.
+* Get warning() from cs.gimmicks.
+
+*Release 20190101*:
+Small bugfix for setupterm.
+
+*Release 20170903*:
+add statusline and statusline_s functions; ttysize: support BSD stty output format
+
+*Release 20160828*:
+Use \"install_requires\" instead of \"requires\" in DISTINFO, add PyPI category.
+
+*Release 20150116*:
+Initial PyPI release."""
+content-type = "text/markdown"
+
+[build-system]
+build-backend = "flit_core.buildapi"
+requires = [
+    "flit_core >=3.2,<4",
+]
+
+[tool.flit.module]
+name = "cs.tty"

cs_tty-20260912/src/cs/tty.py

@@ -0,0 +1,339 @@
+#!/usr/bin/python
+#
+# Facilities for terminals.
+#       - Cameron Simpson <cs@cskk.id.au>
+#
+
+''' Functions related to terminals.
+'''
+
+from __future__ import print_function
+import array
+from collections import namedtuple
+from contextlib import contextmanager
+import errno
+import fcntl
+import os
+import re
+from subprocess import Popen, PIPE
+import sys
+from termios import tcsetattr, tcgetattr, TCSANOW, TIOCGWINSZ
+from cs.gimmicks import warning
+
+__version__ = '20260912'
+
+DISTINFO = {
+    'keywords': ["python2", "python3"],
+    'classifiers': [
+        "Environment :: Console",
+        "Operating System :: POSIX",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 2",
+        "Programming Language :: Python :: 3",
+        "Topic :: Terminals",
+    ],
+    'install_requires': ['cs.gimmicks'],
+}
+
+WinSize = namedtuple('WinSize', 'rows columns')
+
+def ttysize(fd):
+  ''' Return a (rows, columns) tuple for the specified file descriptor.
+
+      If the window size cannot be determined, None will be returned
+      for either or both of rows and columns.
+
+      This function relies on the UNIX `stty` command.
+  '''
+  if not isinstance(fd, int):
+    fd = fd.fileno()
+  P = Popen(['stty', '-a'], stdin=fd, stdout=PIPE, universal_newlines=True)
+  stty = P.stdout.read()
+  P.stdout.close()
+  xit = P.wait()
+  del P
+  if xit != 0:
+    return None
+  m = re.compile(r' rows (\d+); columns (\d+)').search(stty)
+  if m:
+    rows, columns = int(m.group(1)), int(m.group(2))
+  else:
+    m = re.compile(r' (\d+) rows; (\d+) columns').search(stty)
+    if m:
+      rows, columns = int(m.group(1)), int(m.group(2))
+    else:
+      rows, columns = None, None
+  return WinSize(rows, columns)
+
+WinSizePX = namedtuple('WinSizePX', 'rows columns widthpx heightpx')
+
+def ttysizepx(fd):
+  ''' Return a `(rows,columns,widthpx,heightpx)` tuple for the
+      specified file descriptor being the terminal character rows
+      and columns and pixel width and height respectively.
+
+      This function relies on the `fcntl.ioctl` using `termios.TIOCGWINSZ`.
+  '''
+  if not isinstance(fd, int):
+    fd = fd.fileno()
+  buf = array.array('H', [0, 0, 0, 0])
+  fcntl.ioctl(fd, TIOCGWINSZ, buf)
+  return WinSizePX(*buf)
+
+_ti_setup = False
+
+def setupterm(*args):
+  ''' Run curses.setupterm, needed to be able to use the status line.
+      Uses a global flag to avoid doing this twice.
+  '''
+  global _ti_setup  # pylint: disable=global-statement
+  if _ti_setup:
+    return True
+  termstr = None
+  fd = None
+  if args:
+    args = list(args)
+    termstr = args.pop(0)
+    if args:
+      fd = args.pop(0)
+      if args:
+        raise ValueError("extra arguments after termstr and fd: %r" % (args,))
+  if termstr is None:
+    termstr = os.environ['TERM']
+  if fd is None:
+    fd = sys.stdout.fileno()
+  import curses  # pylint: disable=import-outside-toplevel
+  curses.setupterm(termstr, fd)
+  _ti_setup = True
+  return True
+
+def statusline_bs(text, reverse=False, xpos=None, ypos=None):
+  ''' Return a byte string to update the status line.
+  '''
+  from curses import tigetstr, tparm, tigetflag  # pylint: disable=import-outside-toplevel
+  setupterm()
+  if tigetflag('hs'):
+    seq = (
+        tigetstr('tsl'),
+        tigetstr('dsl'),
+        tigetstr('rev') if reverse else b'',
+        text.encode(),
+        tigetstr('fsl'),
+    )
+  else:
+    # save cursor position, position, reverse, restore position
+    if xpos is None:
+      xpos = 0
+    if ypos is None:
+      ypos = 0
+    seq = (
+        tigetstr('sc'),  # save cursor position
+        tparm(tigetstr("cup"), xpos, ypos),
+        tigetstr('rev') if reverse else b'',
+        text.encode(),
+        tigetstr('el'),
+        tigetstr('rc')
+    )
+  return b''.join(seq)
+
+def statusline(text, fd=None, reverse=False, xpos=None, ypos=None):
+  ''' Update the status line.
+  '''
+  if fd is None:
+    fd = sys.stdout.fileno()
+  os.write(fd, statusline_bs(text, reverse=reverse, xpos=xpos, ypos=ypos))
+
+def status(msg, *args, **kwargs):
+  ''' Write a message to the terminal's status line.
+
+      Parameters:
+      * `msg`: message string
+      * `args`: if not empty, the message is %-formatted with `args`
+      * `file`: optional keyword argument specifying the output file.
+        Default: `sys.stderr`.
+
+      Hack: if there is no status line use the xterm title bar sequence :-(
+  '''
+  if args:
+    msg = msg % args
+  f = kwargs.pop('file', None)
+  if kwargs:
+    raise ValueError("unexpected keyword arguments: %r" % (kwargs,))
+  if f is None:
+    f = sys.stderr
+  try:
+    has_ansi_status = f.has_ansi_status
+  except AttributeError:
+    try:
+      import curses  # pylint: disable=import-outside-toplevel
+    except ImportError:
+      has_ansi_status = None
+    else:
+      curses.setupterm()
+      has_status = curses.tigetflag('hs')
+      if has_status == -1:
+        warning(
+            'status: curses.tigetflag(hs): not a Boolean capability, presuming false'
+        )
+        has_ansi_status = None
+      elif has_status > 0:
+        has_ansi_status = (
+            curses.tigetstr('to_status_line'),
+            curses.tigetstr('from_status_line')
+        )
+      else:
+        warning('status: hs=%s, presuming false', has_status)
+        has_ansi_status = None
+    f.has_ansi_status = has_ansi_status
+  if has_ansi_status:
+    msg = has_ansi_status[0] + msg + has_ansi_status[1]
+  else:
+    msg = '\033]0;' + msg + '\007'
+  f.write(msg)
+  f.flush()
+
+_termios_modes_names = {
+    name: index
+    for index, name in
+    enumerate(('iflag', 'oflag', 'cflag', 'lflag', 'ispeed', 'ospeed', 'cc'))
+}
+
+# pylint: disable=too-many-branches
+def modify_termios(fd=0, set_modes=None, clear_modes=None, strict=False):
+  ''' Apply mode changes to a tty.
+      Return the previous tty modes as from `termios.tcgetattr`
+      or `None` if the changes could not be applied.
+      If `strict`, raise an exception instead of returning `None`.
+
+      Parameters:
+      * `fd`: optional tty file descriptor, default `0`.
+      * `set_modes`: an optional  mapping of attribute name to new value
+        for values to set
+      * `clear_modes`: an optional  mapping of attribute name to new value
+        for values to clear
+      * `strict`: optional flag, default `False`;
+        if true, raise exceptions from failed `tcgetattr` and `tcsetattr` calls
+        otherwise issue a warning if the errno is not `ENOTTY` and proceed.
+        This aims to provide ease of use in batch mode by default
+        while providing a mode to fail overtly if required.
+
+      The attribute names are from
+      `iflag`, `oflag`, `cflag`, `lflag`, `ispeed`, `ospeed`, `cc`,
+      corresponding to the list entries defined by the `termios.tcgetattr`
+      call.
+
+      For `set_modes`, the attributes `ispeed`, `ospeed` and `cc`
+      are applied directly;
+      the other attributes are binary ORed into the existing modes.
+
+      For `clear_modes`, the attributes `ispeed`, `ospeed` and `cc`
+      cannot be cleared;
+      the other attributes are binary removed from the existing modes.
+
+      For example, to turn off the terminal echo during some operation:
+
+          old_modes = apply_termios(clear_modes={'lflag': termios.ECHO}):
+              ... do something with tty echo disabled ...
+          if old_modes:
+              termios.tcsetattr(fd, termios.TCSANOW, old_modes)
+  '''
+  if set_modes:
+    if not all(map(lambda k: k in _termios_modes_names, set_modes.keys())):
+      raise ValueError(
+          "set_modes: invalid mode keys: known=%r, supplied=%r" %
+          (sorted(_termios_modes_names.keys()), set_modes)
+      )
+  if clear_modes:
+    if not all(map(lambda k: k in _termios_modes_names, clear_modes.keys())):
+      raise ValueError(
+          "clear_modes: invalid mode keys: known=%r, supplied=%r" %
+          (sorted(_termios_modes_names.keys()), clear_modes)
+      )
+    for k in 'ispeed', 'ospeed', 'cc':
+      if k in clear_modes:
+        raise ValueError("clear_modes: cannot clear %r" % (k,))
+  try:
+    original_modes = tcgetattr(fd)
+  except OSError as e:
+    if strict:
+      raise
+    if e.errno != errno.ENOTTY:
+      warning("tcgetattr(%d): %s", fd, e)
+    original_modes = None
+  restore_modes = None
+  if original_modes:
+    new_modes = list(original_modes)
+    if set_modes:
+      for k, v in set_modes.items():
+        i = _termios_modes_names[k]
+        if k in ('ispeed', 'ospeed', 'cc'):
+          new_modes[i] = v
+        else:
+          new_modes[i] |= v
+    if clear_modes:
+      for k, v in clear_modes.items():
+        i = _termios_modes_names[k]
+        new_modes[i] &= ~v
+    if new_modes == original_modes:
+      restore_modes = None
+    else:
+      try:
+        tcsetattr(fd, TCSANOW, new_modes)
+      except OSError as e:
+        if strict:
+          raise
+        warning("tcsetattr(%d,TCSANOW,%r): %e", fd, new_modes, e)
+      else:
+        restore_modes = original_modes
+  return restore_modes
+
+@contextmanager
+def stack_termios(fd=0, set_modes=None, clear_modes=None, strict=False):
+  ''' Context manager to apply and restore changes to a tty.
+      Yield the previous tty modes as from `termios.tcgetattr`
+      or `None` if the changes could not be applied.
+      If `strict`, raise an exception instead of yielding `None`.
+
+      Parameters:
+      * `fd`: optional tty file descriptor, default `0`.
+      * `set_modes`: an optional  mapping of attribute name to new value
+        for values to set
+      * `clear_modes`: an optional  mapping of attribute name to new value
+        for values to clear
+      * `strict`: optional flag, default `False`;
+        if true, raise exceptions from failed `tcgetattr` and `tcsetattr` calls
+        otherwise issue a warning if the errno is not `ENOTTY` and proceed.
+        This aims to provide ease of use in batch mode by default
+        while providing a mode to fail overtly if required.
+
+      The attribute names are from
+      `iflag`, `oflag`, `cflag`, `lflag`, `ispeed`, `ospeed`, `cc`,
+      corresponding to the list entries defined by the `termios.tcgetattr`
+      call.
+
+      For `set_modes`, the attributes `ispeed`, `ospeed` and `cc`
+      are applied directly;
+      the other attributes are binary ORed into the existing modes.
+
+      For `clear_modes`, the attributes `ispeed`, `ospeed` and `cc`
+      cannot be cleared;
+      the other attributes are binary removed from the existing modes.
+
+      For example, to turn off the terminal echo during some operation:
+
+          with stack_termios(clear_modes={'lflag': termios.ECHO}):
+              ... do something with tty echo disabled ...
+  '''
+  try:
+    restore_modes = modify_termios(
+        fd, set_modes=set_modes, clear_modes=clear_modes, strict=strict
+    )
+    yield restore_modes
+  finally:
+    if restore_modes:
+      try:
+        tcsetattr(fd, TCSANOW, restore_modes)
+      except OSError as e:
+        if strict:
+          raise
+        warning("tcsetattr(%d,TCSANOW,%r): %e", fd, restore_modes, e)