From eff9d1371c54e005e4ea6f2e9a4cbd076d219293 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Sun, 18 Oct 2026 20:50:09 +0100 Subject: [PATCH 1/2] Re-write more `turtle` docs --- Doc/library/turtle.rst | 287 +++++++++++++------------- Lib/turtle.py | 458 ++++++++++++++++++++--------------------- 2 files changed, 370 insertions(+), 375 deletions(-) diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index 76063e3dc91186..6fad6bcac4fd2e 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -350,18 +350,20 @@ Move and draw (0.00,0.00) -.. function:: teleport(x, y=None, *, fill_gap=False) +.. function:: teleport(x=None, y=None, *, fill_gap=False) :param x: a number or ``None`` :param y: a number or ``None`` :param fill_gap: a boolean - Move turtle to an absolute position. Unlike goto(x, y), a line will not - be drawn. The turtle's orientation does not change. If currently - filling, the polygon(s) teleported from will be filled after leaving, - and filling will begin again after teleporting. This can be disabled - with fill_gap=True, which makes the imaginary line traveled during - teleporting act as a fill barrier like in goto(x, y). + Instantly move the turtle to an absolute position. Unlike :func:`goto`, no + line is drawn. If *x* or *y* is not given, that coordinate is kept as it + is. The turtle's heading does not change. + + If the turtle is filling a shape, the shape drawn so far is finished and + filled before the jump, and filling starts again at the new position. Pass + ``fill_gap=True`` to keep filling one shape instead. The jump then counts + as an edge of the shape, as it would with :func:`goto`. .. doctest:: :skipif: _tkinter is None @@ -528,12 +530,12 @@ Move and draw dot(size, color, /) dot(size, r, g, b, /) - :param size: an integer >= 1 (if given) + :param size: a positive integer or ``None`` :param color: a colorstring or a numeric color tuple - Draw a circular dot with diameter *size*, using *color*. If *size* is - not given, the maximum of ``pensize+4`` and ``2*pensize`` is used. - + Draw a circular dot with diameter *size*, using *color*. If *size* is not + given, the larger of ``pensize + 4`` and ``2 * pensize`` is used. If + *color* is not given, the current pencolor is used. .. doctest:: :skipif: _tkinter is None @@ -619,26 +621,23 @@ Move and draw .. function:: speed(speed=None) - :param speed: an integer in the range 0..10 or a speedstring (see below) - - Set the turtle's speed to an integer value in the range 0..10. If no - argument is given, return current speed. + :param speed: an integer, a string or ``None`` - If input is a number greater than 10 or smaller than 0.5, speed is set - to 0. Speedstrings are mapped to speedvalues as follows: + Return or set the turtle's speed. If *speed* is not given, return the + current speed. Otherwise set the turtle's speed to an integer from 0 to 10. + If *speed* is a number greater than 10 or smaller than 0.5, the speed is + set to 0. A speed string is mapped to a speed value as follows: - * "fastest": 0 - * "fast": 10 - * "normal": 6 - * "slow": 3 - * "slowest": 1 + * "fastest": 0 + * "fast": 10 + * "normal": 6 + * "slow": 3 + * "slowest": 1 - Speeds from 1 to 10 enforce increasingly faster animation of line drawing - and turtle turning. - - Attention: *speed* = 0 means that *no* animation takes - place. forward/back makes turtle jump and likewise left/right make the - turtle turn instantly. + Speeds from 1 to 10 give increasingly faster animation of line drawing and + turtle turning. A speed of 0 means that no animation takes place: + :func:`forward` and :func:`back` make the turtle jump, and likewise + :func:`left` and :func:`right` make the turtle turn instantly. .. doctest:: :skipif: _tkinter is None @@ -817,24 +816,24 @@ Drawing state pd() down() - Pull the pen down -- drawing when moving. + Pull the pen down. The turtle draws a line when it moves. .. function:: penup() pu() up() - Pull the pen up -- no drawing when moving. + Pull the pen up. The turtle does not draw when it moves. .. function:: pensize(width=None) width(width=None) - :param width: a positive number + :param width: a positive number or ``None`` - Set the line thickness to *width* or return it. If resizemode is set to - "auto" and turtleshape is a polygon, that polygon is drawn with the same line - thickness. If no argument is given, the current pensize is returned. + Set the line thickness to *width* or return it. If *width* is not given, + return the current pensize. If resizemode is set to "auto" and the turtle + shape is a polygon, that polygon is drawn with the same line thickness. .. doctest:: :skipif: _tkinter is None @@ -889,7 +888,7 @@ Drawing state .. function:: isdown() - Return ``True`` if pen is down, ``False`` if it's up. + Return ``True`` if the pen is down, ``False`` if it's up. .. doctest:: :skipif: _tkinter is None @@ -920,20 +919,20 @@ Color control call. ``pencolor(colorstring)`` - Set pencolor to *colorstring*, which is a Tk color specification string, - such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``. + Set the pencolor to *colorstring*, which is a Tk color specification + string, such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``. ``pencolor((r, g, b))`` - Set pencolor to the RGB color represented by the tuple of *r*, *g*, and - *b*. Each of *r*, *g*, and *b* must be in the range 0..colormode, where + Set the pencolor to the RGB color represented by the tuple of *r*, *g*, + and *b*. Each of *r*, *g*, and *b* must be between 0 and colormode, where colormode is either 1.0 or 255 (see :func:`colormode`). ``pencolor(r, g, b)`` - Set pencolor to the RGB color represented by *r*, *g*, and *b*. Each of - *r*, *g*, and *b* must be in the range 0..colormode. + Set the pencolor to the RGB color represented by *r*, *g*, and *b*. + Each of *r*, *g*, and *b* must be between 0 and colormode. - If turtleshape is a polygon, the outline of that polygon is drawn with the - newly set pencolor. + If the turtle shape is a polygon, the outline of that polygon is drawn with + the newly set pencolor. .. doctest:: :skipif: _tkinter is None @@ -972,19 +971,19 @@ Color control call. ``fillcolor(colorstring)`` - Set fillcolor to *colorstring*, which is a Tk color specification string, - such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``. + Set the fillcolor to *colorstring*, which is a Tk color specification + string, such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``. ``fillcolor((r, g, b))`` - Set fillcolor to the RGB color represented by the tuple of *r*, *g*, and - *b*. Each of *r*, *g*, and *b* must be in the range 0..colormode, where + Set the fillcolor to the RGB color represented by the tuple of *r*, *g*, + and *b*. Each of *r*, *g*, and *b* must be between 0 and colormode, where colormode is either 1.0 or 255 (see :func:`colormode`). ``fillcolor(r, g, b)`` - Set fillcolor to the RGB color represented by *r*, *g*, and *b*. Each of - *r*, *g*, and *b* must be in the range 0..colormode. + Set the fillcolor to the RGB color represented by *r*, *g*, and *b*. Each + of *r*, *g*, and *b* must be between 0 and colormode. - If turtleshape is a polygon, the interior of that polygon is drawn + If the turtle shape is a polygon, the interior of that polygon is drawn with the newly set fillcolor. .. doctest:: @@ -1008,9 +1007,9 @@ Color control color(r, g, b, /) color(pencolor, fillcolor, /) - Return or set pencolor and fillcolor. + Return or set the pencolor and fillcolor. - Several input formats are allowed. They use 0 to 3 arguments as + Several input formats are allowed. They use 0 to 3 arguments as follows: ``color()`` @@ -1019,15 +1018,15 @@ Color control :func:`fillcolor`. ``color(colorstring)``, ``color((r,g,b))``, ``color(r,g,b)`` - Inputs as in :func:`pencolor`, set both, fillcolor and pencolor, to the - given value. + Inputs as in :func:`pencolor`. Set both the pencolor and the fillcolor + to the given value. ``color(colorstring1, colorstring2)``, ``color((r1,g1,b1), (r2,g2,b2))`` Equivalent to ``pencolor(colorstring1)`` and ``fillcolor(colorstring2)`` and analogously if the other input format is used. - If turtleshape is a polygon, outline and interior of that polygon is drawn - with the newly set colors. + If the turtle shape is a polygon, the outline and interior of that polygon + are drawn with the newly set colors. .. doctest:: :skipif: _tkinter is None @@ -1054,7 +1053,7 @@ Filling .. function:: filling() - Return fillstate (``True`` if filling, ``False`` else). + Return ``True`` if the turtle is filling, ``False`` otherwise. .. doctest:: :skipif: _tkinter is None @@ -1182,7 +1181,7 @@ Visibility .. function:: isvisible() - Return ``True`` if the turtle is shown, ``False`` if it's hidden. + Return ``True`` if the turtle is visible, ``False`` if it's hidden. .. doctest:: :skipif: _tkinter is None @@ -1200,13 +1199,13 @@ Appearance .. function:: shape(name=None) - :param name: a string which is a valid shapename + :param name: a string or ``None`` - Set turtle shape to shape with given *name* or, if name is not given, return - name of current shape. Shape with *name* must exist in the TurtleScreen's - shape dictionary. Initially there are the following polygon shapes: "arrow", - "turtle", "circle", "square", "triangle", "classic". To learn about how to - deal with shapes see Screen method :func:`register_shape`. + Set the turtle shape to the shape with the given *name*. If *name* is not + given, return the name of the current shape. The shape must exist in the + :class:`TurtleScreen`'s shape dictionary. Initially there are the following + polygon shapes: "arrow", "turtle", "circle", "square", "triangle" and + "classic". To add shapes, see the :class:`Screen` method :func:`register_shape`. .. doctest:: :skipif: _tkinter is None @@ -1220,19 +1219,19 @@ Appearance .. function:: resizemode(rmode=None) - :param rmode: one of the strings "auto", "user", "noresize" + :param rmode: a string or ``None`` - Set resizemode to one of the values: "auto", "user", "noresize". If *rmode* - is not given, return current resizemode. Different resizemodes have the + Set the resizemode to "auto", "user" or "noresize". If *rmode* is not + given, return the current resizemode. The different resizemodes have the following effects: - - "auto": adapts the appearance of the turtle corresponding to the value of pensize. - - "user": adapts the appearance of the turtle according to the values of - stretchfactor and outlinewidth (outline), which are set by - :func:`shapesize`. - - "noresize": no adaption of the turtle's appearance takes place. + - "auto": the turtle is resized according to the value of :func:`pensize`. + - "user": the turtle is resized according to the stretch factors and + outline width, which are set by :func:`shapesize`. + - "noresize": the turtle is not resized. - ``resizemode("user")`` is called by :func:`shapesize` when used with arguments. + ``resizemode("user")`` is called by :func:`shapesize` when used with + arguments. .. doctest:: :skipif: _tkinter is None @@ -1247,16 +1246,17 @@ Appearance .. function:: shapesize(stretch_wid=None, stretch_len=None, outline=None) turtlesize(stretch_wid=None, stretch_len=None, outline=None) - :param stretch_wid: positive number - :param stretch_len: positive number - :param outline: positive number + :param stretch_wid: a positive number or ``None`` + :param stretch_len: a positive number or ``None`` + :param outline: a positive number or ``None`` - Return or set the pen's attributes x/y-stretchfactors and/or outline. Set - resizemode to "user". If and only if resizemode is set to "user", the turtle - will be displayed stretched according to its stretchfactors: *stretch_wid* is - stretchfactor perpendicular to its orientation, *stretch_len* is - stretchfactor in direction of its orientation, *outline* determines the width - of the shape's outline. + Return or set the turtle's stretch factors and outline width. If no + arguments are given, return the current values. Otherwise set resizemode to + "user", so that the turtle is displayed stretched according to its stretch + factors. *stretch_wid* is the stretch factor perpendicular to the turtle's + heading and *stretch_len* the stretch factor in the direction of its + heading. If only *stretch_wid* is given, *stretch_len* is set to the same + value. *outline* is the width of the shape's outline. .. doctest:: :skipif: _tkinter is None @@ -1456,7 +1456,6 @@ Using events Special Turtle methods ^^^^^^^^^^^^^^^^^^^^^^ - .. function:: poly() Record the vertices of a polygon drawn in the ``with turtle.poly():`` block. @@ -1506,21 +1505,23 @@ Special Turtle methods .. function:: clone() - Create and return a clone of the turtle with same position, heading and - turtle properties. + Create and return a clone of the turtle. The clone has the same position, + heading and turtle properties. .. doctest:: :skipif: _tkinter is None - >>> mick = Turtle() - >>> joe = mick.clone() + >>> leonel = Turtle() + >>> marco = leonel.clone() .. function:: getturtle() getpen() - Return the Turtle object itself. Only reasonable use: as a function to - return the "anonymous turtle": + Return the Turtle object itself. + + Generally used as a function, to get the anonymous turtle used by the + module-level functions: .. doctest:: :skipif: _tkinter is None @@ -1549,10 +1550,10 @@ Special Turtle methods :param size: an integer or ``None`` - Set or disable undobuffer. If *size* is an integer, an empty undobuffer of - given size is installed. *size* gives the maximum number of turtle actions - that can be undone by the :func:`undo` method/function. If *size* is - ``None``, the undobuffer is disabled. + Set or disable the undo buffer. If *size* is an integer, an empty undo + buffer of the given size is installed. *size* is the maximum number of + turtle actions that can be undone by :func:`undo`. If *size* is ``None``, + the undo buffer is disabled. .. doctest:: :skipif: _tkinter is None @@ -1562,7 +1563,7 @@ Special Turtle methods .. function:: undobufferentries() - Return number of entries in the undobuffer. + Return the number of entries in the undo buffer. .. doctest:: :skipif: _tkinter is None @@ -1571,47 +1572,6 @@ Special Turtle methods ... undo() - -.. _compoundshapes: - -Compound shapes -^^^^^^^^^^^^^^^ - -To use compound turtle shapes, which consist of several polygons of different -color, you must use the helper class :class:`Shape` explicitly as described -below: - -1. Create an empty Shape object of type "compound". -2. Add as many components to this object as desired, using the - :meth:`~Shape.addcomponent` method. - - For example: - - .. doctest:: - :skipif: _tkinter is None - - >>> s = Shape("compound") - >>> poly1 = ((0,0),(10,-5),(0,10),(-10,-5)) - >>> s.addcomponent(poly1, "red", "blue") - >>> poly2 = ((0,0),(10,-5),(-10,-5)) - >>> s.addcomponent(poly2, "blue", "red") - -3. Now add the Shape to the Screen's shapelist and use it: - - .. doctest:: - :skipif: _tkinter is None - - >>> register_shape("myshape", s) - >>> shape("myshape") - - -.. note:: - - The :class:`Shape` class is used internally by the :func:`register_shape` - method in different ways. The application programmer has to deal with the - Shape class *only* when using compound shapes like shown above! - - .. _methods-of-turtlescreen-screen: .. _methods-of-turtlescreen-screen-and-corresponding-functions: @@ -1627,6 +1587,7 @@ Most of the examples in this section refer to a TurtleScreen instance called >>> screen = Screen() + Window control ^^^^^^^^^^^^^^ @@ -2171,6 +2132,7 @@ Screen-only methods .. versionadded:: 3.14 + .. function:: setup(width=_CFG["width"], height=_CFG["height"], startx=_CFG["leftright"], starty=_CFG["topbottom"]) Set the size and position of the main window. Default values of arguments @@ -2213,7 +2175,6 @@ Screen-only methods Public classes -------------- - .. class:: RawTurtle(canvas) RawPen(canvas) @@ -2237,6 +2198,7 @@ Public classes Provides screen oriented methods like :func:`bgcolor` etc. that are described above. + .. class:: Screen() Subclass of :class:`TurtleScreen`, with :ref:`four methods added @@ -2333,8 +2295,8 @@ How-to guides This section covers some typical turtle use-cases and approaches. -Automatically begin and end filling ------------------------------------ +How to automatically begin and end filling +------------------------------------------ Starting with Python 3.14, you can use the :func:`fill` :term:`context manager` instead of :func:`begin_fill` and :func:`end_fill` to automatically begin and @@ -2358,8 +2320,41 @@ The code above is equivalent to:: forward(200) -Use the ``turtle`` module namespace ------------------------------------ +.. _compoundshapes: + +How to use compound shapes +-------------------------- + +To use compound turtle shapes, which consist of several polygons of different +color, you must use the helper class :class:`Shape` explicitly as described +below: + +1. Create an empty :class:`Shape` object of type "compound". +2. Add as many components to this object as desired, using the + :meth:`~Shape.addcomponent` method. + + For example: + + .. doctest:: + :skipif: _tkinter is None + + >>> s = Shape("compound") + >>> poly1 = ((0,0), (10,-5), (0,10), (-10,-5)) + >>> s.addcomponent(poly1, "red", "blue") + >>> poly2 = ((0,0), (10,-5), (-10,-5)) + >>> s.addcomponent(poly2, "blue", "red") + +3. Now add the Shape to the Screen's shapelist and use it: + + .. doctest:: + :skipif: _tkinter is None + + >>> register_shape("myshape", s) + >>> shape("myshape") + + +How to 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 @@ -2373,8 +2368,8 @@ The solution is to use ``import turtle`` - ``fd()`` becomes as t`` instead.) -Use turtle graphics in a script -------------------------------- +How to use turtle graphics in a script +-------------------------------------- It's recommended to use the ``turtle`` module namespace as described immediately above, for example:: @@ -2398,8 +2393,8 @@ will not exit until it is terminated, for example by closing the turtle graphics window. -Use object-oriented turtle graphics ------------------------------------ +How to use object-oriented turtle graphics +------------------------------------------ .. seealso:: :ref:`Explanation of the object-oriented interface ` @@ -2438,8 +2433,8 @@ The turtle's screen can be customised, for example:: .. _help-and-configuration: -How to use help ---------------- +How to use :func:`!help` +------------------------ The public methods of the Screen and Turtle classes are documented extensively via docstrings. So these can be used as online-help via the Python help diff --git a/Lib/turtle.py b/Lib/turtle.py index 893994b5c1700c..ab7a193a2cb7bf 100644 --- a/Lib/turtle.py +++ b/Lib/turtle.py @@ -1703,8 +1703,10 @@ def _undo_sequence(self): undobuffer.cumulate = False def teleport(self, x=None, y=None, *, fill_gap: bool = False) -> None: - """To be overwritten by child class RawTurtle. - Includes no TPen references.""" + """To be overwritten by the child class RawTurtle. + + Includes no TPen references. + """ new_x = x if x is not None else self._position[0] new_y = y if y is not None else self._position[1] self._position = Vec2D(new_x, new_y) @@ -2121,26 +2123,29 @@ def _reset(self, pencolor=_CFG["pencolor"], self._outlinewidth = 1 def resizemode(self, rmode=None): - """Set resizemode to one of the values: "auto", "user", "noresize". + """Set the resizemode to "auto", "user" or "noresize". - (Optional) Argument: - rmode -- one of the strings "auto", "user", "noresize" + If rmode is not given, return the current resizemode. The + different resizemodes have the following effects: - Different resizemodes have the following effects: - - "auto" adapts the appearance of the turtle - corresponding to the value of pensize. - - "user" adapts the appearance of the turtle according to the - values of stretchfactor and outlinewidth (outline), - which are set by shapesize() - - "noresize" no adaption of the turtle's appearance takes place. - If no argument is given, return current resizemode. - resizemode("user") is called by a call of shapesize with arguments. + - "auto": the turtle is resized according to the value of + pensize(). + - "user": the turtle is resized according to the stretch factors + and outline width, which are set by shapesize(). + - "noresize": the turtle is not resized. + resizemode("user") is called by shapesize() when used with + arguments. - Examples (for a Turtle instance named turtle): - >>> turtle.resizemode("noresize") - >>> turtle.resizemode() - 'noresize' + Argument: + rmode -- a string or None + + Example (for a Turtle instance named turtle): + >>> turtle.resizemode() + 'noresize' + >>> turtle.resizemode("auto") + >>> turtle.resizemode() + 'auto' """ if rmode is None: return self._resizemode @@ -2149,22 +2154,21 @@ def resizemode(self, rmode=None): self.pen(resizemode=rmode) def pensize(self, width=None): - """Set or return the line thickness. + """Set the line thickness to width or return it. - Aliases: pensize | width + Aliases: pensize | width - Argument: - width -- positive number + If width is not given, return the current pensize. If resizemode + is set to "auto" and the turtle shape is a polygon, that polygon is + drawn with the same line thickness. - Set the line thickness to width or return it. If resizemode is set - to "auto" and turtleshape is a polygon, that polygon is drawn with - the same line thickness. If no argument is given, current pensize - is returned. + Argument: + width -- a positive number or None Example (for a Turtle instance named turtle): - >>> turtle.pensize() - 1 - >>> turtle.pensize(10) # from here on lines of width 10 are drawn + >>> turtle.pensize() + 1 + >>> turtle.pensize(10) # from here on lines of width 10 are drawn """ if width is None: return self._pensize @@ -2172,68 +2176,84 @@ def pensize(self, width=None): def penup(self): - """Pull the pen up -- no drawing when moving. + """Pull the pen up. Aliases: penup | pu | up + + The turtle does not draw when it moves. """ if not self._drawing: return self.pen(pendown=False) def pendown(self): - """Pull the pen down -- drawing when moving. + """Pull the pen down. Aliases: pendown | pd | down + + The turtle draws a line when it moves. """ if self._drawing: return self.pen(pendown=True) def isdown(self): - """Return True if pen is down, False if it's up. + """Return True if the pen is down, False if it's up. Example (for a Turtle instance named turtle): - >>> turtle.penup() - >>> turtle.isdown() - False - >>> turtle.pendown() - >>> turtle.isdown() - True + >>> turtle.penup() + >>> turtle.isdown() + False + >>> turtle.pendown() + >>> turtle.isdown() + True """ return self._drawing def speed(self, speed=None): - """ Return or set the turtle's speed. + """Return or set the turtle's speed. - Optional argument: - speed -- an integer in the range 0..10 or a speedstring (see below) - - Set the turtle's speed to an integer value in the range 0 .. 10. - If no argument is given: return current speed. - - If input is a number greater than 10 or smaller than 0.5, - speed is set to 0. - Speedstrings are mapped to speedvalues in the following way: - 'fastest' : 0 - 'fast' : 10 - 'normal' : 6 - 'slow' : 3 - 'slowest' : 1 - speeds from 1 to 10 enforce increasingly faster animation of - line drawing and turtle turning. - - Attention: - speed = 0 : *no* animation takes place. forward/back makes turtle jump - and likewise left/right make the turtle turn instantly. + If speed is not given, return the current speed. Otherwise set the + turtle's speed to an integer from 0 to 10. If speed is a number + greater than 10 or smaller than 0.5, the speed is set to 0. A + speed string is mapped to a speed value as follows: + + "fastest": 0 + "fast": 10 + "normal": 6 + "slow": 3 + "slowest": 1 + + Speeds from 1 to 10 give increasingly faster animation of line + drawing and turtle turning. A speed of 0 means that no animation + takes place: forward() and back() make the turtle jump, and + likewise left() and right() make the turtle turn instantly. + + Argument: + speed -- an integer, a string or None Example (for a Turtle instance named turtle): - >>> turtle.speed(3) + >>> turtle.speed() + 3 + >>> turtle.speed('normal') + >>> turtle.speed() + 6 + >>> turtle.speed(9) + >>> turtle.speed() + 9 """ - speeds = {'fastest':0, 'fast':10, 'normal':6, 'slow':3, 'slowest':1 } + speed_strings = { + 'fastest': 0, + 'fast': 10, + 'normal': 6, + 'slow': 3, + 'slowest': 1, + } + if speed is None: return self._speed - if speed in speeds: - speed = speeds[speed] + if speed in speed_strings: + speed = speed_strings[speed] elif 0.5 < speed < 10.5: speed = int(round(speed)) else: @@ -2243,32 +2263,30 @@ def speed(self, speed=None): def color(self, *args): """Return or set the pencolor and fillcolor. - Arguments: - Several input formats are allowed. - They use 0 to 3 arguments as follows: + Several input formats are allowed. They use 0 to 3 arguments as follows: - color() Return the current pencolor and the current fillcolor as a pair of color specification strings or tuples as returned by pencolor() and fillcolor(). - color(colorstring), color((r,g,b)), color(r,g,b) - Inputs as in pencolor(), set both, fillcolor and pencolor, - to the given value. + Inputs as in pencolor(). Set both the pencolor and the + fillcolor to the given value. - color(colorstring1, colorstring2), color((r1,g1,b1), (r2,g2,b2)) Equivalent to pencolor(colorstring1) and fillcolor(colorstring2) and analogously if the other input format is used. - If turtleshape is a polygon, outline and interior of that polygon - is drawn with the newly set colors. - For more info see: pencolor, fillcolor + If the turtle shape is a polygon, the outline and interior of that + polygon are drawn with the newly set colors. For more information, + see pencolor() and fillcolor(). Example (for a Turtle instance named turtle): - >>> turtle.color('red', 'green') - >>> turtle.color() - ('red', 'green') - >>> colormode(255) - >>> color(('#285078', '#a0c8f0')) - >>> color() - ((40.0, 80.0, 120.0), (160.0, 200.0, 240.0)) + >>> turtle.color("red", "green") + >>> turtle.color() + ('red', 'green') + >>> colormode(255) + >>> turtle.color("#285078", "#a0c8f0") + >>> turtle.color() + ((40.0, 80.0, 120.0), (160.0, 200.0, 240.0)) """ if args: l = len(args) @@ -2285,37 +2303,36 @@ def color(self, *args): return self._color(self._pencolor), self._color(self._fillcolor) def pencolor(self, *args): - """ Return or set the pencolor. + """Return or set the pencolor. - Arguments: Four input formats are allowed: - pencolor() Return the current pencolor as color specification string or as a tuple (see example). May be used as input to another - color/pencolor/fillcolor/bgcolor call. + color(), pencolor(), fillcolor() or bgcolor() call. - pencolor(colorstring) - Set pencolor to colorstring, which is a Tk color + Set the pencolor to colorstring, which is a Tk color specification string, such as "red", "yellow", or "#33cc8c". - pencolor((r, g, b)) - Set pencolor to the RGB color represented by the tuple of - r, g, and b. Each of r, g, and b must be in the range - 0..colormode, where colormode is either 1.0 or 255 (see + Set the pencolor to the RGB color represented by the tuple of + r, g, and b. Each of r, g, and b must be between 0 and + colormode, where colormode is either 1.0 or 255 (see colormode()). - pencolor(r, g, b) - Set pencolor to the RGB color represented by r, g, and b. - Each of r, g, and b must be in the range 0..colormode. + Set the pencolor to the RGB color represented by r, g, and b. + Each of r, g, and b must be between 0 and colormode. - If turtleshape is a polygon, the outline of that polygon is drawn - with the newly set pencolor. + If the turtle shape is a polygon, the outline of that polygon is + drawn with the newly set pencolor. Example (for a Turtle instance named turtle): - >>> turtle.pencolor('brown') - >>> turtle.pencolor() - 'brown' - >>> colormode(255) - >>> turtle.pencolor('#32c18f') - >>> turtle.pencolor() - (50.0, 193.0, 143.0) + >>> turtle.pencolor("brown") + >>> turtle.pencolor() + 'brown' + >>> colormode(255) + >>> turtle.pencolor("#32c18f") + >>> turtle.pencolor() + (50.0, 193.0, 143.0) """ if args: color = self._colorstr(args) @@ -2326,37 +2343,36 @@ def pencolor(self, *args): return self._color(self._pencolor) def fillcolor(self, *args): - """ Return or set the fillcolor. + """Return or set the fillcolor. - Arguments: Four input formats are allowed: - fillcolor() Return the current fillcolor as color specification string, possibly in tuple format (see example). May be used as - input to another color/pencolor/fillcolor/bgcolor call. + input to another color(), pencolor(), fillcolor() or bgcolor() call. - fillcolor(colorstring) - Set fillcolor to colorstring, which is a Tk color + Set the fillcolor to colorstring, which is a Tk color specification string, such as "red", "yellow", or "#33cc8c". - fillcolor((r, g, b)) - Set fillcolor to the RGB color represented by the tuple of - r, g, and b. Each of r, g, and b must be in the range - 0..colormode, where colormode is either 1.0 or 255 (see + Set the fillcolor to the RGB color represented by the tuple of + r, g, and b. Each of r, g, and b must be between 0 and + colormode, where colormode is either 1.0 or 255 (see colormode()). - fillcolor(r, g, b) - Set fillcolor to the RGB color represented by r, g, and b. - Each of r, g, and b must be in the range 0..colormode. + Set the fillcolor to the RGB color represented by r, g, and b. + Each of r, g, and b must be between 0 and colormode. - If turtleshape is a polygon, the interior of that polygon is drawn - with the newly set fillcolor. + If the turtle shape is a polygon, the interior of that polygon is + drawn with the newly set fillcolor. Example (for a Turtle instance named turtle): - >>> turtle.fillcolor('violet') - >>> turtle.fillcolor() - 'violet' - >>> colormode(255) - >>> turtle.fillcolor('#ffffff') - >>> turtle.fillcolor() - (255.0, 255.0, 255.0) + >>> turtle.fillcolor("violet") + >>> turtle.fillcolor() + 'violet' + >>> colormode(255) + >>> turtle.fillcolor("#ffffff") + >>> turtle.fillcolor() + (255.0, 255.0, 255.0) """ if args: color = self._colorstr(args) @@ -2367,7 +2383,7 @@ def fillcolor(self, *args): return self._color(self._fillcolor) def teleport(self, x=None, y=None, *, fill_gap: bool = False) -> None: - """To be overwritten by child class RawTurtle. + """To be overwritten by the child class RawTurtle. Includes no TNavigator references. """ @@ -2393,7 +2409,7 @@ def hideturtle(self): self.pen(shown=False) def isvisible(self): - """Return True if the turtle is shown, False if it's hidden. + """Return True if the turtle is visible, False if it's hidden. Example (for a Turtle instance named turtle): >>> turtle.hideturtle() @@ -2655,18 +2671,17 @@ def reset(self): self._update() def setundobuffer(self, size): - """Set or disable undobuffer. + """Set or disable the undo buffer. - Argument: - size -- an integer or None + If size is an integer, an empty undo buffer of the given size is + installed. size is the maximum number of turtle actions that can + be undone by undo(). If size is None, the undo buffer is disabled. - If size is an integer an empty undobuffer of given size is installed. - Size gives the maximum number of turtle-actions that can be undone - by the undo() function. - If size is None, no undobuffer is present. + Argument: + size -- an integer or None Example (for a Turtle instance named turtle): - >>> turtle.setundobuffer(42) + >>> turtle.setundobuffer(42) """ if size is None or size <= 0: self.undobuffer = None @@ -2674,7 +2689,7 @@ def setundobuffer(self, size): self.undobuffer = Tbuffer(size) def undobufferentries(self): - """Return the number of entries in the undobuffer. + """Return the number of entries in the undo buffer. Example (for a Turtle instance named turtle): >>> while undobufferentries(): @@ -2736,24 +2751,7 @@ def _update(self): screen._update() def _tracer(self, flag=None, delay=None): - """Turns turtle animation on/off and set delay for update drawings. - - Optional arguments: - n -- nonnegative integer - delay -- nonnegative integer - - If n is given, only each n-th regular screen update is really performed. - (Can be used to accelerate the drawing of complex graphics.) - Second arguments sets delay value (see RawTurtle.delay()) - - Example (for a Turtle instance named turtle): - >>> turtle.tracer(8, 25) - >>> dist = 2 - >>> for i in range(200): - ... turtle.fd(dist) - ... turtle.rt(90) - ... dist += 2 - """ + """Forward flag and delay to the screen's tracer() method.""" return self.screen.tracer(flag, delay) def _color(self, args): @@ -2777,39 +2775,35 @@ def _cc(self, args): return "#%02x%02x%02x" % (r, g, b) def teleport(self, x=None, y=None, *, fill_gap: bool = False) -> None: - """Instantly move turtle to an absolute position. + """Instantly move the turtle to an absolute position. + + Unlike goto(), no line is drawn. If x or y is not given, that + coordinate is kept as it is. The turtle's heading does not change. + + If the turtle is filling a shape, the shape drawn so far is + finished and filled before the jump, and filling starts again at + the new position. Pass fill_gap=True to keep filling one shape + instead. The jump then counts as an edge of the shape, as it + would with goto(). Arguments: - x -- a number or None - y -- a number None - fill_gap -- a boolean This argument must be specified by name. - - call: teleport(x, y) # two coordinates - --or: teleport(x) # teleport to x position, keeping y as is - --or: teleport(y=y) # teleport to y position, keeping x as is - --or: teleport(x, y, fill_gap=True) - # teleport but fill the gap in between - - Move turtle to an absolute position. Unlike goto(x, y), a line will not - be drawn. The turtle's orientation does not change. If currently - filling, the polygon(s) teleported from will be filled after leaving, - and filling will begin again after teleporting. This can be disabled - with fill_gap=True, which makes the imaginary line traveled during - teleporting act as a fill barrier like in goto(x, y). + x -- a number or None + y -- a number or None + fill_gap -- a boolean Example (for a Turtle instance named turtle): - >>> tp = turtle.pos() - >>> tp - (0.00,0.00) - >>> turtle.teleport(60) - >>> turtle.pos() - (60.00,0.00) - >>> turtle.teleport(y=10) - >>> turtle.pos() - (60.00,10.00) - >>> turtle.teleport(20, 30) - >>> turtle.pos() - (20.00,30.00) + >>> tp = turtle.pos() + >>> tp + (0.00,0.00) + >>> turtle.teleport(60) + >>> turtle.pos() + (60.00,0.00) + >>> turtle.teleport(y=10) + >>> turtle.pos() + (60.00,10.00) + >>> turtle.teleport(20, 30) + >>> turtle.pos() + (20.00,30.00) """ pendown = self.isdown() was_filling = self.filling() @@ -2830,14 +2824,11 @@ def teleport(self, x=None, y=None, *, fill_gap: bool = False) -> None: def clone(self): """Create and return a clone of the turtle. - No argument. + The clone has the same position, heading and turtle properties. - Create and return a clone of the turtle with same position, heading - and turtle properties. - - Example (for a Turtle instance named mick): - mick = Turtle() - joe = mick.clone() + Example: + >>> leonel = Turtle() + >>> marco = leonel.clone() """ screen = self.screen self._newLine(self._drawing) @@ -2868,24 +2859,23 @@ def clone(self): return q def shape(self, name=None): - """Set turtle shape to shape with given name / return current shapename. + """Set the turtle shape to the shape with the given name. - Optional argument: - name -- a string, which is a valid shapename + If name is not given, return the name of the current shape. The + shape must exist in the TurtleScreen's shape dictionary. Initially + there are the following polygon shapes: "arrow", "turtle", + "circle", "square", "triangle" and "classic". To add shapes, + see the Screen method register_shape(). - Set turtle shape to shape with given name or, if name is not given, - return name of current shape. - Shape with name must exist in the TurtleScreen's shape dictionary. - Initially there are the following polygon shapes: - 'arrow', 'turtle', 'circle', 'square', 'triangle', 'classic'. - To learn about how to deal with shapes see Screen-method register_shape. + Argument: + name -- a string or None Example (for a Turtle instance named turtle): - >>> turtle.shape() - 'arrow' - >>> turtle.shape("turtle") - >>> turtle.shape() - 'turtle' + >>> turtle.shape() + 'classic' + >>> turtle.shape("turtle") + >>> turtle.shape() + 'turtle' """ if name is None: return self.turtle.shapeIndex @@ -2895,25 +2885,33 @@ def shape(self, name=None): self._update() def shapesize(self, stretch_wid=None, stretch_len=None, outline=None): - """Set/return turtle's stretchfactors/outline. Set resizemode to "user". + """Return or set the turtle's stretch factors and outline width. - Optional arguments: - stretch_wid : positive number - stretch_len : positive number - outline : positive number - - Return or set the pen's attributes x/y-stretchfactors and/or outline. - Set resizemode to "user". - If and only if resizemode is set to "user", the turtle will be displayed - stretched according to its stretchfactors: - stretch_wid is stretchfactor perpendicular to orientation - stretch_len is stretchfactor in direction of turtles orientation. - outline determines the width of the shapes's outline. + Aliases: shapesize | turtlesize - Examples (for a Turtle instance named turtle): - >>> turtle.resizemode("user") - >>> turtle.shapesize(5, 5, 12) - >>> turtle.shapesize(outline=8) + If no arguments are given, return the current values. Otherwise + set resizemode to "user", so that the turtle is displayed + stretched according to its stretch factors. stretch_wid is the + stretch factor perpendicular to the turtle's heading and + stretch_len the stretch factor in the direction of its heading. + If only stretch_wid is given, stretch_len is set to the same + value. outline is the width of the shape's outline. + + Arguments: + stretch_wid -- a positive number or None + stretch_len -- a positive number or None + outline -- a positive number or None + + Example (for a Turtle instance named turtle): + >>> turtle.shapesize() + (1.0, 1.0, 1) + >>> turtle.resizemode("user") + >>> turtle.shapesize(5, 5, 12) + >>> turtle.shapesize() + (5, 5, 12) + >>> turtle.shapesize(outline=8) + >>> turtle.shapesize() + (5, 5, 8) """ if stretch_wid is stretch_len is outline is None: stretch_wid, stretch_len = self._stretchfactor @@ -3389,16 +3387,14 @@ def _newLine(self, usePos=True): self.currentLine = [self._position] def filling(self): - """Return fillstate (True if filling, False else). - - No argument. + """Return True if the turtle is filling, False otherwise. Example (for a Turtle instance named turtle): - >>> turtle.begin_fill() - >>> if turtle.filling(): - ... turtle.pensize(5) - ... else: - ... turtle.pensize(3) + >>> turtle.begin_fill() + >>> if turtle.filling(): + ... turtle.pensize(5) + ... else: + ... turtle.pensize(3) """ return isinstance(self._fillpath, list) @@ -3461,18 +3457,19 @@ def end_fill(self): self._update() def dot(self, size=None, *color): - """Draw a dot with diameter size, using color. + """Draw a circular dot with diameter size, using color. - Optional arguments: - size -- an integer >= 1 (if given) - color -- a colorstring or a numeric color tuple + If size is not given, the larger of pensize + 4 and 2 * pensize is + used. If color is not given, the current pencolor is used. - Draw a circular dot with diameter size, using color. - If size is not given, the maximum of pensize+4 and 2*pensize is used. + Arguments: + size -- a positive integer or None + color -- a colorstring or a numeric color tuple Example (for a Turtle instance named turtle): - >>> turtle.dot() - >>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50) + >>> turtle.home() + >>> turtle.dot() + >>> turtle.fd(50); turtle.dot(20, "blue"); turtle.fd(50) """ if not color: if isinstance(size, (str, tuple)): @@ -3605,15 +3602,18 @@ def getscreen(self): return self.screen def getturtle(self): - """Return the Turtleobject itself. + """Return the Turtle object itself. + + Aliases: getturtle | getpen - Only reasonable use: as a function to return the 'anonymous turtle': + Generally used as a function, to get the anonymous turtle used by + the module-level functions. Example: >>> pet = getturtle() >>> pet.fd(50) >>> pet - + """ return self From 284e767da4619e030693c694121f0b1e13eaedf7 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 20 Oct 2026 18:59:42 +0100 Subject: [PATCH 2/2] Apply review suggestions Co-authored-by: Maciej Olko Co-Authored-By: Carol Willing --- Doc/library/turtle.rst | 59 ++++++++++++++++++++++++++---------------- Lib/turtle.py | 46 ++++++++++++++++++-------------- 2 files changed, 63 insertions(+), 42 deletions(-) diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index 6fad6bcac4fd2e..39f8e5c6f226ee 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -356,14 +356,14 @@ Move and draw :param y: a number or ``None`` :param fill_gap: a boolean - Instantly move the turtle to an absolute position. Unlike :func:`goto`, no - line is drawn. If *x* or *y* is not given, that coordinate is kept as it - is. The turtle's heading does not change. + Teleport, or instantly move, the turtle to an absolute position. Unlike + :func:`goto`, no line is drawn. If *x* or *y* is not given, that coordinate + is kept as it is. The turtle's heading does not change. If the turtle is filling a shape, the shape drawn so far is finished and - filled before the jump, and filling starts again at the new position. Pass - ``fill_gap=True`` to keep filling one shape instead. The jump then counts - as an edge of the shape, as it would with :func:`goto`. + filled before teleporting, and filling starts again at the new position. + Pass ``fill_gap=True`` to keep filling one shape instead. The teleport then + counts as an edge of the shape, as it would with :func:`goto`. .. doctest:: :skipif: _tkinter is None @@ -626,7 +626,7 @@ Move and draw Return or set the turtle's speed. If *speed* is not given, return the current speed. Otherwise set the turtle's speed to an integer from 0 to 10. If *speed* is a number greater than 10 or smaller than 0.5, the speed is - set to 0. A speed string is mapped to a speed value as follows: + set to 0. You can also use these names instead of numbers: * "fastest": 0 * "fast": 10 @@ -816,14 +816,14 @@ Drawing state pd() down() - Pull the pen down. The turtle draws a line when it moves. + Lower the pen. The turtle draws a line when it moves. .. function:: penup() pu() up() - Pull the pen up. The turtle does not draw when it moves. + Lift the pen. The turtle does not draw when it moves. .. function:: pensize(width=None) @@ -831,9 +831,9 @@ Drawing state :param width: a positive number or ``None`` - Set the line thickness to *width* or return it. If *width* is not given, - return the current pensize. If resizemode is set to "auto" and the turtle - shape is a polygon, that polygon is drawn with the same line thickness. + Return or set the line thickness. If *width* is not given, return the + current pensize. If resizemode is set to "auto" and the turtle shape is a + polygon, that polygon is drawn with the same line thickness. .. doctest:: :skipif: _tkinter is None @@ -1201,11 +1201,11 @@ Appearance :param name: a string or ``None`` - Set the turtle shape to the shape with the given *name*. If *name* is not - given, return the name of the current shape. The shape must exist in the + Set the turtle shape to the named shape. If *name* is not given, return the + name of the current shape. The shape must exist in the :class:`TurtleScreen`'s shape dictionary. Initially there are the following - polygon shapes: "arrow", "turtle", "circle", "square", "triangle" and - "classic". To add shapes, see the :class:`Screen` method :func:`register_shape`. + shapes: "arrow", "turtle", "circle", "square", "triangle" and "classic". To + add shapes, see the :class:`Screen` method :func:`register_shape`. .. doctest:: :skipif: _tkinter is None @@ -1253,10 +1253,16 @@ Appearance Return or set the turtle's stretch factors and outline width. If no arguments are given, return the current values. Otherwise set resizemode to "user", so that the turtle is displayed stretched according to its stretch - factors. *stretch_wid* is the stretch factor perpendicular to the turtle's - heading and *stretch_len* the stretch factor in the direction of its - heading. If only *stretch_wid* is given, *stretch_len* is set to the same - value. *outline* is the width of the shape's outline. + factors: + + - *stretch_wid*: the stretch factor perpendicular to the turtle's heading + - *stretch_len*: the stretch factor in the direction of the turtle's + heading + - *outline*: the width of the shape's outline + + For example, ``shapesize(2, 1)`` makes the turtle twice as wide without + changing its length. If only *stretch_wid* is given, *stretch_len* is set to + the same value. .. doctest:: :skipif: _tkinter is None @@ -1520,8 +1526,8 @@ Special Turtle methods Return the Turtle object itself. - Generally used as a function, to get the anonymous turtle used by the - module-level functions: + Call ``getturtle()`` to get the turtle used by functions such as + :func:`forward` and :func:`left`: .. doctest:: :skipif: _tkinter is None @@ -2295,6 +2301,8 @@ How-to guides This section covers some typical turtle use-cases and approaches. +.. _automatically-begin-and-end-filling: + How to automatically begin and end filling ------------------------------------------ @@ -2321,6 +2329,7 @@ The code above is equivalent to:: .. _compoundshapes: +.. _compound-shapes: How to use compound shapes -------------------------- @@ -2353,6 +2362,8 @@ below: >>> shape("myshape") +.. _use-the-turtle-module-namespace: + How to use the ``turtle`` module namespace ------------------------------------------ @@ -2368,6 +2379,8 @@ The solution is to use ``import turtle`` - ``fd()`` becomes as t`` instead.) +.. _use-turtle-graphics-in-a-script: + How to use turtle graphics in a script -------------------------------------- @@ -2393,6 +2406,8 @@ will not exit until it is terminated, for example by closing the turtle graphics window. +.. _use-object-oriented-turtle-graphics: + How to use object-oriented turtle graphics ------------------------------------------ diff --git a/Lib/turtle.py b/Lib/turtle.py index ab7a193a2cb7bf..fbd1ff4870003d 100644 --- a/Lib/turtle.py +++ b/Lib/turtle.py @@ -2154,7 +2154,7 @@ def resizemode(self, rmode=None): self.pen(resizemode=rmode) def pensize(self, width=None): - """Set the line thickness to width or return it. + """Return or set the line thickness. Aliases: pensize | width @@ -2176,7 +2176,7 @@ def pensize(self, width=None): def penup(self): - """Pull the pen up. + """Lift the pen. Aliases: penup | pu | up @@ -2187,7 +2187,7 @@ def penup(self): self.pen(pendown=False) def pendown(self): - """Pull the pen down. + """Lower the pen. Aliases: pendown | pd | down @@ -2215,8 +2215,8 @@ def speed(self, speed=None): If speed is not given, return the current speed. Otherwise set the turtle's speed to an integer from 0 to 10. If speed is a number - greater than 10 or smaller than 0.5, the speed is set to 0. A - speed string is mapped to a speed value as follows: + greater than 10 or smaller than 0.5, the speed is set to 0. You + can also use these names instead of numbers: "fastest": 0 "fast": 10 @@ -2775,15 +2775,15 @@ def _cc(self, args): return "#%02x%02x%02x" % (r, g, b) def teleport(self, x=None, y=None, *, fill_gap: bool = False) -> None: - """Instantly move the turtle to an absolute position. + """Teleport, or instantly move, the turtle to an absolute position. Unlike goto(), no line is drawn. If x or y is not given, that coordinate is kept as it is. The turtle's heading does not change. If the turtle is filling a shape, the shape drawn so far is - finished and filled before the jump, and filling starts again at - the new position. Pass fill_gap=True to keep filling one shape - instead. The jump then counts as an edge of the shape, as it + finished and filled before teleporting, and filling starts again + at the new position. Pass fill_gap=True to keep filling one shape + instead. The teleport then counts as an edge of the shape, as it would with goto(). Arguments: @@ -2859,13 +2859,13 @@ def clone(self): return q def shape(self, name=None): - """Set the turtle shape to the shape with the given name. + """Set the turtle shape to the named shape. If name is not given, return the name of the current shape. The shape must exist in the TurtleScreen's shape dictionary. Initially - there are the following polygon shapes: "arrow", "turtle", - "circle", "square", "triangle" and "classic". To add shapes, - see the Screen method register_shape(). + there are the following shapes: "arrow", "turtle", "circle", + "square", "triangle" and "classic". To add shapes, see the Screen + method register_shape(). Argument: name -- a string or None @@ -2891,11 +2891,17 @@ def shapesize(self, stretch_wid=None, stretch_len=None, outline=None): If no arguments are given, return the current values. Otherwise set resizemode to "user", so that the turtle is displayed - stretched according to its stretch factors. stretch_wid is the - stretch factor perpendicular to the turtle's heading and - stretch_len the stretch factor in the direction of its heading. - If only stretch_wid is given, stretch_len is set to the same - value. outline is the width of the shape's outline. + stretched according to its stretch factors: + + - stretch_wid: the stretch factor perpendicular to the turtle's + heading + - stretch_len: the stretch factor in the direction of the + turtle's heading + - outline: the width of the shape's outline + + For example, shapesize(2, 1) makes the turtle twice as wide + without changing its length. If only stretch_wid is given, + stretch_len is set to the same value. Arguments: stretch_wid -- a positive number or None @@ -3606,8 +3612,8 @@ def getturtle(self): Aliases: getturtle | getpen - Generally used as a function, to get the anonymous turtle used by - the module-level functions. + Call getturtle() to get the turtle used by functions such as + forward() and left(). Example: >>> pet = getturtle()