turtle module examples should all begin "from turtle import *"

[mark-summerfield]

BPO	22122
Nosy	@terryjreedy, @mark-summerfield, @ethanfurman

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2014-08-03.06:55:09.896>
created_at = <Date 2014-08-02.07:57:51.217>
labels = ['type-feature', 'invalid', 'docs']
title = 'turtle module examples should all begin "from turtle import *"'
updated_at = <Date 2014-08-03.06:55:09.895>
user = 'https://github.com/mark-summerfield'

bugs.python.org fields:

activity = <Date 2014-08-03.06:55:09.895>
actor = 'mark'
assignee = 'docs@python'
closed = True
closed_date = <Date 2014-08-03.06:55:09.896>
closer = 'mark'
components = ['Documentation']
creation = <Date 2014-08-02.07:57:51.217>
creator = 'mark'
dependencies = []
files = []
hgrepos = []
issue_num = 22122
keywords = []
message_count = 3.0
messages = ['224538', '224588', '224611']
nosy_count = 4.0
nosy_names = ['terry.reedy', 'mark', 'docs@python', 'ethan.furman']
pr_nums = []
priority = 'normal'
resolution = 'not a bug'
stage = None
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue22122'
versions = ['Python 3.4', 'Python 3.5']

[mark-summerfield]

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?

[terryjreedy]

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. PEP-8 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."

[mark-summerfield]

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()
jane.fd(100)

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):
        who.fd(100)
        who.rt(90)

square(jane)

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.

Thanks.