From e3eecc868d2a816fc2aa384ad25daf173f50af1f Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Sat, 22 Jul 2023 11:10:59 +0200 Subject: [PATCH 1/5] 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/5] 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/5] 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 -------------- From 1e50cc760c1371af7933df058c93c43d3e9f11d6 Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Sun, 23 Jul 2023 22:25:44 +0200 Subject: [PATCH 4/5] Add a how-to section to the turtle documentation This covers the basics of four different use-cases: * using commands directly in the shell (covered in more detail in the tutorial) * using the turtle module namespace * using turtle graphics in a script * using the object-oriented interface --- Doc/library/turtle.rst | 114 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index 58ac546e75860b..c3561a0b2f9ce8 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -55,6 +55,8 @@ graphical output it can be a way to do that without the overhead of introducing more complex or external libraries into their work. +.. _turtle-tutorial: + Tutorial ======== @@ -174,6 +176,118 @@ Finally, complete the filling:: ``end_fill()`` command.) +.. _turtle-how-to: + +How to... +========= + +This section covers some typical turtle use-cases and approaches. + + +Get started as quickly as possible +---------------------------------- + +One of the joys of turtle graphics is the immediate, visual feedback that's +available from simple commands - it's an excellent way to introduce children +to programming ideas, with a minimum of overhead (not just children, of +course). + +The turtle module makes this possible by exposing all its basic functionality +as functions, available with ``from turtle import *``. The :ref:`turtle +graphics tutorial ` covers this approach. + +It's worth noting that many of the turtle commands also have even more terse +equivalents, such as ``fd()`` for :func:`forward`. These are especially +useful when working with learners for whom typing is not a skill. + +.. _note: + + You'll need to have the :mod:`Tk interface package ` installed on + your system for turtle graphics to work. Be warned that this is not + always straightforward, so check this in advance if you're planning to + use turtle graphics with a learner. + + +Use the ``turtle`` module namespace +----------------------------------- + +Using ``from turtle import *`` is convenient - but be warned that it imports a +rather large collection of objects, and if you're doing anything but turtle +graphics you run the risk of a name conflict (this becomes even more an issue +if you're using turtle graphics in a script where other modules might be +imported). + +The solution is to use ``import turtle`` - ``fd()`` becomes +``turtle.fd()``, ``width()`` becomes ``turtle.width()`` and so on. (If typing +"turtle" over and over again becomes tedious, use for example ``import turtle +as t`` instead.) + + +Use turtle graphics in a script +------------------------------- + +It's recommended to use the ``turtle`` module namespace as described +immediately above, for example:: + + import turtle as t + from random import random + + for i in range(100): + steps = int(random() * 100) + angle = int(random() * 360) + t.right(angle) + t.fd(steps) + +Another step is also required though - as soon as the script ends, Python +will also close the turtle's window. Add:: + + t.mainloop() + +to the end of the script. The script will now wait to be dismissed and +will not exit until it is terminated, for example by closing the turtle +graphics window. + + +Use object-oriented turtle graphics +----------------------------------- + +.. seealso:: :ref:`Explanation of the object-oriented interface ` + +Other than for very basic introductory purposes, or for trying things out +as quickly as possible, it's more usual and much more powerful to use the +object-oriented approach to turtle graphics. For example, this allows +multiple turtles on screen at once. + +In this approach, the various turtle commands are methods of objects (mostly of +``Turtle`` objects). You *can* use the object-oriented approach in the shell, +but it would be more typical in a Python script. + +The example above then becomes:: + + from turtle import Turtle + from random import random + + t = Turtle() + for i in range(100): + steps = int(random() * 100) + angle = int(random() * 360) + t.right(angle) + t.fd(steps) + + t.screen.mainloop() + +Note the last line. ``t.screen`` is an instance of the :class:`Screen` +that a Turtle instance exists on; it's created automatically along with +the turtle. + +The turtle's screen can be customised, for example:: + + t.screen.title('Object-oriented turtle demo') + t.screen.bgcolor("orange") + + +.. _turtle-explanation: + Explanation =========== From 1c5a00c2d72d1c9753cb6071ca303bba47017aef Mon Sep 17 00:00:00 2001 From: Daniele Procida Date: Mon, 24 Jul 2023 08:47:23 +0200 Subject: [PATCH 5/5] Fix indentation error in turtle documentation --- 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 08953082458cb3..c3561a0b2f9ce8 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -86,7 +86,7 @@ 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) + left(120) Let's continue by drawing a triangle::