diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index 76063e3dc911860..39f8e5c6f226eea 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). + 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 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 @@ -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. You can also use these names instead of numbers: - * "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. + Lower the pen. The turtle draws a line when it moves. .. function:: penup() pu() up() - Pull the pen up -- no drawing when moving. + Lift the pen. 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. + 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 @@ -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 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 + 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,23 @@ 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 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: - 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. + - *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 @@ -1456,7 +1462,6 @@ Using events Special Turtle methods ^^^^^^^^^^^^^^^^^^^^^^ - .. function:: poly() Record the vertices of a polygon drawn in the ``with turtle.poly():`` block. @@ -1506,21 +1511,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. + + Call ``getturtle()`` to get the turtle used by functions such as + :func:`forward` and :func:`left`: .. doctest:: :skipif: _tkinter is None @@ -1549,10 +1556,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 +1569,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 +1578,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 +1593,7 @@ Most of the examples in this section refer to a TurtleScreen instance called >>> screen = Screen() + Window control ^^^^^^^^^^^^^^ @@ -2171,6 +2138,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 +2181,6 @@ Screen-only methods Public classes -------------- - .. class:: RawTurtle(canvas) RawPen(canvas) @@ -2237,6 +2204,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 +2301,10 @@ How-to guides This section covers some typical turtle use-cases and approaches. -Automatically begin and end filling ------------------------------------ +.. _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 +2328,44 @@ The code above is equivalent to:: forward(200) -Use the ``turtle`` module namespace ------------------------------------ +.. _compoundshapes: +.. _compound-shapes: + +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") + + +.. _use-the-turtle-module-namespace: + +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 +2379,10 @@ The solution is to use ``import turtle`` - ``fd()`` becomes as t`` instead.) -Use turtle graphics in a script -------------------------------- +.. _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 +2406,10 @@ will not exit until it is terminated, for example by closing the turtle graphics window. -Use object-oriented turtle graphics ------------------------------------ +.. _use-object-oriented-turtle-graphics: + +How to use object-oriented turtle graphics +------------------------------------------ .. seealso:: :ref:`Explanation of the object-oriented interface ` @@ -2438,8 +2448,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 893994b5c1700c6..fbd1ff4870003de 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. + """Return or set the line thickness. - 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. + """Lift the pen. 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. + """Lower the pen. 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. You + can also use these names instead of numbers: + + "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. + """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 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: - 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. - - Create and return a clone of the turtle with same position, heading - and turtle properties. + The clone has the 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 named shape. - 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 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,39 @@ 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: 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 + 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 +3393,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 +3463,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 +3608,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': + Call getturtle() to get the turtle used by functions such as + forward() and left(). Example: >>> pet = getturtle() >>> pet.fd(50) >>> pet - + """ return self