From e3eecc868d2a816fc2aa384ad25daf173f50af1f Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Sat, 22 Jul 2023 11:10:59 +0200 Subject: [PATCH 1/3] Amend the introduction to the turtle graphics documentation This patch helps clarify the purpose, value and scope of the turtle graphics module, by rewriting the introduction according to the pattern: * a single sentence that says **what the product (or thing) is**, as succinctly as possible * a brief description of **what it does** * a statement of its purpose or **the problem it solves** * a note about **whom it is useful for** --- Doc/library/turtle.rst | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index c9ce955a6d2ba4..7b706c3a1d9912 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -19,9 +19,27 @@ Introduction ============ -Turtle graphics is a popular way for introducing programming to kids. It was -part of the original Logo programming language developed by Wally Feurzeig, -Seymour Papert and Cynthia Solomon in 1967. +Turtle graphics is an implementation of `the popular geometric drawing tools +introduced in Logo `_, developed by Wally Feurzeig, Seymour Papert and Cynthia Solomon +in 1967. + +In Python, turtle graphics provides a representation of a physical "turtle" +(a little robot with a pen) that draws on a sheet of paper on the floor. + +It's a very effective and well-proven way for learners to encounter +programming concepts and interaction with software, as it provides instant, +visible feedback. It also provides convenient access to graphical output +in general. + +Turtle drawing was originally created as an educational tool, to be used by +teachers in the classroom. For the programmer who needs to produce some +graphical output it can be a way to do that without the overhead of +introducing more complex or external libraries into their work. + + +Get started +=========== Imagine a robotic turtle starting at (0, 0) in the x-y plane. After an ``import turtle``, give it the command ``turtle.forward(15)``, and it moves (on-screen!) 15 pixels in the From 196acc3673d39f45c22d8ef816f7703025e3bbe9 Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Sat, 22 Jul 2023 12:13:36 +0200 Subject: [PATCH 2/3] Update Doc/library/turtle.rst Co-authored-by: Hugo van Kemenade --- Doc/library/turtle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index 7b706c3a1d9912..f14a677b7dd88c 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -27,7 +27,7 @@ in 1967. In Python, turtle graphics provides a representation of a physical "turtle" (a little robot with a pen) that draws on a sheet of paper on the floor. -It's a very effective and well-proven way for learners to encounter +It's an effective and well-proven way for learners to encounter programming concepts and interaction with software, as it provides instant, visible feedback. It also provides convenient access to graphical output in general. From 07628da7dafab5c3a4190e5659dbe3d1fc24d407 Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Sat, 22 Jul 2023 23:06:16 +0200 Subject: [PATCH 3/3] 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. --- Doc/includes/turtle-star.py | 10 --- Doc/library/turtle.rst | 141 ++++++++++++++++++++++++++++++++---- 2 files changed, 125 insertions(+), 26 deletions(-) delete mode 100644 Doc/includes/turtle-star.py diff --git a/Doc/includes/turtle-star.py b/Doc/includes/turtle-star.py deleted file mode 100644 index 1a5db761b32385..00000000000000 --- a/Doc/includes/turtle-star.py +++ /dev/null @@ -1,10 +0,0 @@ -from turtle import * -color('red', 'yellow') -begin_fill() -while True: - forward(200) - left(170) - if abs(pos()) < 1: - break -end_fill() -done() diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index f14a677b7dd88c..4667af0fba6c0c 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -24,6 +24,14 @@ introduced in Logo `_, developed by Wally Feurzeig, Seymour Papert and Cynthia Solomon in 1967. +.. sidebar:: Turtle star + + Turtle can draw intricate shapes using programs that repeat simple + moves. + + .. image:: turtle-star.* + :align: center + In Python, turtle graphics provides a representation of a physical "turtle" (a little robot with a pen) that draws on a sheet of paper on the floor. @@ -38,26 +46,127 @@ graphical output it can be a way to do that without the overhead of introducing more complex or external libraries into their work. -Get started -=========== +Tutorial +======== -Imagine a robotic turtle starting at (0, 0) in the x-y plane. After an ``import turtle``, give it the -command ``turtle.forward(15)``, and it moves (on-screen!) 15 pixels in the -direction it is facing, drawing a line as it moves. Give it the command -``turtle.right(25)``, and it rotates in-place 25 degrees clockwise. +New users should start here. In this tutorial we'll explore some of the +basics of turtle drawing. -.. sidebar:: Turtle star - Turtle can draw intricate shapes using programs that repeat simple - moves. +Starting a turtle environment +----------------------------- - .. image:: turtle-star.* - :align: center +In a Python shell, import all the objects of the ``turtle`` module:: + + from turtle import * + +If you run into a ``No module named '_tkinter'`` error, you'll have to +install the :mod:`Tk interface package ` on your system. + + +Basic drawing +------------- + +Send the turtle forward 100 steps:: + + forward(100) + +You should see (most likely, in a new window on your display) a line +drawn by the turtle, heading East. Change the direction of the turtle, +so that it turns 120 degrees left (anti-clockwise):: + + left(120) + +Let's continue by drawing a triangle:: + + forward(100) + left(120) + forward(100) + +Notice how the turtle, represented by an arrow, points in different +directions as you steer it. + +Experiment with those commands, and also with ``backward()`` and +``right()``. + + +Pen control +~~~~~~~~~~~ + +Try changing the color - for example, ``color('blue')`` - and +width of the line - for example, ``width(3)`` - and then drawing again. + +You can also move the turtle around without drawing, by lifting up the pen: +``up()`` before moving. To start drawing again, use ``down()``. + + +The turtle's position +~~~~~~~~~~~~~~~~~~~~~ + +Send your turtle back to its starting-point (useful if it has disappeared +off-screen):: + + home() + +The home position is at the center of the turtle's screen. If you ever need to +know them, get the turtle's x-y co-ordinates with:: + + pos() + +Home is at ``(0, 0)``. + +And after a while, it will probably help to clear the window so we can start +anew:: + + clearscreen() + + +Making algorithmic patterns +--------------------------- + +Using loops, it's possible to build up geometric patterns:: - .. literalinclude:: ../includes/turtle-star.py + for steps in range(100): + for c in ('blue', 'red', 'green'): + color(c) + forward(steps) + right(30) -By combining together these and similar commands, intricate shapes and pictures -can easily be drawn. + +\ - which of course, are limited only by the imagination! + +Let's draw the star shape at the top of this page. We want red lines, +filled in with yellow:: + + color('red') + fillcolor('yellow') + +Just as ``up()`` and ``down()`` determine whether lines will be drawn, +filling can be turned on and off:: + + begin_fill() + +Next we'll create a loop:: + + while True: + forward(200) + left(170) + if abs(pos()) < 1: + break + +``abs(pos()) < 1`` is a good way to know when the turtle is back at its +home position. + +Finally, complete the filling:: + + end_fill() + +(Note that filling only actually takes place when you give the +``end_fill()`` command.) + + +Explanation +=========== The :mod:`turtle` module is an extended reimplementation of the same-named 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 omitted here. -Overview of available Turtle and Screen methods -================================================= +Turtle graphics reference +========================= Turtle methods --------------