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.
Changes fromall commits
File filter
Filter by extension
Conversations
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1937,31 +1937,40 @@ def circle(self, radius, extent = None, steps = None): | ||||||
| """ Draw a circle with given radius. | ||||||
| Arguments: | ||||||
| radius -- a number (distance) | ||||||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Suggested change
Author There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more.
I'll consider how to improve the whole explanation though. Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||||||
| extent (optional) -- a number (angle, in degrees) | ||||||
| steps (optional) -- an integer | ||||||
| With one argument, draw a circle with the given radius. The | ||||||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Suggested change
Author There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. :) Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Perhaps: | ||||||
| center is radius units to the left of the turtle. If radius is | ||||||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Suggested change
Author There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. But if the extent is negative while the radius is positive, then the circle isn't drawn counterclockwise. :) | ||||||
| negative, the center is to the right. | ||||||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Suggested change
| ||||||
| If extent is given, do not draw the whole circle, but only an | ||||||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Suggested change
| ||||||
| arc of the circle extent degrees wide starting from the current | ||||||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Suggested change
| ||||||
| position. If extent is negative, draw the arc while moving | ||||||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Suggested change
| ||||||
| backwards around the circle from the current position. In either | ||||||
Member There was a problem hiding this comment. Choose a reason for hiding this commentThe 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". Author There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||||||
| case the final heading of the turtle will be extent degrees | ||||||
| different from the original heading. | ||||||
| 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. | ||||||
Member There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||||||
| If steps argument is given, that many steps are taken around the | ||||||
| circle or arc rather than the number being calculated automatically. | ||||||
| This can be used to draw regular polygons. | ||||||
| Examples (for a Turtle instance named turtle): | ||||||
| >>> turtle.circle(50) # full circle of radius 50 drawn counter-clockwise | ||||||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Suggested change
| ||||||
| >>> turtle.circle(-75) # full circle of radius 75 drawn clockwise | ||||||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Suggested change
| ||||||
| >>> turtle.circle(-50, 60) # 60 degree arc with radius 50 drawn clockwise | ||||||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Suggested change
| ||||||
| >>> turtle.circle(80, steps=6) # regular hexagon | ||||||
Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Suggested change
| ||||||
| Unusual cases: | ||||||
Member There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. Not sure it's worth separating these examples from the ones above. Contributor There was a problem hiding this comment. Choose a reason for hiding this commentThe 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. | ||||||
| >>> turtle.circle(-50, -180) # semicircle drawn backwards, counter-clockwise | ||||||
| >>> turtle.circle(100, 180, 2) # two sides of a square with diagonal length 200 | ||||||
| >>> turtle.circle(100, 720, 10) # go twice around a pentagon | ||||||
| """ | ||||||
| if self.undobuffer: | ||||||
| self.undobuffer.push(["seq"]) | ||||||