Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork33.4k
bpo-40283: Clarify turtle.circle() documentation#20928
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
base:main
Are you sure you want to change the base?
Uh oh!
There was an error while loading.Please reload this page.
Conversation
Make it clear what effect the radius and extent arguments haveon 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.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as resolved.
This comment was marked as resolved.
This comment has been minimized.
This comment has been minimized.
This comment was marked as resolved.
This comment was marked as resolved.
| 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I think here it would help talking about clockwise and counter-clockwise instead of using "backwards".
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
| 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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
| >>> turtle.circle(-50, 60) # 60 degree arc with radius 50 drawn clockwise | ||
| >>> turtle.circle(80, steps=6) # regular hexagon | ||
| Unusual cases: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Not sure it's worth separating these examples from the ones above.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I like these examples. I agree that they should not be separated from above.
This comment has been minimized.
This comment has been minimized.
willingc left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
| Arguments: | ||
| radius -- a number | ||
| extent (optional) -- a number | ||
| radius -- a number (distance) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| radius--anumber (distance) | |
| radius--anumber (distancefromcircle'scentertoitscircumference) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
- 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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Perhaps simply "distance from center to boundary".
Please do remember that this is a docstring not a tutorial.
| 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| Ifextentisgiven,donotdrawthewholecircle,butonlyan | |
| If*extent*isgiven,drawanarconthecircle'scircumferencefromthecurrentpositiontoanendingpositionusingacentralangleof*extent*degrees. |
| 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| arc of the circle extent degrees wide starting from the current |
| 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| position.Ifextentisnegative,drawthearcwhilemoving | |
| If*extent*isnegative,drawthearcwhilemoving |
| extent (optional) -- a number (angle, in degrees) | ||
| steps (optional) -- an integer | ||
| With one argument, draw a circle with the given radius. The |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| Withoneargument,drawacirclewiththegivenradius.The | |
| Drawacirclewiththegivenradius. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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. :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
| >>> 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| >>>turtle.circle(50)#fullcircleof radius 50drawn counter-clockwise | |
| >>>turtle.circle(50)# circle drawn counter-clockwise with radius 50 |
| >>> 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| >>>turtle.circle(-75)#fullcircleof radius 75 drawn clockwise | |
| >>>turtle.circle(-75)# circledrawn clockwise with radius 75 |
| >>> 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| >>>turtle.circle(80,steps=6)#regularhexagon | |
| >>>turtle.circle(50,steps=6)# hexagon composed of 6 points on the circle's circumference |
| 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
| >>>turtle.circle(-50,60)# 60 degree arc with radius 50drawn clockwise | |
| >>>turtle.circle(-50,60)# 60 degree arcdrawn clockwisewith radius 50 |
| >>> turtle.circle(-50, 60) # 60 degree arc with radius 50 drawn clockwise | ||
| >>> turtle.circle(80, steps=6) # regular hexagon | ||
| Unusual cases: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I like these examples. I agree that they should not be separated from above.
Uh oh!
There was an error while loading.Please reload this page.
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