Index: Lib/lib-tk/turtle.py
===================================================================
--- Lib/lib-tk/turtle.py	(revision 86166)
+++ Lib/lib-tk/turtle.py	(working copy)
@@ -752,10 +752,11 @@
     def _pointlist(self, item):
         """returns list of coordinate-pairs of points of item
         Example (for insiders):
-        >>> from turtle import *
-        >>> getscreen()._pointlist(getturtle().turtle._item)
+        >>> from turtle import *                             # doctest: +SKIP
+        >>> getscreen()._pointlist(getturtle().turtle._item) # doctest: +SKIP
         [(0.0, 9.9999999999999982), (0.0, -9.9999999999999982),
         (9.9999999999999982, 0.0)]
+
         >>> """
         cl = self.cv.coords(item)
         pl = [(cl[i], -cl[i+1]) for i in range(0, len(cl), 2)]
@@ -859,6 +860,7 @@
         >>> poly = ((0,0),(10,-5),(0,10),(-10,-5))
         >>> s = Shape("compound")
         >>> s.addcomponent(poly, "red", "blue")
+
         ### .. add more components and then use register_shape()
         """
         if self._type != "compound":
@@ -1030,8 +1032,8 @@
         Example (for a TurtleScreen instance named screen):
         >>> screen.setworldcoordinates(-10,-0.5,50,1.5)
         >>> for _ in range(36):
-                left(10)
-                forward(0.5)
+        ...     left(10)
+        ...     forward(0.5)
         """
         if self.mode() != "world":
             self.mode("world")
@@ -1133,6 +1135,7 @@
         r, g, b values of colortriples have to be in range 0..cmode.
 
         Example (for a TurtleScreen instance named screen):
+        >>> screen.colormode(1)
         >>> screen.colormode()
         1.0
         >>> screen.colormode(255)
@@ -1162,7 +1165,7 @@
 
         Example (for a TurtleScreen instance named screen):
         >>> screen.turtles()
-        [<turtle.Turtle object at 0x00E11FB0>]
+        [<...Turtle object at 0x...>, ...]
         """
         return self._turtles
 
@@ -1176,9 +1179,10 @@
         >>> screen.bgcolor("orange")
         >>> screen.bgcolor()
         'orange'
-        >>> screen.bgcolor(0.5,0,0.5)
+        >>> screen.colormode(255)
+        >>> screen.bgcolor(80,0,80)
         >>> screen.bgcolor()
-        '#800080'
+        (80, 0, 80)
         """
         if args:
             color = self._colorstr(args)
@@ -1202,11 +1206,9 @@
 
         Example (for a TurtleScreen instance named screen):
         >>> screen.tracer(8, 25)
-        >>> dist = 2
-        >>> for i in range(200):
-                fd(dist)
-                rt(90)
-                dist += 2
+        >>> for dist in range(2, 202, 2):
+        ...     fd(dist)
+        ...     rt(90)
         """
         if n is None:
             return self._tracing
@@ -1256,8 +1258,7 @@
         """ Return the width of the turtle window.
 
         Example (for a TurtleScreen instance named screen):
-        >>> screen.window_width()
-        640
+        >>> w = screen.window_width()
         """
         return self._window_size()[0]
 
@@ -1265,8 +1266,7 @@
         """ Return the height of the turtle window.
 
         Example (for a TurtleScreen instance named screen):
-        >>> screen.window_height()
-        480
+        >>> h = screen.window_height()
         """
         return self._window_size()[1]
 
@@ -1278,7 +1278,7 @@
         Example (for a Screen instance named screen):
         >>> cv = screen.getcanvas()
         >>> cv
-        <turtle.ScrolledCanvas instance at 0x010742D8>
+        <...ScrolledCanvas instance at 0x...>
         """
         return self.cv
 
@@ -1289,7 +1289,7 @@
 
         Example (for a TurtleScreen instance named screen):
         >>> screen.getshapes()
-        ['arrow', 'blank', 'circle', ... , 'turtle']
+        ['arrow', 'blank', 'circle', ..., 'turtle']
         """
         return sorted(self._shapes.keys())
 
@@ -1328,10 +1328,9 @@
         and a Turtle instance named turtle):
 
         >>> def f():
-                fd(50)
-                lt(60)
+        ...     fd(50)
+        ...     lt(60)
 
-
         >>> screen.onkey(f, "Up")
         >>> screen.listen()
 
@@ -1369,12 +1368,12 @@
 
         >>> running = True
         >>> def f():
-                if running:
-                        fd(50)
-                        lt(60)
-                        screen.ontimer(f, 250)
+        ...    if f.running:
+        ...        fd(50)
+        ...        lt(60)
+        ...        screen.ontimer(f, 250)
 
-        >>> f()   ### makes the turtle marching around
+        >>> f()   ### makes the turtle marching around # doctest: +SKIP
         >>> running = False
         """
         self._ontimer(fun, t)
@@ -1392,8 +1391,8 @@
         Example (for a TurtleScreen instance named screen):
         >>> screen.bgpic()
         'nopic'
-        >>> screen.bgpic("landscape.gif")
-        >>> screen.bgpic()
+        >>> screen.bgpic("landscape.gif")             # doctest: +SKIP
+        >>> screen.bgpic()                            # doctest: +SKIP
         'landscape.gif'
         """
         if picname is None:
@@ -1417,7 +1416,8 @@
         of a drawing, which were outside the canvas before!)
 
         Example (for a Turtle instance named turtle):
-        >>> turtle.screensize(2000,1500)
+        >>> screen.screensize(2000,1500)
+
             ### e. g. to search for an erroneously escaped turtle ;-)
         """
         return self._resize(canvwidth, canvheight, bg)
@@ -1494,10 +1494,10 @@
         Example (for a Turtle instance named turtle):
         >>> turtle.left(90)
         >>> turtle.heading()
-        90
+        90.0
         >>> turtle.degrees(400.0)  # angle measurement in gon
         >>> turtle.heading()
-        100
+        100.0
 
         """
         self._setDegreesPerAU(fullcircle)
@@ -1508,8 +1508,9 @@
         No arguments.
 
         Example (for a Turtle instance named turtle):
+        >>> turtle.setheading(90)
         >>> turtle.heading()
-        90
+        90.0
         >>> turtle.radians()
         >>> turtle.heading()
         1.5707963267948966
@@ -1543,7 +1544,7 @@
 
         Example (for a Turtle instance named turtle):
         >>> turtle.position()
-        (0.00, 0.00)
+        (0.00,0.00)
         >>> turtle.forward(25)
         >>> turtle.position()
         (25.00,0.00)
@@ -1566,10 +1567,10 @@
 
         Example (for a Turtle instance named turtle):
         >>> turtle.position()
-        (0.00, 0.00)
+        (0.00,0.00)
         >>> turtle.backward(30)
         >>> turtle.position()
-        (-30.00, 0.00)
+        (-30.00,0.00)
         """
         self._go(-distance)
 
@@ -1586,6 +1587,7 @@
         Angle orientation depends on mode. (See this.)
 
         Example (for a Turtle instance named turtle):
+        >>> turtle.setheading(22)
         >>> turtle.heading()
         22.0
         >>> turtle.right(45)
@@ -1607,6 +1609,7 @@
         Angle orientation depends on mode. (See this.)
 
         Example (for a Turtle instance named turtle):
+        >>> turtle.setheading(22)
         >>> turtle.heading()
         22.0
         >>> turtle.left(45)
@@ -1623,8 +1626,9 @@
         No arguments.
 
         Example (for a Turtle instance named turtle):
+        >>> turtle.goto(0, 240)
         >>> turtle.pos()
-        (0.00, 240.00)
+        (0.00,240.00)
         """
         return self._position
 
@@ -1676,7 +1680,7 @@
         Example (for a Turtle instance named turtle):
         >>> tp = turtle.pos()
         >>> tp
-        (0.00, 0.00)
+        (0.00,0.00)
         >>> turtle.setpos(60,30)
         >>> turtle.pos()
         (60.00,30.00)
@@ -1716,11 +1720,12 @@
         unchanged.
 
         Example (for a Turtle instance named turtle):
+        >>> turtle.goto(0, 240)
         >>> turtle.position()
-        (0.00, 240.00)
+        (0.00,240.00)
         >>> turtle.setx(10)
         >>> turtle.position()
-        (10.00, 240.00)
+        (10.00,240.00)
         """
         self._goto(Vec2D(x, self._position[1]))
 
@@ -1734,11 +1739,12 @@
         unchanged.
 
         Example (for a Turtle instance named turtle):
+        >>> turtle.goto(0, 40)
         >>> turtle.position()
-        (0.00, 40.00)
+        (0.00,40.00)
         >>> turtle.sety(-10)
         >>> turtle.position()
-        (0.00, -10.00)
+        (0.00,-10.00)
         """
         self._goto(Vec2D(self._position[0], y))
 
@@ -1756,7 +1762,7 @@
 
         Example (for a Turtle instance named turtle):
         >>> turtle.pos()
-        (0.00, 0.00)
+        (0.00,0.00)
         >>> turtle.distance(30,40)
         50.0
         >>> pen = Turtle()
@@ -1791,8 +1797,9 @@
         modes - "standard" or "logo")
 
         Example (for a Turtle instance named turtle):
+        >>> turtle.goto(10, 10)
         >>> turtle.pos()
-        (10.00, 10.00)
+        (10.00,10.00)
         >>> turtle.towards(0,0)
         225.0
         """
@@ -1845,7 +1852,7 @@
         Example (for a Turtle instance named turtle):
         >>> turtle.setheading(90)
         >>> turtle.heading()
-        90
+        90.0
         """
         angle = (to_angle - self.heading())*self._angleOrient
         full = self._fullcircle
@@ -2001,7 +2008,9 @@
         Example (for a Turtle instance named turtle):
         >>> turtle.pensize()
         1
-        turtle.pensize(10)   # from here on lines of width 10 are drawn
+        >>> turtle.pensize(10)   # from here on lines of width 10 are drawn
+        >>> turtle.pensize()
+        10
         """
         if width is None:
             return self._pensize
@@ -2116,10 +2125,10 @@
         >>> turtle.color('red', 'green')
         >>> turtle.color()
         ('red', 'green')
-        >>> colormode(255)
-        >>> color((40, 80, 120), (160, 200, 240))
-        >>> color()
-        ('#285078', '#a0c8f0')
+        >>> turtle.screen.colormode(255)
+        >>> turtle.color((40, 80, 120), (160, 200, 240))
+        >>> turtle.color()
+        ((40, 80, 120), (160, 200, 240))
         """
         if args:
             l = len(args)
@@ -2159,10 +2168,12 @@
 
         Example (for a Turtle instance named turtle):
         >>> turtle.pencolor('brown')
+        >>> turtle.screen.colormode(1)
         >>> tup = (0.2, 0.8, 0.55)
         >>> turtle.pencolor(tup)
+        >>> turtle.screen.colormode(255)
         >>> turtle.pencolor()
-        '#33cc8c'
+        (51, 204, 140)
         """
         if args:
             color = self._colorstr(args)
@@ -2244,7 +2255,7 @@
 
         Example (for a Turtle instance named turtle):
         >>> turtle.hideturtle()
-        >>> print turtle.isvisible():
+        >>> print turtle.isvisible()
         False
         """
         return self._shown
@@ -2278,22 +2289,16 @@
 
         Examples (for a Turtle instance named turtle):
         >>> turtle.pen(fillcolor="black", pencolor="red", pensize=10)
-        >>> turtle.pen()
-        {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1,
-        'pencolor': 'red', 'pendown': True, 'fillcolor': 'black',
-        'stretchfactor': (1,1), 'speed': 3}
-        >>> penstate=turtle.pen()
+        >>> sorted(turtle.pen().items())[:5]
+        [('fillcolor', 'black'), ..., ('pencolor', 'red'), ..., ('pensize', 10)]
+        >>> penstate = turtle.pen()
         >>> turtle.color("yellow","")
         >>> turtle.penup()
-        >>> turtle.pen()
-        {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1,
-        'pencolor': 'yellow', 'pendown': False, 'fillcolor': '',
-        'stretchfactor': (1,1), 'speed': 3}
-        >>> p.pen(penstate, fillcolor="green")
-        >>> p.pen()
-        {'pensize': 10, 'shown': True, 'resizemode': 'auto', 'outline': 1,
-        'pencolor': 'red', 'pendown': True, 'fillcolor': 'green',
-        'stretchfactor': (1,1), 'speed': 3}
+        >>> sorted(turtle.pen().items())[:3]
+        [('fillcolor', ''), ('outline', 1), ('pencolor', 'yellow')]
+        >>> turtle.pen(penstate, fillcolor="green")
+        >>> sorted(turtle.pen().items())[:3]
+        [('fillcolor', 'green'), ('outline', 1), ('pencolor', 'red')]
         """
         _pd =  {"shown"         : self._shown,
                 "pendown"       : self._drawing,
@@ -2471,6 +2476,8 @@
         and set variables to the default values.
 
         Example (for a Turtle instance named turtle):
+        >>> turtle.goto(0, -22)
+        >>> turtle.setheading(100)
         >>> turtle.position()
         (0.00,-22.00)
         >>> turtle.heading()
@@ -2512,8 +2519,8 @@
         No argument.
 
         Example (for a Turtle instance named turtle):
-        >>> while undobufferentries():
-                undo()
+        >>> while turtle.undobufferentries():
+        ...     turtle.undo()
         """
         if self.undobuffer is None:
             return 0
@@ -2574,7 +2581,7 @@
                     t._drawturtle()
                 screen._update()
 
-    def tracer(self, flag=None, delay=None):
+    def tracer(self, n=None, delay=None):
         """Turns turtle animation on/off and set delay for update drawings.
 
         Optional arguments:
@@ -2587,13 +2594,11 @@
 
         Example (for a Turtle instance named turtle):
         >>> turtle.tracer(8, 25)
-        >>> dist = 2
-        >>> for i in range(200):
-                turtle.fd(dist)
-                turtle.rt(90)
-                dist += 2
+        >>> for dist in range(2, 200):
+        ...     turtle.fd(dist)
+        ...     turtle.rt(90)
         """
-        return self.screen.tracer(flag, delay)
+        return self.screen.tracer(n, delay)
 
     def _color(self, args):
         return self.screen._color(args)
@@ -2671,7 +2676,7 @@
 
         Example (for a Turtle instance named turtle):
         >>> turtle.shape()
-        'arrow'
+        'classic'
         >>> turtle.shape("turtle")
         >>> turtle.shape()
         'turtle'
@@ -2736,10 +2741,10 @@
         >>> turtle.shape("circle")
         >>> turtle.shapesize(5,2)
         >>> turtle.settiltangle(45)
-        >>> stamp()
+        >>> id = stamp()
         >>> turtle.fd(50)
         >>> turtle.settiltangle(-45)
-        >>> stamp()
+        >>> id = stamp()
         >>> turtle.fd(50)
         """
         tilt = -angle * self._degreesPerAU * self._angleOrient
@@ -2760,6 +2765,7 @@
         >>> turtle.shapesize(5,2)
         >>> turtle.tilt(45)
         >>> turtle.tiltangle()
+        45.0
         >>>
         """
         tilt = -self._tilt * (180.0/math.pi) * self._angleOrient
@@ -2862,8 +2868,7 @@
 
         Example (for a Turtle instance named turtle):
         >>> turtle.color("blue")
-        >>> turtle.stamp()
-        13
+        >>> id = turtle.stamp()
         >>> turtle.fd(50)
         """
         screen = self.screen
@@ -2960,8 +2965,9 @@
 
         Example (for a Turtle instance named turtle):
         >>> for i in range(8):
-                turtle.stamp(); turtle.fd(30)
-        ...
+        ...     id = turtle.stamp(); turtle.fd(30)
+        >>> id in turtle.stampItems
+        True
         >>> turtle.clearstamps(2)
         >>> turtle.clearstamps(-2)
         >>> turtle.clearstamps()
@@ -3338,8 +3344,11 @@
         No argument.
 
         Example (for a Turtle instance named turtle):
+        >>> turtle.begin_poly()
+        >>> turtle.circle(100, 5) # draw a pentagon
+        >>> turtle.end_poly()
         >>> p = turtle.get_poly()
-        >>> turtle.register_shape("myFavouriteShape", p)
+        >>> screen.register_shape("myFavouriteShape", p)
         """
         ## check if there is any poly?  -- 1st solution:
         if self._poly is not None:
@@ -3356,7 +3365,7 @@
         Example (for a Turtle instance named turtle):
         >>> ts = turtle.getscreen()
         >>> ts
-        <turtle.TurtleScreen object at 0x0106B770>
+        <...Screen object at 0x...>
         >>> ts.bgcolor("pink")
         """
         return self.screen
@@ -3372,9 +3381,9 @@
         >>> pet = getturtle()
         >>> pet.fd(50)
         >>> pet
-        <turtle.Turtle object at 0x0187D810>
+        <...Turtle object at 0x...>
         >>> turtles()
-        [<turtle.Turtle object at 0x0187D810>]
+        [<...Turtle object at 0x...>]
         """
         return self
 
@@ -3391,8 +3400,7 @@
         No argument.
 
         Example (for a TurtleScreen instance named screen):
-        >>> screen.window_width()
-        640
+        >>> w = screen.window_width()
         """
         return self.screen._window_size()[0]
 
@@ -3402,8 +3410,7 @@
         No argument.
 
         Example (for a TurtleScreen instance named screen):
-        >>> screen.window_height()
-        480
+        >>> h = screen.window_height()
         """
         return self.screen._window_size()[1]
 
@@ -3427,7 +3434,7 @@
         Example for the anonymous turtle, i. e. the procedural way:
 
         >>> def turn(x, y):
-                left(360)
+        ...     left(360)
 
         >>> onclick(turn) # Now clicking into the turtle will turn it.
         >>> onclick(None)  # event-binding will be removed
@@ -3445,14 +3452,15 @@
 
         Example (for a MyTurtle instance named joe):
         >>> class MyTurtle(Turtle):
-                def glow(self,x,y):
-                        self.fillcolor("red")
-                def unglow(self,x,y):
-                        self.fillcolor("")
+        ...     def glow(self,x,y):
+        ...             self.fillcolor("red")
+        ...     def unglow(self,x,y):
+        ...             self.fillcolor("")
 
         >>> joe = MyTurtle()
         >>> joe.onclick(joe.glow)
         >>> joe.onrelease(joe.unglow)
+
         ### clicking on joe turns fillcolor red,
         ### unclicking turns it to transparent.
         """
@@ -3471,7 +3479,7 @@
         mouse-click event on that turtle.
 
         Example (for a Turtle instance named turtle):
-        >>> turtle.ondrag(turtle.goto)
+        >>> turtle.ondrag(turtle.goto)                 # doctest: +SKIP
 
         ### Subsequently clicking and dragging a Turtle will
         ### move it across the screen thereby producing handdrawings
@@ -3522,10 +3530,10 @@
 
         Example (for a Turtle instance named turtle):
         >>> for i in range(4):
-                turtle.fd(50); turtle.lt(80)
+        ...     turtle.fd(50); turtle.lt(80)
 
         >>> for i in range(8):
-                turtle.undo()
+        ...     turtle.undo()
         """
         if self.undobuffer is None:
             return
@@ -3598,11 +3606,11 @@
           Default, starty=None is to center window vertically.
 
         Examples (for a Screen instance named screen):
-        >>> screen.setup (width=200, height=200, startx=0, starty=0)
+        >>> screen.setup(width=200, height=200, startx=0, starty=0)       # doctest: +SKIP
 
         sets window to 200x200 pixels, in upper left of screen
 
-        >>> screen.setup(width=.75, height=0.5, startx=None, starty=None)
+        >>> screen.setup(width=.75, height=0.5, startx=None, starty=None) # doctest: +SKIP
 
         sets window to 75% of screen by 50% of screen and centers
         """
@@ -3672,7 +3680,7 @@
         TurtleScreen instances.
 
         Example (for a Screen instance named screen):
-        >>> screen.exitonclick()
+        >>> screen.exitonclick()                            # doctest: +SKIP
 
         """
         def exitGracefully(x, y):
@@ -3829,7 +3837,7 @@
     turtlename = _CFG["exampleturtle"]
     newdocstr = docstr.replace("%s." % turtlename,"")
     parexp = re.compile(r' \(.+ %s\):' % turtlename)
-    newdocstr = parexp.sub(":", newdocstr)
+    newdocstr = parexp.sub(":", newdocstr).replace('>>>', '->>')
     return newdocstr
 
 def _screen_docrevise(docstr):
@@ -3841,7 +3849,7 @@
     screenname = _CFG["examplescreen"]
     newdocstr = docstr.replace("%s." % screenname,"")
     parexp = re.compile(r' \(.+ %s\):' % screenname)
-    newdocstr = parexp.sub(":", newdocstr)
+    newdocstr = parexp.sub(":", newdocstr).replace('>>>', '->>')
     return newdocstr
 
 ## The following mechanism makes all methods of RawTurtle and Turtle available
@@ -3873,6 +3881,22 @@
 done = mainloop = TK.mainloop
 del pl1, pl2, defstr
 
+def run_doctests():
+    import doctest
+    import turtle as module
+    class Globs(dict):
+        def copy(self):
+            turtle = module.Turtle()
+            turtlename = _CFG["exampleturtle"]
+            screenname = _CFG["examplescreen"]
+            globs = Globs(module.__dict__)
+            globs[turtlename] = turtle
+            globs[screenname] = turtle.screen
+            turtle.screen.clear()
+            return globs
+
+    doctest.testmod(module, globs=Globs(), optionflags=doctest.ELLIPSIS)
+
 if __name__ == "__main__":
     def switchpen():
         if isdown():