https://github.com/python/cpython/commit/9b3fc89b2a62167ac7a8de8e58cd739ff13a3626
commit: 9b3fc89b2a62167ac7a8de8e58cd739ff13a3626
branch: main
author: Stan Ulbrych <[email protected]>
committer: StanFromIreland <[email protected]>
date: 2026-09-24T15:41:17+01:00
summary:
gh-157847: Rewrite `turtle` module docs introduction (#157854)
files:
M Doc/includes/optional-module.rst
M Doc/library/turtle.rst
M Doc/tools/removed-ids.txt
diff --git a/Doc/includes/optional-module.rst b/Doc/includes/optional-module.rst
index 262e73f2eaa09fb..d37f18227f73725 100644
--- a/Doc/includes/optional-module.rst
+++ b/Doc/includes/optional-module.rst
@@ -7,3 +7,4 @@ If you are the distributor, see
:ref:`optional-module-requirements`.
.. Similar notes appear in the docs of the modules:
- zipfile
- tarfile
+ - turtle
diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst
index f28c4230f3d6b89..8affcc9ef79defd 100644
--- a/Doc/library/turtle.rst
+++ b/Doc/library/turtle.rst
@@ -24,25 +24,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.
-
-.. include:: ../includes/optional-module.rst
-
-
-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
@@ -51,21 +32,40 @@ direction it is facing, drawing a line as it moves. Give
it the command
.. image:: turtle-star.png
: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` :term:`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
========
@@ -108,7 +108,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
@@ -188,38 +189,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.
-
-
Automatically begin and end filling
-----------------------------------
@@ -323,8 +302,11 @@ The turtle's screen can be customised, for example::
t.screen.bgcolor("orange")
-Turtle graphics reference
-=========================
+.. _turtle-reference:
+.. _turtle-graphics-reference:
+
+Reference
+=========
.. note::
diff --git a/Doc/tools/removed-ids.txt b/Doc/tools/removed-ids.txt
index 3f7906ee84ec148..eb2b30b7b4a1286 100644
--- a/Doc/tools/removed-ids.txt
+++ b/Doc/tools/removed-ids.txt
@@ -91,3 +91,7 @@ reference/expressions.html: generator.throw
# Obsolete sections in 'turtle' docs
library/turtle.html: changes-since-python-2-6
library/turtle.html: changes-since-python-3-0
+
+# 'turtle' documentation reorganisation (gh-157847)
+library/turtle.html: note
+library/turtle.html: introduction
_______________________________________________
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]
