[3.11] gh-106996: Rewrite turtle explanation (GH-107244) (#107336)

Co-authored-by: Daniele Procida <daniele@vurt.org>
Co-authored-by: Hugo van Kemenade <hugovk@users.noreply.github.com>
This commit is contained in:
Miss Islington (bot) 2023-07-27 01:12:17 -07:00 committed by GitHub
parent 9513acf737
commit 8f0dc1878c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 38 additions and 54 deletions

View File

@ -277,67 +277,16 @@ The turtle's screen can be customised, for example::
t.screen.bgcolor("orange")
.. _turtle-explanation:
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.
It tries to keep the merits of the old turtle module and to be (nearly) 100%
compatible with it. This means in the first place to enable the learning
programmer to use all the commands, classes and methods interactively when using
the module from within IDLE run with the ``-n`` switch.
The turtle module provides turtle graphics primitives, in both object-oriented
and procedure-oriented ways. Because it uses :mod:`tkinter` for the underlying
graphics, it needs a version of Python installed with Tk support.
The object-oriented interface uses essentially two+two classes:
1. The :class:`TurtleScreen` class defines graphics windows as a playground for
the drawing turtles. Its constructor needs a :class:`tkinter.Canvas` or a
:class:`ScrolledCanvas` as argument. It should be used when :mod:`turtle` is
used as part of some application.
The function :func:`Screen` returns a singleton object of a
:class:`TurtleScreen` subclass. This function should be used when
:mod:`turtle` is used as a standalone tool for doing graphics.
As a singleton object, inheriting from its class is not possible.
All methods of TurtleScreen/Screen also exist as functions, i.e. as part of
the procedure-oriented interface.
2. :class:`RawTurtle` (alias: :class:`RawPen`) defines Turtle objects which draw
on a :class:`TurtleScreen`. Its constructor needs a Canvas, ScrolledCanvas
or TurtleScreen as argument, so the RawTurtle objects know where to draw.
Derived from RawTurtle is the subclass :class:`Turtle` (alias: :class:`Pen`),
which draws on "the" :class:`Screen` instance which is automatically
created, if not already present.
All methods of RawTurtle/Turtle also exist as functions, i.e. part of the
procedure-oriented interface.
The procedural interface provides functions which are derived from the methods
of the classes :class:`Screen` and :class:`Turtle`. They have the same names as
the corresponding methods. A screen object is automatically created whenever a
function derived from a Screen method is called. An (unnamed) turtle object is
automatically created whenever any of the functions derived from a Turtle method
is called.
To use multiple turtles on a screen one has to use the object-oriented interface.
Turtle graphics reference
=========================
.. note::
In the following documentation the argument list for functions is given.
Methods, of course, have the additional first argument *self* which is
omitted here.
Turtle graphics reference
=========================
Turtle methods
--------------
@ -2434,6 +2383,41 @@ Public classes
* ``a.rotate(angle)`` rotation
.. _turtle-explanation:
Explanation
===========
A turtle object draws on a screen object, and there a number of key classes in
the turtle object-oriented interface that can be used to create them and relate
them to each other.
A :class:`Turtle` instance will automatically create a :class:`Screen`
instance if one is not already present.
``Turtle`` is a subclass of :class:`RawTurtle`, which *doesn't* automatically
create a drawing surface - a *canvas* will need to be provided or created for
it. The *canvas* can be a :class:`tkinter.Canvas`, :class:`ScrolledCanvas`
or :class:`TurtleScreen`.
:class:`TurtleScreen` is the basic drawing surface for a
turtle. :class:`Screen` is a subclass of ``TurtleScreen``, and
includes :ref:`some additional methods <screenspecific>` for managing its
appearance (including size and title) and behaviour. ``TurtleScreen``'s
constructor needs a :class:`tkinter.Canvas` or a
:class:`ScrolledCanvas` as an argument.
The functional interface for turtle graphics uses the various methods of
``Turtle`` and ``TurtleScreen``/``Screen``. Behind the scenes, a screen
object is automatically created whenever a function derived from a ``Screen``
method is called. Similarly, a turtle object is automatically created
whenever any of the functions derived from a Turtle method is called.
To use multiple turtles on a screen, the object-oriented interface must be
used.
Help and configuration
======================