Skip to content

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.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

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

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3daf04d
bpo-40283: Clarify turtle.circle() documentation
mikeweilgart Jun 17, 2020
1d98f96
Fixup typo in example
mikeweilgart Jun 17, 2020
4aab995
Merge branch 'main' into patch-1
ezio-melotti Oct 28, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 32 additions & 23 deletions Lib/turtle.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. 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:
  2. The "circle" method only sometimes draws a circle.

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

Copy link
Contributor

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.

extent (optional) -- a number (angle, in degrees)
steps (optional) -- an integer

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

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. :)

Copy link
Contributor

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.

center is radius units to the left of the turtle. If radius is
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
center is radius units to the left of the turtle. If radius is
If radius is positive, the circle is drawn in the counterclockwise direction, and the circle's center is radius units to the left of the turtle's starting position.

Copy link
Author

Choose a reason for hiding this comment

The 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
negative, the center is to the right.
If radius is negative, the circle is drawn in the clockwise direction, and the center is to the right of the turtle's starting position.


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

Choose a reason for hiding this comment

The 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
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.

arc of the circle extent degrees wide starting from the current
Copy link
Contributor

Choose a reason for hiding this comment

The 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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

backwards around the circle from the current position. In either
Copy link
Member

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".

Copy link
Author

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.

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.
Copy link
Member

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.


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.

Draw a circle with given radius. The center is radius units left
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.

As the circle is approximated by an inscribed regular polygon,
steps determines the number of steps to use. If not given,
it will be calculated automatically. Maybe used to draw regular
polygons.

call: circle(radius) # full circle
--or: circle(radius, extent) # arc
--or: circle(radius, extent, steps)
--or: circle(radius, steps=6) # 6-sided polygon

Example (for a Turtle instance named turtle):
>>> 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
>>> 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

Choose a reason for hiding this comment

The 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
>>> turtle.circle(-50, 60) # 60 degree arc drawn clockwise with radius 50

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Unusual cases:
Copy link
Member

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.

Copy link
Contributor

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.

>>> 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"])
Expand Down