From 1507d119d930a412a3423f737503a9c94cee3b56 Mon Sep 17 00:00:00 2001 From: Stewyn Chaudhary Date: Tue, 22 Sep 2026 22:45:01 -0500 Subject: [PATCH] gh-84464: Clarify how the signs of radius and extent affect turtle.circle() The docs said the arc is drawn counterclockwise whenever radius is positive, but a negative extent makes the turtle move backward and reverses the direction. Also state where the center is for a negative radius and how the final heading depends on the sign of radius. --- Doc/library/turtle.rst | 9 ++++++--- Lib/turtle.py | 9 ++++++--- .../2026-09-22-12-00-00.gh-issue-84464.tRtCrc.rst | 2 ++ 3 files changed, 14 insertions(+), 6 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2026-09-22-12-00-00.gh-issue-84464.tRtCrc.rst diff --git a/Doc/library/turtle.rst b/Doc/library/turtle.rst index f28c4230f3d6b89..ce950d64620ed90 100644 --- a/Doc/library/turtle.rst +++ b/Doc/library/turtle.rst @@ -757,9 +757,12 @@ Turtle motion the turtle; *extent* -- an angle -- determines which part of the circle is drawn. If *extent* is not given, draw the entire circle. If *extent* is not a full circle, one endpoint of the arc is the current pen - position. Draw the arc in counterclockwise direction if *radius* is - positive, otherwise in clockwise direction. Finally the direction of the - turtle is changed by the amount of *extent*. + position. If *radius* is negative, the center is to the right of the + turtle instead. The turtle moves forward along the arc if *extent* is + positive and backward if it is negative, so the arc is drawn + counterclockwise if *radius* and *extent* have the same sign, otherwise + clockwise. Finally the turtle turns left by *extent* if *radius* is + positive, otherwise right by *extent*. As the circle is approximated by an inscribed regular polygon, *steps* determines the number of steps to use. If not given, it will be diff --git a/Lib/turtle.py b/Lib/turtle.py index b49df26bd07bc5a..f8c4b2fdb71bd87 100644 --- a/Lib/turtle.py +++ b/Lib/turtle.py @@ -2028,9 +2028,12 @@ def circle(self, radius, extent = None, steps = None): of the turtle; extent - an angle - determines which part of the circle is drawn. If extent is not given, draw the entire circle. If extent is not a full circle, one endpoint of the arc is the - current pen position. Draw the arc in counterclockwise direction - if radius is positive, otherwise in clockwise direction. Finally - the direction of the turtle is changed by the amount of extent. + current pen position. If radius is negative, the center is to the + right of the turtle instead. The turtle moves forward along the + arc if extent is positive and backward if it is negative, so the + arc is drawn counterclockwise if radius and extent have the same + sign, otherwise clockwise. Finally the turtle turns left by extent + if radius is positive, otherwise right by extent. As the circle is approximated by an inscribed regular polygon, steps determines the number of steps to use. If not given, diff --git a/Misc/NEWS.d/next/Documentation/2026-09-22-12-00-00.gh-issue-84464.tRtCrc.rst b/Misc/NEWS.d/next/Documentation/2026-09-22-12-00-00.gh-issue-84464.tRtCrc.rst new file mode 100644 index 000000000000000..f94f4ae0906fd4a --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-09-22-12-00-00.gh-issue-84464.tRtCrc.rst @@ -0,0 +1,2 @@ +Clarify the documentation of :func:`turtle.circle`: the sign of *extent* +also affects whether the arc is drawn clockwise or counterclockwise.