Harmonize docstrings. Move redemo from Tools/scripts to Tools/demo. A…

…dd a README file to Tools/demo.

demo/README

@@ -0,0 +1,16 @@
+This directory contains a collection of demonstration scripts for
+various aspects of Python programming.
+
+beer.py        Well-known programming example: Bottles of beer.
+eiffel.py      Python advanced magic: A metaclass for Eiffel post/preconditions.
+hanoi.py       Well-known programming example: Towers of Hanoi.
+life.py        Curses programming: Simple game-of-life.
+markov.py      Algorithms: Markov chain simulation.
+mcast.py       Network programming: Send and receive UDP multicast packets.
+queens.py      Well-known programming example: N-Queens problem.
+redemo.py      Regular Expressions: GUI script to test regexes.
+rpython.py     Network programming: Small client for remote code execution.
+rpythond.py    Network programming: Small server for remote code execution.
+sortvisu.py    GUI programming: Visualization of different sort algorithms.
+ss1.py         GUI/Application programming: A simple spreadsheet application.
+vector.py      Python basics: A vector class with demonstrating special methods.

demo/beer.py

@@ -1,6 +1,11 @@
-#! /usr/bin/env python3
+#!/usr/bin/env python3
 
-# By GvR, demystified after a version by Fredrik Lundh.
+"""
+A Python version of the classic "bottles of beer on the wall" programming
+example.
+
+By Guido van Rossum, demystified after a version by Fredrik Lundh.
+"""
 
 import sys
 

demo/Eiffel.py → demo/eiffel.py

@@ -1,13 +1,20 @@
-"""Support Eiffel-style preconditions and postconditions."""
+#!/usr/bin/env python3
 
+"""
+Support Eiffel-style preconditions and postconditions for functions.
+
+An example for Python metaclasses.
+"""
+
+import unittest
 from types import FunctionType as function
 
 class EiffelBaseMetaClass(type):
 
     def __new__(meta, name, bases, dict):
         meta.convert_methods(dict)
-        return super(EiffelBaseMetaClass, meta).__new__(meta, name, bases,
-                                                        dict)
+        return super(EiffelBaseMetaClass, meta).__new__(
+            meta, name, bases, dict)
 
     @classmethod
     def convert_methods(cls, dict):
@@ -31,6 +38,7 @@ def convert_methods(cls, dict):
             if pre or post:
                 dict[k] = cls.make_eiffel_method(dict[m], pre, post)
 
+
 class EiffelMetaClass1(EiffelBaseMetaClass):
     # an implementation of the "eiffel" meta class that uses nested functions
 
@@ -39,16 +47,17 @@ def make_eiffel_method(func, pre, post):
         def method(self, *args, **kwargs):
             if pre:
                 pre(self, *args, **kwargs)
-            x = func(self, *args, **kwargs)
+            rv = func(self, *args, **kwargs)
             if post:
-                post(self, x, *args, **kwargs)
-            return x
+                post(self, rv, *args, **kwargs)
+            return rv
 
         if func.__doc__:
             method.__doc__ = func.__doc__
 
         return method
 
+
 class EiffelMethodWrapper:
 
     def __init__(self, inst, descr):
@@ -58,7 +67,8 @@ def __init__(self, inst, descr):
     def __call__(self, *args, **kwargs):
         return self._descr.callmethod(self._inst, args, kwargs)
 
-class EiffelDescriptor(object):
+
+class EiffelDescriptor:
 
     def __init__(self, func, pre, post):
         self._func = func
@@ -79,63 +89,58 @@ def callmethod(self, inst, args, kwargs):
             self._post(inst, x, *args, **kwargs)
         return x
 
+
 class EiffelMetaClass2(EiffelBaseMetaClass):
     # an implementation of the "eiffel" meta class that uses descriptors
 
     make_eiffel_method = EiffelDescriptor
 
-def _test(metaclass):
-    class Eiffel(metaclass=metaclass):
-        pass
-
-    class Test(Eiffel):
-
-        def m(self, arg):
-            """Make it a little larger"""
-            return arg + 1
-
-        def m2(self, arg):
-            """Make it a little larger"""
-            return arg + 1
-
-        def m2_pre(self, arg):
-            assert arg > 0
-
-        def m2_post(self, result, arg):
-            assert result > arg
-
-    class Sub(Test):
-        def m2(self, arg):
-            return arg**2
-        def m2_post(self, Result, arg):
-            super(Sub, self).m2_post(Result, arg)
-            assert Result < 100
-
-    t = Test()
-    t.m(1)
-    t.m2(1)
-    try:
-        t.m2(0)
-    except AssertionError:
-        pass
-    else:
-        assert False
-
-    s = Sub()
-    try:
-        s.m2(1)
-    except AssertionError:
-        pass # result == arg
-    else:
-        assert False
-    try:
-        s.m2(10)
-    except AssertionError:
-        pass # result ==  100
-    else:
-        assert False
-    s.m2(5)
+
+class Tests(unittest.TestCase):
+
+    def testEiffelMetaClass1(self):
+        self._test(EiffelMetaClass1)
+
+    def testEiffelMetaClass2(self):
+        self._test(EiffelMetaClass2)
+
+    def _test(self, metaclass):
+        class Eiffel(metaclass=metaclass):
+            pass
+
+        class Test(Eiffel):
+            def m(self, arg):
+                """Make it a little larger"""
+                return arg + 1
+
+            def m2(self, arg):
+                """Make it a little larger"""
+                return arg + 1
+
+            def m2_pre(self, arg):
+                assert arg > 0
+
+            def m2_post(self, result, arg):
+                assert result > arg
+
+        class Sub(Test):
+            def m2(self, arg):
+                return arg**2
+
+            def m2_post(self, Result, arg):
+                super(Sub, self).m2_post(Result, arg)
+                assert Result < 100
+
+        t = Test()
+        self.assertEqual(t.m(1), 2)
+        self.assertEqual(t.m2(1), 2)
+        self.assertRaises(AssertionError, t.m2, 0)
+
+        s = Sub()
+        self.assertRaises(AssertionError, s.m2, 1)
+        self.assertRaises(AssertionError, s.m2, 10)
+        self.assertEqual(s.m2(5), 25)
+
 
 if __name__ == "__main__":
-    _test(EiffelMetaClass1)
-    _test(EiffelMetaClass2)
+    unittest.main()

demo/hanoi.py

@@ -1,17 +1,18 @@
-# Animated Towers of Hanoi using Tk with optional bitmap file in
-# background.
-#
-# Usage: tkhanoi [n [bitmapfile]]
-#
-# n is the number of pieces to animate; default is 4, maximum 15.
-#
-# The bitmap file can be any X11 bitmap file (look in
-# /usr/include/X11/bitmaps for samples); it is displayed as the
-# background of the animation.  Default is no bitmap.
+#!/usr/bin/env python3
 
-# This uses Steen Lumholt's Tk interface
-from tkinter import *
+"""
+Animated Towers of Hanoi using Tk with optional bitmap file in background.
 
+Usage: hanoi.py [n [bitmapfile]]
+
+n is the number of pieces to animate; default is 4, maximum 15.
+
+The bitmap file can be any X11 bitmap file (look in /usr/include/X11/bitmaps for
+samples); it is displayed as the background of the animation.  Default is no
+bitmap.
+"""
+
+from tkinter import Tk, Canvas
 
 # Basic Towers-of-Hanoi algorithm: move n pieces from a to b, using c
 # as temporary.  For each move, call report()
@@ -123,7 +124,6 @@ def report(self, i, a, b):
         self.pegstate[b].append(i)
 
 
-# Main program
 def main():
     import sys