Release 2.0

README.rst

@@ -22,6 +22,12 @@ Demo
 Status
 ------
 
+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
+   returned result
+
 1.4 (stable)
  - pager.py <file>
  - Linux: termios comments, docs and preparation for very
@@ -53,8 +59,20 @@ Status
  - works on Linux
 
 
-API
----
+API (output)
+------------
+
+..function:: **page(content, [pagecallback=prompt])**
+
+  Output `content` iterable, calling `pagecallback` function after each
+  page with page number as a parameter. Default `prompt()` callback shows
+  page number with 'Press any key . . . ' prompt and waits for keypress.
+
+
+..function:: **echo(msg)**
+
+  Print msg to the screen without linefeed and flush the output.
+
 
 ..function:: **getwidth()**
 
@@ -69,29 +87,29 @@ API
   Coordinate of the last line is -1 from returned value. 
 
 
+API (input)
+------------
+
 ..function:: **getch()**
 
-  Wait for keypress and return character or a list of characters. Arrows
-  and special keys generate a sequence of characters, so if there are
-  extra symbols in input buffer, this function returns list.
+  Wait for keypress(es). Return list of characters generated as a
+  result. Arrows and special keys generate such sequence after a single
+  keypress. Sequences may differ between platforms, so make sure to use
+  constants defined in this module to recognize keys back.
 
 
-..function:: **page(content, [pagecallback=prompt])**
-
-  Output `content` iterable, calling `pagecallback` function after each
-  page with page number as a parameter. Default `prompt()` callback shows
-  page number with 'Press any key . . . ' prompt and waits for keypress.
-
-
-..function:: **echo(msg)**
-
-  Print msg to the screen without linefeed and flush the output.
-
 ..function:: **dumpkey(key)**
 
   Return hexadecimal representation of a key value returned by getch().
 
 
+Credits
+-------
+
+Danny Yoo for getch()-like unbuffered character reading recipe
+http://code.activestate.com/recipes/134892-getch-like-unbuffered/
+
+
 References
 ----------
 

pager.py

@@ -14,7 +14,7 @@ Author:  anatoly techtonik <techtonik@gmail.com>
 License: Public Domain (use MIT if Public Domain doesn't work for you)
 """
 
-__version__ = '2.0dev'
+__version__ = '2.0'
 
 import os,sys
 
@@ -154,8 +154,7 @@ ESC = ['\x1b']
 
 def dumpkey(key):
     """
-    Helper to convert value returned from getch() (which can be list or
-    a string) to hex string.
+    Helper to convert a list (returned from getch()) or string to hex string.
     """
     def hex3fy(key):
         """Helper to convert string into hex string (Python 3 compatible)"""
@@ -172,7 +171,6 @@ def dumpkey(key):
     else:
         return ' '.join( [hex3fy(s) for s in key] )
 
-# [ ] recognize multiple-character sequences such as arrow keys
 def getch():
     """
     Wait for keypress(es), return list of chars generated as a result.
@@ -184,8 +182,8 @@ def getch():
 
     # check that Ctrl-C and Ctrl-Break break this function
     #
-    # Ctrl-C       [n] Windows  [ ] Linux
-    # Ctrl-Break   [y] Windows  [ ] Linux
+    # Ctrl-C       [n] Windows  [y] Linux  [ ] OSX
+    # Ctrl-Break   [y] Windows  [n] Linux  [ ] OSX
 
     chars = []
     try:
@@ -452,6 +450,8 @@ def _manual_test_getch():
 
 
 
+# [ ] recognize multiple-character sequences such as arrow keys
+
 if __name__ == '__main__':
     # check if pager.py is running in interactive mode
     # (without stdin redirection)