Skip to content

Commit 07628da

Browse files
committed
Add the basics of a turtle graphics tutorial
The tutorial follows the practices outlined in https://diataxis.fr/tutorials/. It uses the functional turtle interface, and doesn't mention the object-oriented interface (which would be a good next step). Existing sections are now clearly labelled "Explanation" and "Reference" to clarify their scope.
1 parent 196acc3 commit 07628da

File tree

2 files changed

+125
-26
lines changed

2 files changed

+125
-26
lines changed

Doc/includes/turtle-star.py

Lines changed: 0 additions & 10 deletions
This file was deleted.

Doc/library/turtle.rst

Lines changed: 125 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,14 @@ introduced in Logo <https://en.wikipedia.org/wiki/Turtle_
2424
(robot)>`_, developed by Wally Feurzeig, Seymour Papert and Cynthia Solomon
2525
in 1967.
2626

27+
.. sidebar:: Turtle star
28+
29+
Turtle can draw intricate shapes using programs that repeat simple
30+
moves.
31+
32+
.. image:: turtle-star.*
33+
:align: center
34+
2735
In Python, turtle graphics provides a representation of a physical "turtle"
2836
(a little robot with a pen) that draws on a sheet of paper on the floor.
2937

@@ -38,26 +46,127 @@ graphical output it can be a way to do that without the overhead of
3846
introducing more complex or external libraries into their work.
3947

4048

41-
Get started
42-
===========
49+
Tutorial
50+
========
4351

44-
Imagine a robotic turtle starting at (0, 0) in the x-y plane. After an ``import turtle``, give it the
45-
command ``turtle.forward(15)``, and it moves (on-screen!) 15 pixels in the
46-
direction it is facing, drawing a line as it moves. Give it the command
47-
``turtle.right(25)``, and it rotates in-place 25 degrees clockwise.
52+
New users should start here. In this tutorial we'll explore some of the
53+
basics of turtle drawing.
4854

49-
.. sidebar:: Turtle star
5055

51-
Turtle can draw intricate shapes using programs that repeat simple
52-
moves.
56+
Starting a turtle environment
57+
-----------------------------
5358

54-
.. image:: turtle-star.*
55-
:align: center
59+
In a Python shell, import all the objects of the ``turtle`` module::
60+
61+
from turtle import *
62+
63+
If you run into a ``No module named '_tkinter'`` error, you'll have to
64+
install the :mod:`Tk interface package <tkinter>` on your system.
65+
66+
67+
Basic drawing
68+
-------------
69+
70+
Send the turtle forward 100 steps::
71+
72+
forward(100)
73+
74+
You should see (most likely, in a new window on your display) a line
75+
drawn by the turtle, heading East. Change the direction of the turtle,
76+
so that it turns 120 degrees left (anti-clockwise)::
77+
78+
left(120)
79+
80+
Let's continue by drawing a triangle::
81+
82+
forward(100)
83+
left(120)
84+
forward(100)
85+
86+
Notice how the turtle, represented by an arrow, points in different
87+
directions as you steer it.
88+
89+
Experiment with those commands, and also with ``backward()`` and
90+
``right()``.
91+
92+
93+
Pen control
94+
~~~~~~~~~~~
95+
96+
Try changing the color - for example, ``color('blue')`` - and
97+
width of the line - for example, ``width(3)`` - and then drawing again.
98+
99+
You can also move the turtle around without drawing, by lifting up the pen:
100+
``up()`` before moving. To start drawing again, use ``down()``.
101+
102+
103+
The turtle's position
104+
~~~~~~~~~~~~~~~~~~~~~
105+
106+
Send your turtle back to its starting-point (useful if it has disappeared
107+
off-screen)::
108+
109+
home()
110+
111+
The home position is at the center of the turtle's screen. If you ever need to
112+
know them, get the turtle's x-y co-ordinates with::
113+
114+
pos()
115+
116+
Home is at ``(0, 0)``.
117+
118+
And after a while, it will probably help to clear the window so we can start
119+
anew::
120+
121+
clearscreen()
122+
123+
124+
Making algorithmic patterns
125+
---------------------------
126+
127+
Using loops, it's possible to build up geometric patterns::
56128

57-
.. literalinclude:: ../includes/turtle-star.py
129+
for steps in range(100):
130+
for c in ('blue', 'red', 'green'):
131+
color(c)
132+
forward(steps)
133+
right(30)
58134

59-
By combining together these and similar commands, intricate shapes and pictures
60-
can easily be drawn.
135+
136+
\ - which of course, are limited only by the imagination!
137+
138+
Let's draw the star shape at the top of this page. We want red lines,
139+
filled in with yellow::
140+
141+
color('red')
142+
fillcolor('yellow')
143+
144+
Just as ``up()`` and ``down()`` determine whether lines will be drawn,
145+
filling can be turned on and off::
146+
147+
begin_fill()
148+
149+
Next we'll create a loop::
150+
151+
while True:
152+
forward(200)
153+
left(170)
154+
if abs(pos()) < 1:
155+
break
156+
157+
``abs(pos()) < 1`` is a good way to know when the turtle is back at its
158+
home position.
159+
160+
Finally, complete the filling::
161+
162+
end_fill()
163+
164+
(Note that filling only actually takes place when you give the
165+
``end_fill()`` command.)
166+
167+
168+
Explanation
169+
===========
61170

62171
The :mod:`turtle` module is an extended reimplementation of the same-named
63172
module from the Python standard distribution up to version Python 2.5.
@@ -112,8 +221,8 @@ To use multiple turtles on a screen one has to use the object-oriented interface
112221
omitted here.
113222

114223

115-
Overview of available Turtle and Screen methods
116-
=================================================
224+
Turtle graphics reference
225+
=========================
117226

118227
Turtle methods
119228
--------------

0 commit comments

Comments
 (0)