diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index fea6b57edf0f1f..09dc8713da1254 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -524,9 +524,17 @@ Turtle motion :param angle: a number (integer or float) - Turn turtle right by *angle* units. (Units are by default degrees, but - can be set via the :func:`degrees` and :func:`radians` functions.) Angle - orientation depends on the turtle mode, see :func:`mode`. + Turn turtle right by *angle* units. + + The unit of measurement is controlled by :func:`degrees` and + :func:`radians`: + + * By default, 360.0 units form a full circle (degrees). + * After calling :func:`radians`, ``2*math.pi`` units form a full circle. + * Custom values can be set with :func:`degrees`. + + Orientation of the turn depends in the current turtle mode, + see :func:`mode`. .. doctest:: :skipif: _tkinter is None @@ -549,9 +557,17 @@ Turtle motion :param angle: a number (integer or float) - Turn turtle left by *angle* units. (Units are by default degrees, but - can be set via the :func:`degrees` and :func:`radians` functions.) Angle - orientation depends on the turtle mode, see :func:`mode`. + Turn turtle left by *angle* units. + + The unit of measurement is controlled by :func:`degrees` and + :func:`radians`: + + * By default, 360.0 units form a full circle (degrees). + * After calling :func:`radians`, ``2*math.pi`` units form a full circle. + * Custom values can be set with :func:`degrees`. + + Orientation of the turn depends in the current turtle mode, + see :func:`mode`. .. doctest:: :skipif: _tkinter is None @@ -1008,10 +1024,16 @@ Settings for measurement .. function:: degrees(fullcircle=360.0) - :param fullcircle: a number + :param fullcircle: a number representing units for a full circle + + Set angle measurement units so that a full circle is *fullcircle* + units. The default value is ``360.0`` (i.e. conventional degrees). - Set angle measurement units, i.e. set number of "degrees" for a full circle. - Default value is 360 degrees. + .. seealso:: + :func:`radians` + :func:`mode` + :func:`left` + :func:`right` .. doctest:: :skipif: _tkinter is None @@ -1030,11 +1052,29 @@ Settings for measurement >>> turtle.heading() 90.0 + >>> # Change angle measurement unit to radians (where a full circle + >>> # equals 2π radians, so 90 degrees becomes π/2 radians) + >>> import math + >>> turtle.degrees(2*math.pi) + >>> turtle.heading() + 1.5707963267948966 + >>> turtle.degrees(360) + >>> turtle.heading() + 90.0 + .. function:: radians() - Set the angle measurement units to radians. Equivalent to - ``degrees(2*math.pi)``. + Set the angle measurement unit to radians. + + Equivalent to:: + + degrees(2*math.pi) + + After this call, one full circle correspond to + ``2*math.pi`` units. + + .. seealso:: :func:`degrees`, :func:`left`, :func:`right` .. doctest:: :skipif: _tkinter is None @@ -1356,8 +1396,26 @@ 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 from the screen. Move the turtle + to position ``(0, 0)``, set its heading 0 and restore the + following state variables to their initial values: + + * position: ``(0, 0)`` + * heading: ``0`` (east if standard or world mode, north if logo mode) + * pen state: down (drawing) + * pensize: ``1`` + * pencolor: black + * fillcolor: white + * speed: ``3`` + * turtle visibility: shown + * shape size: ``(1.0, 1.0)`` (no stretch) + * shape shear: ``0.0`` (no shear) + * shape tilt: ``0.0`` (no tilt) + + .. note:: + The angle unit is **not reset** to degrees. If + :func:`radians` was used before :func:`reset`, + the unit remains radians. .. doctest:: :skipif: _tkinter is None @@ -2588,7 +2646,7 @@ facilities: "orange" >>> screen.bgcolor(0.5,0,0.5) >>> screen.bgcolor() - "#800080" + "rgba(128, 0, 128, 1)" >>> help(Turtle.penup) Help on method penup in module turtle: diff --git a/Lib/turtle.py b/Lib/turtle.py index e88981d298ad52..d25b1d6d8b9d41 100644 --- a/Lib/turtle.py +++ b/Lib/turtle.py @@ -1580,7 +1580,7 @@ def reset(self): Will be overwritten by parent class """ self._position = Vec2D(0.0, 0.0) - self._orient = TNavigator.START_ORIENTATION[self._mode] + self._orient = TNavigator.START_ORIENTATION[self._mode] def _setmode(self, mode=None): """Set turtle-mode to 'standard', 'world' or 'logo'. @@ -1612,9 +1612,8 @@ def degrees(self, fullcircle=360.0): Optional argument: fullcircle - a number - Set angle measurement units, i. e. set number - of 'degrees' for a full circle. Default value is - 360 degrees. + Set angle measurement units so that a full circle is *fullcircle* + units. The default value is `360.0` (i.e. conventional degrees). Example (for a Turtle instance named turtle): >>> turtle.left(90) @@ -1627,12 +1626,20 @@ def degrees(self, fullcircle=360.0): >>> turtle.heading() 100 + Change angle measurement unit to radians (where a full circle + equals 2π radians, so 90 degrees becomes π/2 radians) + >>> turtle.degrees(2*math.pi) + >>> turtle.heading() + 1.5707963267948966 + """ self._setDegreesPerAU(fullcircle) def radians(self): """ Set the angle measurement units to radians. + Equivalent to calling `degrees(2*math.pi)` + No arguments. Example (for a Turtle instance named turtle): @@ -1716,9 +1723,17 @@ def right(self, angle): Argument: angle -- a number (integer or float) - Turn turtle right by angle units. (Units are by default degrees, - but can be set via the degrees() and radians() functions.) - Angle orientation depends on mode. (See this.) + Turn turtle right by *angle* units. + + The unit of measurement is controlled by `degrees()` and + `radians()`: + + * By default, 360.0 units form a full circle (degrees). + * After calling `radians()`, ``2*math.pi`` units form a full circle. + * Custom values can be set with `degrees(fullcircle)`. + + Orientation of the turn depends in the current turtle mode, + see function `mode()`. Example (for a Turtle instance named turtle): >>> turtle.heading() @@ -1737,9 +1752,17 @@ def left(self, angle): Argument: angle -- a number (integer or float) - Turn turtle left by angle units. (Units are by default degrees, - but can be set via the degrees() and radians() functions.) - Angle orientation depends on mode. (See this.) + Turn turtle left by *angle* units. + + The unit of measurement is controlled by `degrees()` and + `radians()`: + + * By default, 360.0 units form a full circle (degrees). + * After calling `radians()`, ``2*math.pi`` units form a full circle. + * Custom values can be set with `degrees(fullcircle)`. + + Orientation of the turn depends in the current turtle mode, + see function `mode()`. Example (for a Turtle instance named turtle): >>> turtle.heading() @@ -2622,8 +2645,26 @@ def reset(self): No argument. - Delete the turtle's drawings from the screen, re-center the turtle - and set variables to the default values. + Delete the turtle's drawings from the screen. Move the turtle + to position `(0, 0)`, set its heading to 0 and restore + the following state variables to their initial values: + + - position: `(0, 0)` + - heading: `0` (east if standard or world mode, north if logo mode) + - pen state: down (drawing) + - pensize: `1` + - pencolor: black + - fillcolor: white + - speed: `3` + - turtle visibility: shown + - shape size: `(1.0, 1.0)` (no stretch) + - shape shear: `0.0` (no shear) + - shape tilt: `0.0` (no tilt) + + Note: + The angle unit is **not reset** to degrees. If + `radians()` was used before `reset()`, + the unit remains radians. Example (for a Turtle instance named turtle): >>> turtle.position()