Title: turtle module examples should all begin "from turtle import *"
Type: enhancement Stage:
Components: Documentation Versions: Python 3.4, Python 3.5
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ethan.furman, mark, terry.reedy
Priority: normal Keywords:

Created on 2014-08-02 07:57 by mark, last changed 2014-08-03 06:55 by mark. This issue is now closed.

Messages (3)
msg224538 - (view) Author: Mark Summerfield (mark) * Date: 2014-08-02 07:57
The turtle module is aimed primarily at young beginners to Python. Making them type turtle.this and turtle.that all over the place is tedious and unhelpful.

At the start of the turtle docs there's a nice example that begins
from turtle import *
and the following code is all the better for it.

But none of the other examples do this. I realise that this would make the module's docs inconsistent, but given the target audience and given that we surely want to lower the barrier to entry, it would be a reasonable concession to make?
msg224588 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-08-02 21:24
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."
msg224611 - (view) Author: Mark Summerfield (mark) * Date: 2014-08-03 06:55
Ah, we're slightly at cross purposes. I showed them purely in terms of the procedural API. However, I can see now that I could have begun with:

import turtle
jane = turtle.Turtle()

So, to "teach" their turtle how to go in a square, I guess they'd do:

def square(who, size=100):
    for n in range(4):


That seems reasonable, but then why isn't the first (and only complete) example done in this OO-ish style?

Anyway, I've marked this closed and will switch to this approach in future.

Date User Action Args
2014-08-03 06:55:09marksetstatus: open -> closed
resolution: not a bug
messages: + msg224611
2014-08-02 21:24:18terry.reedysetnosy: + terry.reedy
messages: + msg224588
2014-08-02 16:54:11ethan.furmansetnosy: + ethan.furman
2014-08-02 07:57:51markcreate