Skip to content

Commit

Permalink
[3.12] gh-106996: Add a how-to section to the turtle documentation (G…
Browse files Browse the repository at this point in the history
…H-107153) (#107233)

Co-authored-by: Daniele Procida <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>
  • Loading branch information
3 people authored Jul 25, 2023
1 parent 2cdde10 commit fab36fb
Showing 1 changed file with 114 additions and 0 deletions.
114 changes: 114 additions & 0 deletions Doc/library/turtle.rst
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,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
========

Expand Down Expand Up @@ -165,6 +167,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 <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
-----------------------------------

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 <turtle-explanation>`

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
===========

Expand Down

0 comments on commit fab36fb

Please sign in to comment.