From dae41e052d9ae51eaf76fc569ea3d12e7782fe94 Mon Sep 17 00:00:00 2001 From: marat Date: Sat, 13 Sep 2025 23:45:03 +0300 Subject: [PATCH 1/4] gh-138845: Correct turtle module documentation misconceptions --- Doc/library/turtle.rst | 81 +++++++++++++++++++++++++++++++++++------- Lib/turtle.py | 66 +++++++++++++++++++++++++++------- 2 files changed, 122 insertions(+), 25 deletions(-) diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index fea6b57edf0f1f..cf93b1306586ff 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(fullcircle)`. + + 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(fullcircle)`. + + 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, 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). + + .. seealso:: + :func:`radians` + :func:`mode` + :func:`left` + :func:`right` .. doctest:: :skipif: _tkinter is None @@ -1030,11 +1052,25 @@ 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) + >>> turtle.degrees(2*math.pi) + >>> turtle.heading() + 1.5707963267948966 + .. 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 +1392,27 @@ 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 to the default + (facing east in standard mode) and restore the following state + variables to their initial values: + + * position: ``(0, 0)`` + * heading: ``0`` (east) + * 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 diff --git a/Lib/turtle.py b/Lib/turtle.py index e88981d298ad52..163fdcc93a6285 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,27 @@ 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 the default + (facing east in standard mode) and restore the following state + variables to their initial values: + + - position: `(0, 0)` + - heading: `0` (east) + - 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() From 721c45487f50fea6905f89908b86f7767d05ef56 Mon Sep 17 00:00:00 2001 From: marat Date: Sun, 14 Sep 2025 08:45:08 +0300 Subject: [PATCH 2/4] Fix function names and doctests --- Doc/library/turtle.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index cf93b1306586ff..652910a1de0883 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -531,7 +531,7 @@ Turtle motion * 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(fullcircle)`. + * Custom values can be set with :func:`degrees`. Orientation of the turn depends in the current turtle mode, see :func:`mode`. @@ -564,7 +564,7 @@ Turtle motion * 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(fullcircle)`. + * Custom values can be set with :func:`degrees`. Orientation of the turn depends in the current turtle mode, see :func:`mode`. @@ -1054,6 +1054,7 @@ Settings for measurement >>> # 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 @@ -1064,7 +1065,7 @@ Settings for measurement Set the angle measurement unit to radians. Equivalent to:: - + degrees(2*math.pi) After this call, one full circle correspond to From 31873d3c58d3710439e8df4e96695f43fd77db6b Mon Sep 17 00:00:00 2001 From: marat Date: Sun, 14 Sep 2025 09:07:59 +0300 Subject: [PATCH 3/4] Fix doctests with radians corresponding --- Doc/library/turtle.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index 652910a1de0883..0b38e3f0467c65 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -1058,6 +1058,9 @@ Settings for measurement >>> turtle.degrees(2*math.pi) >>> turtle.heading() 1.5707963267948966 + >>> turtle.degrees(360) + >>> turtle.heading() + 90.0 .. function:: radians() From 0849c99b2c567c4139660de0105a74ba8d7eae7f Mon Sep 17 00:00:00 2001 From: marat Date: Sun, 14 Sep 2025 09:53:48 +0300 Subject: [PATCH 4/4] Add news entry --- .../2025-09-14-09-48-44.gh-issue-138845.38PSxU.rst | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2025-09-14-09-48-44.gh-issue-138845.38PSxU.rst diff --git a/Misc/NEWS.d/next/Documentation/2025-09-14-09-48-44.gh-issue-138845.38PSxU.rst b/Misc/NEWS.d/next/Documentation/2025-09-14-09-48-44.gh-issue-138845.38PSxU.rst new file mode 100644 index 00000000000000..47ebaa1f35f7c2 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2025-09-14-09-48-44.gh-issue-138845.38PSxU.rst @@ -0,0 +1,3 @@ +Correct the documentation for the functions :func:`turtle.reset`, +:func:`turtle.left`, :func:`turtle.right`, :func:`turtle.degrees`, and +:func:`turtle.radians` to address misconceptions.