bpo-40283: Clarify turtle.circle() documentation #20928

mikeweilgart · 2020-06-17T06:32:00Z

Make it clear what effect the radius and extent arguments have
on the direction of the circle/arc to be drawn (the referenced bug).

Clarify the rest of the explanation also, as this module is meant for complete beginners.

https://bugs.python.org/issue40283

Make it clear what effect the radius and extent arguments have on the direction of the circle/arc to be drawn (the referenced bug). Clarify the rest of the explanation as this module is meant for complete beginners.

mikeweilgart · 2023-10-28T00:35:23Z

@ezio-melotti I just saw that you removed the "CLA signed" tag a year ago. I did sign the CLA back three years ago when I submitted the PR. What needs to happen now for this to be accepted? :)

ezio-melotti · 2023-10-28T02:23:27Z

The label was removed simply because we switched to a different system to detect if the CLA was signed. I closed and reopened the PR to trigger the new checks.

ezio-melotti · 2023-10-28T02:34:28Z

Lib/turtle.py

+        If extent is given, do not draw the whole circle, but only an
+        arc of the circle extent degrees wide starting from the current
+        position. If extent is negative, draw the arc while moving
+        backwards around the circle from the current position. In either


I think here it would help talking about clockwise and counter-clockwise instead of using "backwards".

The trick is that either radius or extent, or both, may be negative. Any time either is switched from negative to positive or back, the resulting direction of drawing (clockwise or counter-clockwise) will be switched also.

ezio-melotti · 2023-10-28T02:38:24Z

Lib/turtle.py

+        The circle or arc drawn is not a true geometric curve (impossible
+        on a computer screen composed of pixels), but rather is composed
+        of many very short straight steps. The number of steps to use is
+        calculated automatically to give the appearance of a true curve.


In order to keep the docstring more concise, I would merge this paragraph with the next and remove the part about why the circle is created by steps. Saying that it's done in steps, that the number is calculated automatically if not specified, and that this can be used to draw polygons it's enough IMHO.

ezio-melotti · 2023-10-28T02:40:00Z

Lib/turtle.py

+        >>> turtle.circle(-50, 60)      # 60 degree arc with radius 50 drawn clockwise
+        >>> turtle.circle(80, steps=6)  # regular hexagon
+
+        Unusual cases:


Not sure it's worth separating these examples from the ones above.

I like these examples. I agree that they should not be separated from above.

willingc

Thanks for the PR @mikeweilgart. I think you have raised some good points for clarification. Since this is a docstring, I think we should lean to being precise with descriptions.

willingc · 2023-10-28T15:57:37Z

Lib/turtle.py

@@ -1937,31 +1937,40 @@ def circle(self, radius, extent = None, steps = None):
        """ Draw a circle with given radius.

        Arguments:
-        radius -- a number
-        extent (optional) -- a number
+        radius -- a number (distance)


Suggested change

radius -- a number (distance)

radius -- a number (distance from circle's center to its circumference)

Circumference is itself a distance; it doesn't properly mean "edge of the circle." I think "distance from circle's center to its edge" is a decent idea, except:

The "circle" method only sometimes draws a circle.

I'll consider how to improve the whole explanation though.

Perhaps simply "distance from center to boundary".

Please do remember that this is a docstring not a tutorial.

willingc · 2023-10-28T16:24:55Z

Lib/turtle.py

+        center is radius units to the left of the turtle. If radius is
+        negative, the center is to the right.
+
+        If extent is given, do not draw the whole circle, but only an


Suggested change

If extent is given, do not draw the whole circle, but only an

If *extent* is given, draw an arc on the circle's circumference from the current position to an ending position using a central angle of *extent* degrees.

willingc · 2023-10-28T16:25:17Z

Lib/turtle.py

+        negative, the center is to the right.
+
+        If extent is given, do not draw the whole circle, but only an
+        arc of the circle extent degrees wide starting from the current


Suggested change

arc of the circle extent degrees wide starting from the current

willingc · 2023-10-28T16:26:10Z

Lib/turtle.py

+
+        If extent is given, do not draw the whole circle, but only an
+        arc of the circle extent degrees wide starting from the current
+        position. If extent is negative, draw the arc while moving


Suggested change

position. If extent is negative, draw the arc while moving

If *extent* is negative, draw the arc while moving

willingc · 2023-10-28T16:41:31Z

Lib/turtle.py

        steps (optional) -- an integer
+
+        With one argument, draw a circle with the given radius. The


Suggested change

With one argument, draw a circle with the given radius. The

Draw a circle with the given radius.

Except that if there is more than one argument, a circle is NOT drawn. It may be a portion of a circle, or a portion of a polygon. Try running any proposed documentation past a bright seven-year-old and you'll see some of the rationale for the wording choices I made. :)

Perhaps:
Draw a circle with the given radius when passed the default argument radius.
When additional arguments are given, a circle, arc, polygon, or portion of a polygon may be drawn.

willingc · 2023-10-28T16:52:03Z

Lib/turtle.py

-        >>> turtle.circle(50)
-        >>> turtle.circle(120, 180)  # semicircle
+        Examples (for a Turtle instance named turtle):
+        >>> turtle.circle(50)           # full circle of radius 50 drawn counter-clockwise


Suggested change

>>> turtle.circle(50) # full circle of radius 50 drawn counter-clockwise

>>> turtle.circle(50) # circle drawn counter-clockwise with radius 50

willingc · 2023-10-28T16:52:37Z

Lib/turtle.py

-        >>> turtle.circle(120, 180)  # semicircle
+        Examples (for a Turtle instance named turtle):
+        >>> turtle.circle(50)           # full circle of radius 50 drawn counter-clockwise
+        >>> turtle.circle(-75)          # full circle of radius 75 drawn clockwise


Suggested change

>>> turtle.circle(-75) # full circle of radius 75 drawn clockwise

>>> turtle.circle(-75) # circle drawn clockwise with radius 75

willingc · 2023-10-28T16:54:17Z

Lib/turtle.py

+        >>> turtle.circle(50)           # full circle of radius 50 drawn counter-clockwise
+        >>> turtle.circle(-75)          # full circle of radius 75 drawn clockwise
+        >>> turtle.circle(-50, 60)      # 60 degree arc with radius 50 drawn clockwise
+        >>> turtle.circle(80, steps=6)  # regular hexagon


Suggested change

>>> turtle.circle(80, steps=6) # regular hexagon

>>> turtle.circle(50, steps=6) # hexagon composed of 6 points on the circle's circumference

willingc · 2023-10-28T16:58:35Z

Lib/turtle.py

+        Examples (for a Turtle instance named turtle):
+        >>> turtle.circle(50)           # full circle of radius 50 drawn counter-clockwise
+        >>> turtle.circle(-75)          # full circle of radius 75 drawn clockwise
+        >>> turtle.circle(-50, 60)      # 60 degree arc with radius 50 drawn clockwise


Suggested change

>>> turtle.circle(-50, 60) # 60 degree arc with radius 50 drawn clockwise

>>> turtle.circle(-50, 60) # 60 degree arc drawn clockwise with radius 50

willingc · 2023-10-28T17:10:37Z

Lib/turtle.py

+        >>> turtle.circle(-50, 60)      # 60 degree arc with radius 50 drawn clockwise
+        >>> turtle.circle(80, steps=6)  # regular hexagon
+
+        Unusual cases:


I like these examples. I agree that they should not be separated from above.

bpo-40283: Clarify turtle.circle() documentation

3daf04d

Make it clear what effect the radius and extent arguments have on the direction of the circle/arc to be drawn (the referenced bug). Clarify the rest of the explanation as this module is meant for complete beginners.

the-knights-who-say-ni added the CLA not signed label Jun 17, 2020

This comment was marked as outdated.

Sign in to view

bedevere-bot added the awaiting review label Jun 17, 2020

Fixup typo in example

1d98f96

the-knights-who-say-ni added CLA signed and removed CLA not signed labels Jun 18, 2020

guchao mannequin mentioned this pull request Apr 10, 2022

Documentation of turtle.circle() #84464

Open

ezio-melotti removed the CLA signed label Jul 13, 2022

ezio-melotti closed this Oct 28, 2023

ezio-melotti reopened this Oct 28, 2023

This comment has been minimized.

Sign in to view

ezio-melotti reviewed Oct 28, 2023

View reviewed changes

Merge branch 'main' into patch-1

4aab995

This comment has been minimized.

Sign in to view

ezio-melotti added the skip news label Oct 28, 2023

ezio-melotti requested a review from willingc October 28, 2023 02:42

willingc reviewed Oct 28, 2023

View reviewed changes

willingc added awaiting changes DO-NOT-MERGE and removed awaiting review labels Oct 28, 2023

	radius -- a number (distance)
	radius -- a number (distance from circle's center to its circumference)

	If extent is given, do not draw the whole circle, but only an
	If extent is given, draw an arc on the circle's circumference from the current position to an ending position using a central angle of extent degrees.

	position. If extent is negative, draw the arc while moving
	If extent is negative, draw the arc while moving

		steps (optional) -- an integer

		With one argument, draw a circle with the given radius. The

	With one argument, draw a circle with the given radius. The
	Draw a circle with the given radius.

	>>> turtle.circle(50) # full circle of radius 50 drawn counter-clockwise
	>>> turtle.circle(50) # circle drawn counter-clockwise with radius 50

	>>> turtle.circle(-75) # full circle of radius 75 drawn clockwise
	>>> turtle.circle(-75) # circle drawn clockwise with radius 75

	>>> turtle.circle(80, steps=6) # regular hexagon
	>>> turtle.circle(50, steps=6) # hexagon composed of 6 points on the circle's circumference

	>>> turtle.circle(-50, 60) # 60 degree arc with radius 50 drawn clockwise
	>>> turtle.circle(-50, 60) # 60 degree arc drawn clockwise with radius 50

Uh oh!

bpo-40283: Clarify turtle.circle() documentation #20928

Are you sure you want to change the base?

bpo-40283: Clarify turtle.circle() documentation #20928

Uh oh!

Conversation

mikeweilgart commented Jun 17, 2020 • edited by bedevere-bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

mikeweilgart commented Oct 28, 2023

Uh oh!

This comment has been minimized.

ezio-melotti commented Oct 28, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mikeweilgart commented Jun 17, 2020 •

edited by bedevere-bot

Loading