[docs] [issue22122] turtle module examples should all begin "from turtle import *"

Terry J. Reedy report at bugs.python.org
Sat Aug 2 23:24:18 CEST 2014

Terry J. Reedy added the comment:

I think your suggestion is wrong as is and that this issue should be revised or closed.  The simple initial example is a complete program. PEP8 discourages 'import *' but it is acceptable in this context. The snippets you refer to follow

"24.1.3. Methods of RawTurtle/Turtle and corresponding functions

Most of the examples in this section refer to a Turtle instance called turtle."

Methods are always documented as method calls, and they should be here too. The function interface can only be used for 1 turtle, while drawings often require more than 1.  See turtledemo for examples such as 'forest', which uses 3 Turtle instances.

Nothing says that users have to name an instance 'turtle'.  In practice one might use 't1', 't2', etc, or other short names.  Within a subclass of Turtle, with added methods, the prefix would be 'self.'. The quote above could be, and perhaps should be augmented with a reminder that "If one uses the function interface for one turtle or the first of many turtles, 'turtle.' should be omitted."  As a further concession to beginners, this could even be follows by "If one uses the object interface, replace 'turtle' with the actual name of a particular turtle."

nosy: +terry.reedy

Python tracker <report at bugs.python.org>

More information about the docs mailing list