API Break, version bump to 3.0 - reverted default getch() behaviour to again

return single char as in 2.0.
Added getchars() func that always returns list

(it calls getch() that got new internal _getall parameter).

README.rst

@@ -21,11 +21,15 @@ Demo
 
 Status
 ------
+3.0 (stable) - API break in getch() function
+ - reverted getch() behaviour changed in 2.0 - now
+   getch() again returns single char
+ - new getchars() function that always returns list
+
 2.1 (stable)
  - split getch() into _getch_unix() and _getch_windows()
    and detect correct flavor at import time (speedup)
-
+2.0 (stable) - API break in getch() function
-2.0 (stable) - API Break in getch() function
  - getch() now always returns list of characters
    (previously it could return single char). This is done
    to simplify the task of detecting keys from the
@@ -95,15 +99,25 @@ API (input)
 
 ..function:: **getch()**
 
-  Wait for keypress(es). Return list of characters generated as a
+  Wait for keypress, return first char generated as a result.
-  result. Arrows and special keys generate such sequence after a single
+
-  keypress. Sequences may differ between platforms, so make sure to use
+  Arrows and special keys generate sequence of chars. Use `getchars`
-  constants defined in this module to recognize keys back.
+  function to receive all chars generated or present in buffer.
+
+
+..function:: **getchars()**
+
+  Wait for keypress. Return list of chars generated as a result.
+  More than one char in result list is returned when arrows and
+  special keys are pressed. Returned sequences differ between
+  platforms, so use constants defined in this module to guess
+  correct keys.
 
 
 ..function:: **dumpkey(key)**
 
-  Return hexadecimal representation of a key value returned by getch().
+  Helper to convert result of `getch` (string) or `getchars` (list)
+  to hex string.
 
 
 Credits

pager.py

@@ -14,7 +14,7 @@ Author:  anatoly techtonik <techtonik@gmail.com>
 License: Public Domain (use MIT if the former doesn't work for you)
 """
 
-__version__ = '2.1'
+__version__ = '3.0'
 
 import os,sys
 
@@ -156,7 +156,8 @@ ESC = ['\x1b']
 
 def dumpkey(key):
     """
-    Helper to convert a list (returned from getch()) or string to hex string.
+    Helper to convert result of `getch` (string) or `getchars` (list)
+    to hex string.
     """
     def hex3fy(key):
         """Helper to convert string into hex string (Python 3 compatible)"""
@@ -180,22 +181,26 @@ if WINDOWS:
     else:
         from msvcrt import kbhit, getch as __getchw
 
-def _getch_windows():
+def _getch_windows(_getall=False):
-    chars = []
     chars = [__getchw()]  # wait for the keypress
-    while kbhit():      # deplete input buffer
+    if _getall:           # read everything, return list
+        while kbhit():
             chars.append(__getchw())
         return chars
+    else:
+        return chars[0]
 
 
-def _getch_unix():  # [ ] _getch_linux()? (test on FreeBSD and MacOS)
+# [ ] _getch_linux() or _getch_posix()? (test on FreeBSD and MacOS)
+def _getch_unix(_getall=False):
     """
     # --- current algorithm ---
     # 1. switch to char-by-char input mode
     # 2. turn off echo
     # 3. wait for at least one char to appear
-    # 4. read the rest of the character buffer
+    # 4. read the rest of the character buffer (_getall=True)
-    # 5. return list of characters
+    # 5. return list of characters (_getall on)
+    #        or a single char (_getall off)
     """
     import sys, termios
 
@@ -222,6 +227,7 @@ def _getch_unix():  # [ ] _getch_linux()? (test on FreeBSD and MacOS)
         ch = sys.stdin.read(1)
         chars = [ch]
 
+        if _getall:
             # move rest of chars (if any) from input buffer
             # change terminal settings - enable non-blocking read
             newattr = termios.tcgetattr(fd)
@@ -239,7 +245,11 @@ def _getch_unix():  # [ ] _getch_linux()? (test on FreeBSD and MacOS)
         # restore terminal settings. Do this when all output is
         # finished - TCSADRAIN flag
         termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+
+    if _getall:
         return chars
+    else:
+        return chars[0]
 
 
 # choose correct getch function at module import time
@@ -250,11 +260,10 @@ else:
 
 getch.__doc__ = \
     """
-    Wait for keypress(es), return list of chars generated as a result.
+    Wait for keypress, return first char generated as a result.
 
-    Arrows and special keys generate such sequence after a single
+    Arrows and special keys generate sequence of chars. Use `getchars`
-    keypress. Sequences may differ between platforms, so make sure to
+    function to receive all chars generated or present in buffer.
-    use constants defined in this module to recognize keys back.
     """
 
     # check that Ctrl-C and Ctrl-Break break this function
@@ -263,6 +272,19 @@ getch.__doc__ = \
     # Ctrl-Break   [y] Windows  [n] Linux  [ ] OSX
 
 
+# [ ] check if getchars returns chars already present in buffer
+#     before the call to this function
+def getchars():
+    """
+    Wait for keypress. Return list of chars generated as a result.
+    More than one char in result list is returned when arrows and
+    special keys are pressed. Returned sequences differ between
+    platforms, so use constants defined in this module to guess
+    correct keys.
+    """
+    return getch(_getall=True)
+    
+
 def echo(msg):
     """
     Print msg to the screen without linefeed and flush the output.