https://github.com/python/cpython/commit/7f5140b6e0b7aafdb1e662eb80528cfe8a33cdf3 commit: 7f5140b6e0b7aafdb1e662eb80528cfe8a33cdf3 branch: 3.13 author: Stan Ulbrych <[email protected]> committer: StanFromIreland <[email protected]> date: 2026-09-24T15:22:50Z summary:
[3.13] gh-157847: Rewrite `turtle` module docs introduction (GH-157854) (#158104) (cherry picked from commit 9b3fc89b2a62167ac7a8de8e58cd739ff13a3626) files: M Doc/library/turtle.rst diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index 43d8f384834590..fac92a1add6e3c 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -17,23 +17,6 @@ -------------- -Introduction -============ - -Turtle graphics is an implementation of `the popular geometric drawing tools -introduced in Logo <https://en.wikipedia.org/wiki/Turtle_ -(robot)>`_, developed by Wally Feurzeig, Seymour Papert and Cynthia Solomon -in 1967. - - -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 -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. - .. sidebar:: Turtle star Turtle can draw intricate shapes using programs that repeat simple @@ -42,21 +25,40 @@ direction it is facing, drawing a line as it moves. Give it the command .. 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. +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. + +Turtle graphics is an implementation of `the drawing tools introduced in Logo +<https://en.wikipedia.org/wiki/Turtle_(robot)>`_ in 1967. It was created as an +educational tool, and its instant, visible feedback makes it an effective way +for learners to encounter programming concepts. It is also a convenient way to +produce simple graphical output without bringing in external libraries. + +This document includes four main sections: -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. +* :ref:`turtle-tutorial` teaches the basics of turtle drawing. +* :ref:`turtle-reference` describes the functions, methods and classes this + module defines. +* :ref:`turtle-howtos` details how to handle specific tasks. +* :ref:`turtle-explanation` provides background on the object-oriented + interface. + +.. note:: -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. + Turtle graphics requires the :mod:`tkinter` optional module. + The python.org installers for Windows and macOS include it, but some + Linux distributions and other platforms may package it separately. If + ``import turtle`` fails with an error mentioning ``_tkinter``, look for + documentation from your distributor (that is, whoever provided Python to you). + Check this in advance if you're planning to use turtle graphics with a learner. .. _turtle-tutorial: +.. _get-started: +.. _get-started-as-quickly-as-possible: Tutorial ======== @@ -99,7 +101,8 @@ 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()``. +``right()``. Many commands also have terser aliases, such as ``fd()`` for +:func:`forward`. Pen control @@ -179,38 +182,16 @@ Finally, complete the filling:: ``end_fill()`` command.) +.. _turtle-howtos: .. _turtle-how-to: +.. _how-to: -How to... -========= +How-to guides +============= 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 <turtle-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 <tkinter>` 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 ----------------------------------- @@ -289,8 +270,11 @@ The turtle's screen can be customised, for example:: t.screen.bgcolor("orange") -Turtle graphics reference -========================= +.. _turtle-reference: +.. _turtle-graphics-reference: + +Reference +========= .. note:: _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
