https://github.com/python/cpython/commit/35ab5bcd4d91f214ac85c81dc19284c56ed26776 commit: 35ab5bcd4d91f214ac85c81dc19284c56ed26776 branch: 3.14 author: Miss Islington (bot) <[email protected]> committer: StanFromIreland <[email protected]> date: 2026-10-11T13:36:15Z summary:
[3.14] gh-157847: Improve more `turtle` docstrings and docs (GH-158562) (#159171) (cherry picked from commit 77f7b96c2c77ac6d83155fe2659513ee6bcd5623) Co-authored-by: Stan Ulbrych <[email protected]> Co-authored-by: Terry Reedy <[email protected]> files: M Doc/library/idle.rst M Doc/library/turtle.rst M Lib/turtle.py diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst index 89be225b6baae4c..d5b5508d526a99d 100644 --- a/Doc/library/idle.rst +++ b/Doc/library/idle.rst @@ -933,6 +933,8 @@ the mainloop call. One then gets a shell prompt immediately and can interact with the live application. One just has to remember to re-enable the mainloop call when running in standard Python. +.. _idle-no-subprocess: + Running without a subprocess ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index fe475ed301cf8ab..7519752d7c123e1 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -84,6 +84,13 @@ In a Python shell, import all the objects of the ``turtle`` module:: If you run into a ``No module named '_tkinter'`` error, you'll have to install the :mod:`Tk interface package <tkinter>` on your system. +Nothing appears yet. To open the turtle window, make the turtle visible:: + + showturtle() + +A new window opens, with the turtle in the middle, shown as an arrow +heading East. + Basic drawing ------------- @@ -92,9 +99,9 @@ Send the turtle forward 100 steps:: forward(100) -You should see (most likely, in a new window on your display) a line -drawn by the turtle, heading East. Change the direction of the turtle, -so that it turns 120 degrees left (anti-clockwise):: +You should see a line drawn by the turtle, heading East. Change the +direction of the turtle, so that it turns 120 degrees left +(anti-clockwise):: left(120) @@ -908,7 +915,8 @@ Color control ``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. + :func:`color`, :func:`pencolor`, :func:`fillcolor` or :func:`bgcolor` + call. ``pencolor(colorstring)`` Set pencolor to *colorstring*, which is a Tk color specification string, @@ -959,7 +967,8 @@ Color control ``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. + :func:`color`, :func:`pencolor`, :func:`fillcolor` or :func:`bgcolor` + call. ``fillcolor(colorstring)`` Set fillcolor to *colorstring*, which is a Tk color specification string, @@ -1108,8 +1117,8 @@ More drawing control .. function:: reset() - Delete the turtle's drawings from the screen, re-center the turtle and set - variables to the default values. + Delete the turtle's drawings and re-center the turtle. The turtle's + settings are restored to their default values. .. doctest:: :skipif: _tkinter is None @@ -1129,8 +1138,8 @@ More drawing control .. function:: clear() - Delete the turtle's drawings from the screen. Do not move turtle. State and - position of the turtle as well as drawings of other turtles are not affected. + Delete the turtle's drawings from the screen. The state and position of the + turtle as well as the drawings of other turtles are not affected. .. function:: write(arg, move=False, align="left", font=("Arial", 8, "normal")) @@ -1161,14 +1170,7 @@ Visibility .. function:: hideturtle() ht() - Make the turtle invisible. It's a good idea to do this while you're in the - middle of doing some complex drawing, because hiding the turtle speeds up the - drawing observably. - - .. doctest:: - :skipif: _tkinter is None - - >>> turtle.hideturtle() + Make the turtle invisible. If the pen is down, movement still draws. .. function:: showturtle() @@ -1176,15 +1178,10 @@ Visibility Make the turtle visible. - .. doctest:: - :skipif: _tkinter is None - - >>> turtle.showturtle() - .. function:: isvisible() - Return ``True`` if the Turtle is shown, ``False`` if it's hidden. + Return ``True`` if the turtle is shown, ``False`` if it's hidden. .. doctest:: :skipif: _tkinter is None @@ -1386,15 +1383,16 @@ Using events .. function:: onclick(fun, btn=1, add=None) :noindex: - :param fun: a function with two arguments which will be called with the - coordinates of the clicked point on the canvas - :param btn: number of the mouse-button, defaults to 1 (left mouse button) - :param add: ``True`` or ``False`` -- if ``True``, a new binding will be - added, otherwise it will replace a former binding + :param fun: a function with two arguments or ``None`` + :param btn: an integer + :param add: a boolean or ``None`` - Bind *fun* to mouse-click events on this turtle. If *fun* is ``None``, - existing bindings are removed. Example for the anonymous turtle, i.e. the - procedural way: + Bind *fun* to mouse-click events on this turtle. *fun* is called with the + coordinates of the clicked point on the canvas. If *fun* is ``None``, + existing bindings are removed. *btn* is the number of the mouse button and + defaults to 1, the left mouse button. If *add* is ``True``, a new binding + is added, otherwise it replaces a former binding. Example for the + anonymous turtle, that is, the procedural way: .. doctest:: :skipif: _tkinter is None @@ -1476,14 +1474,14 @@ Special Turtle methods .. function:: begin_poly() - Start recording the vertices of a polygon. Current turtle position is first - vertex of polygon. + Start recording the vertices of a polygon. The current turtle position is + the first vertex of the polygon. .. function:: end_poly() - Stop recording the vertices of a polygon. Current turtle position is last - vertex of polygon. This will be connected with the first vertex. + Stop recording the vertices of a polygon. The current turtle position is + the last vertex of the polygon. This will be connected with the first vertex. .. function:: get_poly() @@ -1640,9 +1638,10 @@ Window control Four input formats are allowed: ``bgcolor()`` - Return the current background color as color specification string or + Return the current background color as a color specification string or as a tuple (see example). May be used as input to another - color/pencolor/fillcolor/bgcolor call. + :func:`color`, :func:`pencolor`, :func:`fillcolor` or :func:`bgcolor` + call. ``bgcolor(colorstring)`` Set the background color to *colorstring*, which is a Tk color @@ -1651,12 +1650,12 @@ Window control ``bgcolor((r, g, b))`` Set the background color 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 + Each of *r*, *g*, and *b* must be between 0 and colormode, where colormode is either 1.0 or 255 (see :func:`colormode`). ``bgcolor(r, g, b)`` - Set the background color 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 background color to the RGB color represented by *r*, *g*, and + *b*. Each of *r*, *g*, and *b* must be between 0 and colormode. .. doctest:: :skipif: _tkinter is None @@ -1713,7 +1712,7 @@ Window control .. function:: resetscreen() - Reset all Turtles on the Screen to their initial state. + Reset all turtles on the screen to their initial state. .. function:: screensize(canvwidth=None, canvheight=None, bg=None) @@ -1742,17 +1741,17 @@ Window control .. function:: setworldcoordinates(llx, lly, urx, ury) - :param llx: a number, x-coordinate of lower left corner of canvas - :param lly: a number, y-coordinate of lower left corner of canvas - :param urx: a number, x-coordinate of upper right corner of canvas - :param ury: a number, y-coordinate of upper right corner of canvas - - Set up user-defined coordinate system and switch to mode "world" if - necessary. This performs a ``screen.reset()``. If mode "world" is already - active, all drawings are redrawn according to the new coordinates. + :param llx: a number + :param lly: a number + :param urx: a number + :param ury: a number - **ATTENTION**: in user-defined coordinate systems angles may appear - distorted. + Set up a user-defined coordinate system. *llx* and *lly* are the x and y + coordinates of the lower left corner of the canvas. *urx* and *ury* are the + x and y coordinates of the upper right corner. Switch to mode "world" if + necessary, which performs a reset. If mode "world" is already active, all + drawings are redrawn according to the new coordinates. In user-defined + coordinate systems, angles may appear distorted, see :func:`mode`. .. doctest:: :skipif: _tkinter is None @@ -1779,9 +1778,10 @@ Animation control .. function:: no_animation() - Temporarily disable turtle animation. The code written inside the - ``no_animation`` block will not be animated; - once the code block is exited, the drawing will appear. + Temporarily turn off turtle animation. The code inside the :keyword:`with` + block is not animated. Once the block is exited, the drawing appears. This + is useful for drawing complex shapes where even the fastest speed setting + is too slow. .. doctest:: :skipif: _tkinter is None @@ -1796,14 +1796,12 @@ Animation control .. function:: delay(delay=None) - :param delay: positive integer + :param delay: a nonnegative integer or ``None`` - Set or return the drawing *delay* in milliseconds. (This is approximately - the time interval between two consecutive canvas updates.) The longer the + Return or set the drawing delay in milliseconds. This is approximately the + time interval between two consecutive canvas updates. The longer the drawing delay, the slower the animation. - Optional argument: - .. doctest:: :skipif: _tkinter is None @@ -1816,15 +1814,15 @@ Animation control .. function:: tracer(n=None, delay=None) - :param n: nonnegative integer - :param delay: nonnegative integer + :param n: a nonnegative integer or ``None`` + :param delay: a nonnegative integer or ``None`` - Turn turtle animation on/off and set delay for update drawings. If - *n* is given, only each n-th regular screen update is really - performed. (Can be used to accelerate the drawing of complex - graphics.) When called without arguments, returns the currently - stored value of n. Second argument sets delay value (see - :func:`delay`). + Turn turtle animation on or off and set the drawing delay. If *n* is given, + only every n-th regular screen update is performed, which can be used to + speed up the drawing of complex graphics. If *n* is 0, animation is turned + off and the screen is only updated by calling :func:`update`. If *delay* is + given, it sets the drawing delay, see :func:`delay`. When called without + arguments, return the current value of *n*. .. doctest:: :skipif: _tkinter is None @@ -1897,14 +1895,15 @@ Using screen events .. function:: onclick(fun, btn=1, add=None) onscreenclick(fun, btn=1, add=None) - :param fun: a function with two arguments which will be called with the - coordinates of the clicked point on the canvas - :param btn: number of the mouse-button, defaults to 1 (left mouse button) - :param add: ``True`` or ``False`` -- if ``True``, a new binding will be - added, otherwise it will replace a former binding + :param fun: a function with two arguments or ``None`` + :param btn: an integer + :param add: a boolean or ``None`` - Bind *fun* to mouse-click events on this screen. If *fun* is ``None``, - existing bindings are removed. + Bind *fun* to mouse-click events on this screen. *fun* is called with the + coordinates of the clicked point on the canvas. If *fun* is ``None``, + existing bindings are removed. *btn* is the number of the mouse button and + defaults to 1, the left mouse button. If *add* is ``True``, a new binding + is added, otherwise it replaces a former binding. Example for a TurtleScreen instance named ``screen`` and a Turtle instance named ``turtle``: @@ -1945,12 +1944,10 @@ Using screen events .. function:: mainloop() done() - Starts event loop - calling Tkinter's mainloop function. - Must be the last statement in a turtle graphics program. - Must *not* be used if a script is run from within IDLE in -n mode - (No subprocess) - for interactive use of turtle graphics. :: - - >>> screen.mainloop() + Start the event loop by calling Tkinter's :meth:`~tkinter.Misc.mainloop` + method. Must be the last statement in a turtle graphics program. Must + *not* be used if a script is run from within IDLE in -n mode (see + :ref:`idle-no-subprocess`). Input methods @@ -1958,33 +1955,31 @@ Input methods .. function:: textinput(title, prompt) - :param title: string - :param prompt: string + :param title: a string + :param prompt: a string - Pop up a dialog window for input of a string. Parameter title is - the title of the dialog window, prompt is a text mostly describing - what information to input. - Return the string input. If the dialog is canceled, return ``None``. :: + Pop up a dialog window for input of a string. *title* is the title of the + dialog window and *prompt* is a text describing what information to input. + Return the string entered. If the dialog is canceled, return ``None``. :: >>> screen.textinput("NIM", "Name of first player:") .. function:: numinput(title, prompt, default=None, minval=None, maxval=None) - :param title: string - :param prompt: string - :param default: number (optional) - :param minval: number (optional) - :param maxval: number (optional) - - Pop up a dialog window for input of a number. title is the title of the - dialog window, prompt is a text mostly describing what numerical information - to input. default: default value, minval: minimum value for input, - maxval: maximum value for input. - The number input must be in the range minval .. maxval if these are - given. If not, a hint is issued and the dialog remains open for - correction. - Return the number input. If the dialog is canceled, return ``None``. :: + :param title: a string + :param prompt: a string + :param default: a number or ``None`` + :param minval: a number or ``None`` + :param maxval: a number or ``None`` + + Pop up a dialog window for input of a number. *title* is the title of the + dialog window and *prompt* is a text describing what numerical information + to input. *default* is the default value, *minval* and *maxval* are the + minimum and maximum values for input. If these are given, the number + entered must be between *minval* and *maxval*. If not, a hint is issued + and the dialog remains open for correction. Return the number entered. If + the dialog is canceled, return ``None``. :: >>> screen.numinput("Poker", "Your stakes:", 1000, minval=10, maxval=10000) @@ -1994,15 +1989,16 @@ Settings and special methods .. function:: mode(mode=None) - :param mode: one of the strings "standard", "logo" or "world" + :param mode: a string or ``None`` - Set turtle mode ("standard", "logo" or "world") and perform reset. If mode - is not given, current mode is returned. + Set the turtle mode and perform a reset. *mode* is one of the strings + "standard", "logo" or "world". If *mode* is not given, return the current + mode. - Mode "standard" is compatible with old :mod:`!turtle`. Mode "logo" is - compatible with most Logo turtle graphics. Mode "world" uses user-defined - "world coordinates". **Attention**: in this mode angles appear distorted if - ``x/y`` unit-ratio doesn't equal 1. + Mode "standard" is compatible with the old :mod:`!turtle` module. Mode + "logo" is compatible with most Logo turtle graphics. Mode "world" uses + user-defined world coordinates, see :func:`setworldcoordinates`. In this + mode, angles appear distorted if the x and y units are not of equal length. ============ ========================= =================== Mode Initial turtle heading positive angles @@ -2014,17 +2010,17 @@ Settings and special methods .. doctest:: :skipif: _tkinter is None - >>> mode("logo") # resets turtle heading to north + >>> mode("logo") # resets turtle heading to north >>> mode() 'logo' .. function:: colormode(cmode=None) - :param cmode: one of the values 1.0 or 255 + :param cmode: a number or ``None`` - Return the colormode or set it to 1.0 or 255. Subsequently *r*, *g*, *b* - values of color triples have to be in the range 0..*cmode*. + Return the colormode or set it to 1.0 or 255. After setting it, the *r*, + *g* and *b* values of color triples have to be between 0 and *cmode*. .. doctest:: :skipif: _tkinter is None @@ -2069,26 +2065,23 @@ Settings and special methods .. function:: register_shape(name, shape=None) addshape(name, shape=None) - There are four different ways to call this function: + :param name: a string + :param shape: a string, a tuple of pairs of numbers, a :class:`Shape` + object or ``None`` - (1) *name* is the name of an image file (PNG, GIF, PGM, and PPM) and *shape* is ``None``: Install the - corresponding image shape. :: + Add a turtle shape to the TurtleScreen's shape list. It can be called in + four different ways: - >>> screen.register_shape("turtle.gif") + (1) *name* is the name of an image file (PNG, GIF, PGM, and PPM) and + *shape* is ``None``: Install the corresponding image shape. :: - .. note:: - Image shapes *do not* rotate when turning the turtle, so they do not - display the heading of the turtle! + >>> screen.register_shape("turtle.gif") - (2) *name* is an arbitrary string and *shape* is the name of an image file (PNG, GIF, PGM, and PPM): Install the - corresponding image shape. :: + (2) *name* is an arbitrary string and *shape* is the name of an image file + (PNG, GIF, PGM, and PPM): Install the corresponding image shape. :: >>> screen.register_shape("turtle", "turtle.gif") - .. note:: - Image shapes *do not* rotate when turning the turtle, so they do not - display the heading of the turtle! - (3) *name* is an arbitrary string and *shape* is a tuple of pairs of coordinates: Install the corresponding polygon shape. @@ -2100,8 +2093,9 @@ Settings and special methods (4) *name* is an arbitrary string and *shape* is a (compound) :class:`Shape` object: Install the corresponding compound shape. - Add a turtle shape to TurtleScreen's shapelist. Only thusly registered - shapes can be used by issuing the command ``shape(shapename)``. + Image shapes do not rotate when turning the turtle, so they do not display + the heading of the turtle. To use a registered shape, call :func:`shape` + with its name. .. versionchanged:: 3.14 Added support for PNG, PGM, and PPM image formats. @@ -2143,7 +2137,7 @@ Screen-only methods .. function:: bye() - Shut the turtlegraphics window. + Close the turtle graphics window. .. function:: exitonclick() @@ -2204,10 +2198,10 @@ Screen-only methods .. function:: title(titlestring) - :param titlestring: a string that is shown in the titlebar of the turtle - graphics window + :param titlestring: a string - Set title of turtle window to *titlestring*. + Set the title of the turtle window to *titlestring*. The title is shown in + the title bar of the turtle graphics window. .. doctest:: :skipif: _tkinter is None @@ -2244,7 +2238,10 @@ Public classes .. class:: Screen() - Subclass of TurtleScreen, with :ref:`four methods added <screenspecific>`. + Subclass of :class:`TurtleScreen`, with :ref:`four methods added + <screenspecific>`. Calling ``Screen()`` returns the single screen object. + If it does not exist yet, it is created. Otherwise the existing one is + returned. .. class:: ScrolledCanvas(master) @@ -2257,33 +2254,32 @@ Public classes .. class:: Shape(type_, data) - :param type\_: one of the strings "polygon", "image", "compound" - - Data structure modeling shapes. The pair ``(type_, data)`` must follow this - specification: + :param type\_: a string + :param data: depends on *type_* - - =========== =========== - *type_* *data* - =========== =========== - "polygon" a polygon-tuple, i.e. a tuple of pairs of coordinates - "image" an image (in this form only used internally!) - "compound" ``None`` (a compound shape has to be constructed using the - :meth:`addcomponent` method) - =========== =========== + Data structure modeling shapes. *type_* is one of the strings "polygon", + "image" or "compound". What *data* must be depends on *type_*: for + "polygon" a tuple of pairs of coordinates, for "image" an image (only used + internally), and for "compound" ``None``, as a compound shape is built up + using the :meth:`addcomponent` method. .. method:: addcomponent(poly, fill, outline=None) - :param poly: a polygon, i.e. a tuple of pairs of numbers - :param fill: a color the *poly* will be filled with - :param outline: a color for the poly's outline (if given) + :param poly: a tuple of pairs of numbers + :param fill: a color + :param outline: a color or ``None`` + + Add a component to a shape of type "compound". *poly* is a polygon, a + tuple of pairs of numbers. *fill* is the color the polygon is filled + with and *outline* is the color of its outline. If *outline* is not + given, *fill* is used for it as well. Example: .. doctest:: :skipif: _tkinter is None - >>> poly = ((0,0),(10,-5),(0,10),(-10,-5)) + >>> poly = ((0,0), (10,-5), (0,10), (-10,-5)) >>> s = Shape("compound") >>> s.addcomponent(poly, "red", "blue") >>> # ... add more components and then use register_shape() diff --git a/Lib/turtle.py b/Lib/turtle.py index 33bfcb4f98bad4b..a8cfedcaa0ac037 100644 --- a/Lib/turtle.py +++ b/Lib/turtle.py @@ -696,9 +696,9 @@ def _pointlist(self, item): """Return list of coordinate pairs of points of item. For example: - >>> getscreen()._pointlist(getturtle().turtle._item) - [(0.0, 9.9999999999999982), (0.0, -9.9999999999999982), - (9.9999999999999982, 0.0)] + >>> getscreen()._pointlist(getturtle().turtle._item) + [(0.0, 9.9999999999999982), (0.0, -9.9999999999999982), + (9.9999999999999982, 0.0)] """ cl = self.cv.coords(item) pl = [(cl[i], -cl[i+1]) for i in range(0, len(cl), 2)] @@ -746,52 +746,51 @@ def _window_size(self): return width, height def mainloop(self): - """Starts event loop - calling Tkinter's mainloop function. - - No argument. - - Must be the last statement in a turtle graphics program. - Must NOT be used if a script is run from within IDLE in -n mode - (No subprocess) - for interactive use of turtle graphics. - - Example (for a TurtleScreen instance named screen): - >>> screen.mainloop() + """Start the event loop by calling Tkinter's mainloop function. + Must be the last statement in a turtle graphics program. Must not + be used if a script is run from within IDLE in -n mode (no + subprocess). """ self.cv.tk.mainloop() def textinput(self, title, prompt): """Pop up a dialog window for input of a string. - Arguments: title is the title of the dialog window, - prompt is a text mostly describing what information to input. - - Return the string input + title is the title of the dialog window and prompt is a text + describing what information to input. Return the string entered. If the dialog is canceled, return None. - Example (for a TurtleScreen instance named screen): - >>> screen.textinput("NIM", "Name of first player:") + Arguments: + title -- a string + prompt -- a string + Example (for a TurtleScreen instance named screen): + >>> screen.textinput("NIM", "Name of first player:") """ return simpledialog.askstring(title, prompt, parent=self.cv) def numinput(self, title, prompt, default=None, minval=None, maxval=None): """Pop up a dialog window for input of a number. - Arguments: title is the title of the dialog window, - prompt is a text mostly describing what numerical information to input. - default: default value - minval: minimum value for input - maxval: maximum value for input + title is the title of the dialog window and prompt is a text + describing what numerical information to input. default is the + default value, minval and maxval are the minimum and maximum + values for input. If these are given, the number entered must be + between minval and maxval. If not, a hint is issued and the dialog + remains open for correction. Return the number entered. + If the dialog is canceled, return None. - The number input must be in the range minval .. maxval if these are - given. If not, a hint is issued and the dialog remains open for - correction. Return the number input. - If the dialog is canceled, return None. + Arguments: + title -- a string + prompt -- a string + default -- a number or None + minval -- a number or None + maxval -- a number or None Example (for a TurtleScreen instance named screen): - >>> screen.numinput("Poker", "Your stakes:", 1000, minval=10, maxval=10000) - + >>> screen.numinput("Poker", "Your stakes:", 1000, + ... minval=10, maxval=10000) """ return simpledialog.askfloat(title, prompt, initialvalue=default, minvalue=minval, maxvalue=maxval, @@ -803,7 +802,7 @@ def numinput(self, title, prompt, default=None, minval=None, maxval=None): ############################################################################## -class Terminator (Exception): +class Terminator(Exception): """Will be raised in TurtleScreen.update, if _RUNNING becomes False. This stops execution of a turtle graphics script. @@ -819,9 +818,11 @@ class TurtleGraphicsError(Exception): class Shape: """Data structure modeling shapes. - attribute _type is one of "polygon", "image", "compound" - attribute _data is - depending on _type a poygon-tuple, - an image or a list constructed using the addcomponent method. + type_ is one of the strings "polygon", "image" or "compound". What + data must be depends on type_: for "polygon" a tuple of pairs of + coordinates, for "image" an image (only used internally), and for + "compound" None, as a compound shape is built up using the + addcomponent method. """ def __init__(self, type_, data=None): self._type = type_ @@ -837,20 +838,22 @@ def __init__(self, type_, data=None): self._data = data def addcomponent(self, poly, fill, outline=None): - """Add component to a shape of type compound. + """Add a component to a shape of type "compound". - Arguments: poly is a polygon, i. e. a tuple of number pairs. - fill is the fillcolor of the component, - outline is the outline color of the component. + poly is a polygon, a tuple of pairs of numbers. fill is the color + the polygon is filled with and outline is the color of its + outline. If outline is not given, fill is used for it as well. - call (for a Shapeobject namend s): - -- s.addcomponent(((0,0), (10,10), (-10,10)), "red", "blue") + Arguments: + poly -- a tuple of pairs of numbers + fill -- a color + outline -- a color or None Example: - >>> poly = ((0,0),(10,-5),(0,10),(-10,-5)) - >>> s = Shape("compound") - >>> s.addcomponent(poly, "red", "blue") - >>> # .. add more components and then use register_shape() + >>> poly = ((0,0), (10,-5), (0,10), (-10,-5)) + >>> s = Shape("compound") + >>> s.addcomponent(poly, "red", "blue") + >>> # ... add more components and then use register_shape() """ if self._type != "compound": raise TurtleGraphicsError("Cannot add component to %s Shape" @@ -968,15 +971,16 @@ def __init__(self, cv, mode=_CFG["mode"], def clear(self): """Delete all drawings and all turtles from the TurtleScreen. - No argument. + Aliases: clear | clearscreen - Reset empty TurtleScreen to its initial state: white background, - no backgroundimage, no eventbindings and tracing on. + Reset the now empty TurtleScreen to its initial state: white + background, no background image, no event bindings and tracing on. + As a function, this method is only available under the name + clearscreen. The function clear is derived from the Turtle method + clear. Example (for a TurtleScreen instance named screen): - >>> screen.clear() - - Note: this method is not available as function. + >>> screen.clearscreen() """ self._delayvalue = _CFG["delay"] self._colormode = _CFG["colormode"] @@ -996,26 +1000,29 @@ def clear(self): Turtle._pen = None def mode(self, mode=None): - """Set turtle-mode ('standard', 'logo' or 'world') and perform reset. + """Set the turtle mode and perform a reset. - Optional argument: - mode -- one of the strings 'standard', 'logo' or 'world' + mode is one of the strings "standard", "logo" or "world". If mode + is not given, return the current mode. - Mode 'standard' is compatible with turtle.py. - Mode 'logo' is compatible with most Logo-Turtle-Graphics. - Mode 'world' uses userdefined 'worldcoordinates'. *Attention*: in - this mode angles appear distorted if x/y unit-ratio doesn't equal 1. - If mode is not given, return the current mode. + Mode "standard" is compatible with the old turtle module. Mode + "logo" is compatible with most Logo turtle graphics. Mode "world" + uses user-defined world coordinates, see setworldcoordinates(). In + this mode, angles appear distorted if the x and y units are not of + equal length. Mode Initial turtle heading positive angles ------------|-------------------------|------------------- - 'standard' to the right (east) counterclockwise - 'logo' upward (north) clockwise + "standard" to the right (east) counterclockwise + "logo" upward (north) clockwise + + Argument: + mode -- a string or None - Examples: - >>> mode('logo') # resets turtle heading to north - >>> mode() - 'logo' + Example (for a TurtleScreen instance named screen): + >>> screen.mode("logo") # resets turtle heading to north + >>> screen.mode() + 'logo' """ if mode is None: return self._mode @@ -1030,26 +1037,29 @@ def mode(self, mode=None): self.reset() def setworldcoordinates(self, llx, lly, urx, ury): - """Set up a user defined coordinate-system. + """Set up a user-defined coordinate system. - Arguments: - llx -- a number, x-coordinate of lower left corner of canvas - lly -- a number, y-coordinate of lower left corner of canvas - urx -- a number, x-coordinate of upper right corner of canvas - ury -- a number, y-coordinate of upper right corner of canvas - - Set up user coodinat-system and switch to mode 'world' if necessary. - This performs a screen.reset. If mode 'world' is already active, - all drawings are redrawn according to the new coordinates. + llx and lly are the x and y coordinates of the lower left corner of + the canvas. urx and ury are the x and y coordinates of the upper + right corner. Switch to mode "world" if necessary, which performs a + reset. If mode "world" is already active, all drawings are redrawn + according to the new coordinates. In user-defined coordinate + systems, angles may appear distorted, see mode(). - But ATTENTION: in user-defined coordinatesystems angles may appear - distorted. (see Screen.mode()) + Arguments: + llx -- a number + lly -- a number + urx -- a number + ury -- a number Example (for a TurtleScreen instance named screen): - >>> screen.setworldcoordinates(-10,-0.5,50,1.5) - >>> for _ in range(36): - ... left(10) - ... forward(0.5) + >>> screen.reset() + >>> screen.setworldcoordinates(-50,-7.5,50,7.5) + >>> for _ in range(72): + ... left(10) + ... + >>> for _ in range(8): + ... left(45); fd(2) # a regular octagon """ if self.mode() != "world": self.mode("world") @@ -1069,31 +1079,35 @@ def setworldcoordinates(self, llx, lly, urx, ury): self.update() def register_shape(self, name, shape=None): - """Adds a turtle shape to TurtleScreen's shapelist. + """Add a turtle shape to the TurtleScreen's shape list. + + Aliases: register_shape | addshape + + It can be called in four different ways: + + (1) name is the name of an image file (PNG, GIF, PGM, and PPM) and + shape is None. Install the corresponding image shape. + (2) name is an arbitrary string and shape is the name of an image + file (PNG, GIF, PGM, and PPM). Install the corresponding image + shape. + (3) name is an arbitrary string and shape is a tuple of pairs of + coordinates. Install the corresponding polygon shape. + (4) name is an arbitrary string and shape is a (compound) Shape + object. Install the corresponding compound shape. + + Image shapes do not rotate when turning the turtle, so they do not + display the heading of the turtle. To use a registered shape, call + shape() with its name. Arguments: - (1) name is the name of an image file (PNG, GIF, PGM, and PPM) and shape is None. - Installs the corresponding image shape. - !! Image-shapes DO NOT rotate when turning the turtle, - !! so they do not display the heading of the turtle! - (2) name is an arbitrary string and shape is the name of an image file (PNG, GIF, PGM, and PPM). - Installs the corresponding image shape. - !! Image-shapes DO NOT rotate when turning the turtle, - !! so they do not display the heading of the turtle! - (3) name is an arbitrary string and shape is a tuple - of pairs of coordinates. Installs the corresponding - polygon shape - (4) name is an arbitrary string and shape is a - (compound) Shape object. Installs the corresponding - compound shape. - To use a shape, you have to issue the command shape(shapename). - - call: register_shape("turtle.gif") - --or: register_shape("tri", ((0,0), (10,10), (-10,10))) + name -- a string + shape -- a string, a tuple of pairs of numbers, a Shape object + or None Example (for a TurtleScreen instance named screen): - >>> screen.register_shape("triangle", ((5,-3),(0,5),(-5,-3))) - + >>> screen.register_shape("turtle.gif") + >>> screen.register_shape("turtle", "turtle.gif") + >>> screen.register_shape("triangle", ((5,-3), (0,5), (-5,-3))) """ if shape is None: shape = Shape("image", self._image(name)) @@ -1105,14 +1119,12 @@ def register_shape(self, name, shape=None): self._shapes[name] = shape def _colorstr(self, color): - """Return color string corresponding to args. + """Return the color string corresponding to color. - Argument may be a string or a tuple of three - numbers corresponding to actual colormode, - i.e. in the range 0<=n<=colormode. + color may be a string or a tuple of three numbers, each between 0 and + the current colormode. - If the argument doesn't represent a color, - an error is raised. + If color doesn't represent a color, an error is raised. """ if len(color) == 1: color = color[0] @@ -1145,16 +1157,24 @@ def _color(self, cstr): def colormode(self, cmode=None): """Return the colormode or set it to 1.0 or 255. - Optional argument: - cmode -- one of the values 1.0 or 255 + After setting it, the r, g and b values of color triples have to + be between 0 and cmode. - r, g, b values of colortriples have to be in range 0..cmode. + Argument: + cmode -- a number or None Example (for a TurtleScreen instance named screen): - >>> screen.colormode() - 1.0 - >>> screen.colormode(255) - >>> pencolor(240,160,80) + >>> screen.colormode(1) + >>> turtle.pencolor(240, 160, 80) + Traceback (most recent call last): + ... + TurtleGraphicsError: bad color sequence: (240, 160, 80) + >>> screen.colormode() + 1.0 + >>> screen.colormode(255) + >>> screen.colormode() + 255 + >>> turtle.pencolor(240,160,80) """ if cmode is None: return self._colormode @@ -1164,12 +1184,13 @@ def colormode(self, cmode=None): self._colormode = int(cmode) def reset(self): - """Reset all Turtles on the Screen to their initial state. + """Reset all turtles on the screen to their initial state. - No argument. + Aliases: reset | resetscreen - Example (for a TurtleScreen instance named screen): - >>> screen.reset() + As a function, this method is only available under the name + resetscreen. The function reset is derived from the Turtle method + reset(). """ for turtle in self._turtles: turtle._setmode(self._mode) @@ -1179,40 +1200,40 @@ def turtles(self): """Return the list of turtles on the screen. Example (for a TurtleScreen instance named screen): - >>> screen.turtles() - [<turtle.Turtle object at 0x00E11FB0>] + >>> for turtle in screen.turtles(): + ... turtle.color("red") """ return self._turtles def bgcolor(self, *args): - """Set or return backgroundcolor of the TurtleScreen. + """Return or set the background color of the TurtleScreen. Four input formats are allowed: - bgcolor() - Return the current background color as color specification + Return the current background color as a color specification string or as a tuple (see example). May be used as input - to another color/pencolor/fillcolor/bgcolor call. + to another color(), pencolor(), fillcolor() or bgcolor() call. - bgcolor(colorstring) Set the background color to colorstring, which is a Tk color specification string, such as "red", "yellow", or "#33cc8c". - bgcolor((r, g, b)) Set the background color 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 + 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()). - bgcolor(r, g, b) Set the background color to the RGB color represented by - r, g, and b. Each of r, g, and b must be in the range - 0..colormode. + r, g, and b. Each of r, g, and b must be between 0 and + colormode. Example (for a TurtleScreen instance named screen): - >>> screen.bgcolor("orange") - >>> screen.bgcolor() - 'orange' - >>> colormode(255) - >>> screen.bgcolor('#800080') - >>> screen.bgcolor() - (128.0, 0.0, 128.0) + >>> screen.bgcolor("orange") + >>> screen.bgcolor() + 'orange' + >>> screen.colormode(255) + >>> screen.bgcolor("#800080") + >>> screen.bgcolor() + (128.0, 0.0, 128.0) """ if args: color = self._colorstr(args) @@ -1224,23 +1245,26 @@ def bgcolor(self, *args): return color def tracer(self, n=None, delay=None): - """Turns turtle animation on/off and set delay for update drawings. + """Turn turtle animation on or off and set the drawing delay. - Optional arguments: - n -- nonnegative integer - delay -- nonnegative integer + If n is given, only every n-th regular screen update is performed, + which can be used to speed up the drawing of complex graphics. If + n is 0, animation is turned off and the screen is only updated by + calling update(). If delay is given, it sets the drawing delay, see + delay(). When called without arguments, return the current value + of n. - 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()) + Arguments: + n -- a nonnegative integer or None + delay -- a nonnegative integer or None Example (for a TurtleScreen instance named screen): - >>> screen.tracer(8, 25) - >>> dist = 2 - >>> for i in range(200): - ... fd(dist) - ... rt(90) - ... dist += 2 + >>> screen.tracer(8, 25) + >>> dist = 2 + >>> for i in range(200): + ... fd(dist) + ... rt(90) + ... dist += 2 """ if n is None: return self._tracing @@ -1254,13 +1278,19 @@ def tracer(self, n=None, delay=None): def delay(self, delay=None): """Return or set the drawing delay in milliseconds. - Optional argument: - delay -- positive integer + This is approximately the time interval between two consecutive + canvas updates. The longer the drawing delay, the slower the + animation. + + Argument: + delay -- a nonnegative integer or None Example (for a TurtleScreen instance named screen): - >>> screen.delay(15) - >>> screen.delay() - 15 + >>> screen.delay() + 10 + >>> screen.delay(5) + >>> screen.delay() + 5 """ if delay is None: return self._delayvalue @@ -1268,16 +1298,17 @@ def delay(self, delay=None): @contextmanager def no_animation(self): - """Temporarily turn off auto-updating the screen. + """Temporarily turn off turtle animation. - This is useful for drawing complex shapes where even the fastest setting - is too slow. Once this context manager is exited, the drawing will - be displayed. + The code inside the with block is not animated. Once the block is + exited, the drawing appears. This is useful for drawing complex + shapes where even the fastest speed setting is too slow. - Example (for a TurtleScreen instance named screen - and a Turtle instance named turtle): - >>> with screen.no_animation(): - ... turtle.circle(50) + Example (for a TurtleScreen instance named screen): + >>> with screen.no_animation(): + ... for dist in range(2, 400, 2): + ... fd(dist) + ... rt(90) """ tracer = self.tracer() try: @@ -1287,7 +1318,7 @@ def no_animation(self): self.tracer(tracer) def _incrementudc(self): - """Increment update counter.""" + """Increment the update counter.""" if not TurtleScreen._RUNNING: TurtleScreen._RUNNING = True raise Terminator @@ -1309,8 +1340,8 @@ def window_width(self): """Return the width of the turtle window. Example (for a TurtleScreen instance named screen): - >>> screen.window_width() - 640 + >>> screen.window_width() + 640 """ return self._window_size()[0] @@ -1318,48 +1349,53 @@ def window_height(self): """Return the height of the turtle window. Example (for a TurtleScreen instance named screen): - >>> screen.window_height() - 480 + >>> screen.window_height() + 480 """ return self._window_size()[1] def getcanvas(self): """Return the Canvas of this TurtleScreen. - No argument. - Example (for a Screen instance named screen): - >>> cv = screen.getcanvas() - >>> cv - <turtle.ScrolledCanvas instance at 0x010742D8> + >>> cv = screen.getcanvas() + >>> cv + <turtle.ScrolledCanvas object ...> """ return self.cv def getshapes(self): """Return a list of names of all currently available turtle shapes. - No argument. - Example (for a TurtleScreen instance named screen): - >>> screen.getshapes() - ['arrow', 'blank', 'circle', ... , 'turtle'] + >>> screen.getshapes() + ['arrow', 'blank', 'circle', ..., 'turtle'] """ return sorted(self._shapes.keys()) def onclick(self, fun, btn=1, add=None): - """Bind fun to mouse-click event on canvas. + """Bind fun to mouse-click events on this screen. - Arguments: - fun -- a function with two arguments, the coordinates of the - clicked point on the canvas. - btn -- the number of the mouse-button, defaults to 1 + Aliases: onclick | onscreenclick + + fun is called with the coordinates of the clicked point on the + canvas. If fun is None, existing bindings are removed. btn is the + number of the mouse button and defaults to 1, the left mouse + button. If add is True, a new binding is added, otherwise it + replaces a former binding. As a function, this method is only + available under the name onscreenclick. The function onclick is + derived from the Turtle method onclick. - Example (for a TurtleScreen instance named screen) + Arguments: + fun -- a function with two arguments or None + btn -- an integer + add -- a boolean or None - >>> screen.onclick(goto) - >>> # Subsequently clicking into the TurtleScreen will - >>> # make the turtle move to the clicked point. - >>> screen.onclick(None) + Example (for a TurtleScreen instance named screen): + >>> screen.onscreenclick(turtle.goto) + >>> # Subsequently clicking into the TurtleScreen will + >>> # make the turtle move to the clicked point. + >>> screen.onscreenclick(None) # remove event binding again """ self._onscreenclick(fun, btn, add) @@ -1565,9 +1601,9 @@ def __init__(self, mode=DEFAULT_MODE): TNavigator.reset(self) def reset(self): - """Reset turtle to its initial values. + """Reset the turtle to its initial values. - Will be overwritten by the parent class. + Will be overwritten by the child class. """ self._position = Vec2D(0.0, 0.0) self._orient = TNavigator.START_ORIENTATION[self._mode] @@ -2138,11 +2174,6 @@ def penup(self): """Pull the pen up -- no drawing when moving. Aliases: penup | pu | up - - No argument - - Example (for a Turtle instance named turtle): - >>> turtle.penup() """ if not self._drawing: return @@ -2152,11 +2183,6 @@ def pendown(self): """Pull the pen down -- drawing when moving. Aliases: pendown | pd | down - - No argument. - - Example (for a Turtle instance named turtle): - >>> turtle.pendown() """ if self._drawing: return @@ -2165,8 +2191,6 @@ def pendown(self): def isdown(self): """Return True if pen is down, False if it's up. - No argument. - Example (for a Turtle instance named turtle): >>> turtle.penup() >>> turtle.isdown() @@ -2343,6 +2367,7 @@ def fillcolor(self, *args): def teleport(self, x=None, y=None, *, fill_gap: bool = False) -> None: """To be overwritten by child class RawTurtle. + Includes no TNavigator references. """ pendown = self.isdown() @@ -2351,43 +2376,31 @@ def teleport(self, x=None, y=None, *, fill_gap: bool = False) -> None: self.pen(pendown=pendown) def showturtle(self): - """Makes the turtle visible. + """Make the turtle visible. Aliases: showturtle | st - - No argument. - - Example (for a Turtle instance named turtle): - >>> turtle.hideturtle() - >>> turtle.showturtle() """ self.pen(shown=True) def hideturtle(self): - """Makes the turtle invisible. + """Make the turtle invisible. Aliases: hideturtle | ht - No argument. - - It's a good idea to do this while you're in the - middle of a complicated drawing, because hiding - the turtle speeds up the drawing observably. - - Example (for a Turtle instance named turtle): - >>> turtle.hideturtle() + If the pen is down, movement still draws. """ self.pen(shown=False) def isvisible(self): - """Return True if the Turtle is shown, False if it's hidden. - - No argument. + """Return True if the turtle is shown, False if it's hidden. Example (for a Turtle instance named turtle): - >>> turtle.hideturtle() - >>> print(turtle.isvisible()) - False + >>> turtle.hideturtle() + >>> turtle.isvisible() + False + >>> turtle.showturtle() + >>> turtle.isvisible() + True """ return self._shown @@ -2516,16 +2529,18 @@ def pen(self, pen=None, **pendict): -scx*sa, scy*(ca - shf*sa)) self._update() -## three dummy methods to be implemented by child class: + # Three dummy methods to be implemented by the child class: def _newLine(self, usePos = True): - """dummy method - to be overwritten by child class""" + """Dummy method - to be overwritten by the child class.""" def _update(self, count=True, forced=False): - """dummy method - to be overwritten by child class""" + """Dummy method - to be overwritten by the child class.""" def _color(self, args): - """dummy method - to be overwritten by child class""" + """Dummy method - to be overwritten by the child class.""" def _colorstr(self, args): - """dummy method - to be overwritten by child class""" + """Dummy method - to be overwritten by the child class.""" + + # Aliases for the commonly used commands: width = pensize up = penup @@ -2537,8 +2552,7 @@ def _colorstr(self, args): class _TurtleImage: - """Helper class: Datatype to store Turtle attributes - """ + """Helper class holding the canvas items that display a turtle's shape.""" def __init__(self, screen, shapeIndex): self.screen = screen @@ -2568,9 +2582,10 @@ def _setshape(self, shapeIndex): class RawTurtle(TPen, TNavigator): - """Animation part of the RawTurtle. - Puts RawTurtle upon a TurtleScreen and provides tools for - its animation. + """A turtle that draws on the given canvas or TurtleScreen. + + Combines the navigation part (TNavigator) and the drawing part (TPen) + and adds the animation of the turtle on the screen. """ screens = [] @@ -2615,23 +2630,22 @@ def __init__(self, canvas=None, self._update() def reset(self): - """Delete the turtle's drawings and restore its default values. + """Delete the turtle's drawings and re-center the turtle. - No argument. - - Delete the turtle's drawings from the screen, re-center the turtle - and set variables to the default values. + The turtle's settings are restored to their default values. Example (for a Turtle instance named turtle): - >>> turtle.position() - (0.00,-22.00) - >>> turtle.heading() - 100.0 - >>> turtle.reset() - >>> turtle.position() - (0.00,0.00) - >>> turtle.heading() - 0.0 + >>> turtle.goto(0,-22) + >>> turtle.left(100) + >>> turtle.position() + (0.00,-22.00) + >>> turtle.heading() + 100.0 + >>> turtle.reset() + >>> turtle.position() + (0.00,0.00) + >>> turtle.heading() + 0.0 """ TNavigator.reset(self) TPen._reset(self) @@ -2659,20 +2673,18 @@ def setundobuffer(self, size): self.undobuffer = Tbuffer(size) def undobufferentries(self): - """Return count of entries in the undobuffer. - - No argument. + """Return the number of entries in the undobuffer. Example (for a Turtle instance named turtle): - >>> while undobufferentries(): - ... undo() + >>> while undobufferentries(): + ... undo() """ if self.undobuffer is None: return 0 return self.undobuffer.nr_of_items() def _clear(self): - """Delete all of pen's drawings""" + """Delete all of the pen's drawings.""" self._fillitem = self._fillpath = None for item in self.items: self.screen._delete(item) @@ -2686,16 +2698,13 @@ def _clear(self): def clear(self): - """Delete the turtle's drawings from the screen. Do not move turtle. + """Delete the turtle's drawings from the screen. - No arguments. + The state and position of the turtle as well as the drawings of + other turtles are not affected. - Delete the turtle's drawings from the screen. Do not move turtle. - State and position of the turtle as well as drawings of other - turtles are not affected. - - Examples (for a Turtle instance named turtle): - >>> turtle.clear() + Example (for a Turtle instance named turtle): + >>> turtle.clear() """ self._clear() self._update() @@ -2709,8 +2718,7 @@ def _update_data(self): self._pencolor, self._pensize) def _update(self): - """Perform a Turtle-data update. - """ + """Perform a Turtle-data update.""" screen = self.screen if screen._tracing == 0: return @@ -2754,8 +2762,7 @@ def _colorstr(self, args): return self.screen._colorstr(args) def _cc(self, args): - """Convert colortriples to hexstrings. - """ + """Convert colortriples to hexstrings.""" if isinstance(args, str): return args try: @@ -3173,8 +3180,7 @@ def stamp(self): return stitem def _clearstamp(self, stampid): - """does the work for clearstamp() and clearstamps() - """ + """Does the work for clearstamp() and clearstamps().""" if stampid in self.stampItems: if isinstance(stampid, tuple): for subitem in stampid: @@ -3284,8 +3290,7 @@ def _goto(self, end): self._update() #count=True) def _undogoto(self, entry): - """Reverse a _goto. Used for undo() - """ + """Reverse a _goto(). Used for undo().""" old, new, go_modes, coodata = entry drawing, pc, ps, filling = go_modes cLI, cL, pl, items = coodata @@ -3349,8 +3354,7 @@ def _undogoto(self, entry): self._update() #count=True) def _rotate(self, angle): - """Turns pen clockwise by angle. - """ + """Turns pen clockwise by angle.""" if self.undobuffer: self.undobuffer.push(("rot", angle, self._degreesPerAU)) angle *= self._degreesPerAU @@ -3554,13 +3558,7 @@ def poly(self): def begin_poly(self): """Start recording the vertices of a polygon. - No argument. - - Start recording the vertices of a polygon. Current turtle position - is first point of polygon. - - Example (for a Turtle instance named turtle): - >>> turtle.begin_poly() + The current turtle position is the first vertex of the polygon. """ self._poly = [self._position] self._creatingPoly = True @@ -3568,58 +3566,53 @@ def begin_poly(self): def end_poly(self): """Stop recording the vertices of a polygon. - No argument. - - Stop recording the vertices of a polygon. Current turtle position is - last point of polygon. This will be connected with the first point. - - Example (for a Turtle instance named turtle): - >>> turtle.end_poly() + The current turtle position is the last vertex of the polygon. + This will be connected with the first vertex. """ self._creatingPoly = False def get_poly(self): """Return the last recorded polygon. - No argument. - Example (for a Turtle instance named turtle): - >>> p = turtle.get_poly() - >>> turtle.register_shape("myFavouriteShape", p) + >>> turtle.home() + >>> turtle.begin_poly() + >>> turtle.fd(100) + >>> turtle.left(20) + >>> turtle.fd(30) + >>> turtle.left(60) + >>> turtle.fd(50) + >>> turtle.end_poly() + >>> p = turtle.get_poly() + >>> register_shape("myFavouriteShape", p) """ - ## check if there is any poly? + # Check if there are any poly? if self._poly is not None: return tuple(self._poly) def getscreen(self): """Return the TurtleScreen object the turtle is drawing on. - No argument. - So TurtleScreen-methods can be called for that object. Example (for a Turtle instance named turtle): - >>> ts = turtle.getscreen() - >>> ts - <turtle.TurtleScreen object at 0x0106B770> - >>> ts.bgcolor("pink") + >>> ts = turtle.getscreen() + >>> ts + <turtle.TurtleScreen object at ...> + >>> ts.bgcolor("pink") """ return self.screen def getturtle(self): """Return the Turtleobject itself. - No argument. - Only reasonable use: as a function to return the 'anonymous turtle': Example: - >>> pet = getturtle() - >>> pet.fd(50) - >>> pet - <turtle.Turtle object at 0x0187D810> - >>> turtles() - [<turtle.Turtle object at 0x0187D810>] + >>> pet = getturtle() + >>> pet.fd(50) + >>> pet + <turtle.Turtle object at ...> """ return self @@ -3631,27 +3624,29 @@ def getturtle(self): ################################################################ def _delay(self, delay=None): - """Set delay value which determines speed of turtle animation. - """ + """Set the delay which determines the speed of turtle animation.""" return self.screen.delay(delay) def onclick(self, fun, btn=1, add=None): - """Bind fun to mouse-click event on this turtle on canvas. + """Bind fun to mouse-click events on this turtle. - Arguments: - fun -- a function with two arguments, to which will be assigned - the coordinates of the clicked point on the canvas. - btn -- number of the mouse-button defaults to 1 (left mouse button). - add -- True or False. If True, new binding will be added, otherwise - it will replace a former binding. + fun is called with the coordinates of the clicked point on the + canvas. If fun is None, existing bindings are removed. btn is the + number of the mouse button and defaults to 1, the left mouse + button. If add is True, a new binding is added, otherwise it + replaces a former binding. - Example for the anonymous turtle, i. e. the procedural way: + Arguments: + fun -- a function with two arguments or None + btn -- an integer + add -- a boolean or None - >>> def turn(x, y): - ... left(360) - ... - >>> onclick(turn) # Now clicking into the turtle will turn it. - >>> onclick(None) # event-binding will be removed + Example for the anonymous turtle, that is, the procedural way: + >>> def turn(x, y): + ... left(180) + ... + >>> onclick(turn) # Now clicking into the turtle will turn it. + >>> onclick(None) # event-binding will be removed """ self.screen._onclick(self.turtle._item, fun, btn, add) self._update() @@ -3703,8 +3698,7 @@ def ondrag(self, fun, btn=1, add=None): def _undo(self, action, data): - """Does the main part of the work for undo() - """ + """Does the main part of the work for undo().""" if self.undobuffer is None: return if action == "rot": @@ -3773,9 +3767,10 @@ def undo(self): ### Screen - Singleton ######################## def Screen(): - """Return the singleton screen object. - If none exists at the moment, create a new one and return it, - else return the existing one.""" + """Return the single screen object. + + If it does not exist yet, create it. Otherwise return the existing one. + """ if Turtle._screen is None: Turtle._screen = _Screen() return Turtle._screen @@ -3844,17 +3839,17 @@ def setup(self, width=_CFG["width"], height=_CFG["height"], self.update() def title(self, titlestring): - """Set title of turtle-window + """Set the title of the turtle window to titlestring. - Argument: - titlestring -- a string, to appear in the titlebar of the - turtle graphics window. + The title is shown in the title bar of the turtle graphics window. + This is a method of the Screen class. It is not available for + TurtleScreen objects. - This is a method of Screen-class. Not available for TurtleScreen- - objects. + Argument: + titlestring -- a string Example (for a Screen instance named screen): - >>> screen.title("Welcome to the turtle-zoo!") + >>> screen.title("Welcome to the turtle zoo!") """ if _Screen._root is not None: _Screen._root.title(titlestring) @@ -3871,11 +3866,7 @@ def _destroy(self): root.destroy() def bye(self): - """Shut the turtlegraphics window. - - Example (for a TurtleScreen instance named screen): - >>> screen.bye() - """ + """Close the turtle graphics window.""" self._destroy() def exitonclick(self): @@ -4030,8 +4021,7 @@ def getmethparlist(ob): return str(func_sig), call_text def _turtle_docrevise(docstr): - """To reduce docstrings from RawTurtle class for functions - """ + """To reduce docstrings from the RawTurtle class for functions.""" import re if docstr is None: return None @@ -4042,8 +4032,7 @@ def _turtle_docrevise(docstr): return newdocstr def _screen_docrevise(docstr): - """To reduce docstrings from TurtleScreen class for functions - """ + """To reduce docstrings from the TurtleScreen class for functions.""" import re if docstr is None: return None _______________________________________________ Python-checkins mailing list -- [email protected] To unsubscribe send an email to [email protected] https://mail.python.org/mailman3//lists/python-checkins.python.org Member address: [email protected]
