classification
Title: Documentation of turtle.circle()
Type: behavior Stage: needs patch
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: DahlitzFlorian, cajetan.rodrigues, docs@python, guchao, terry.reedy
Priority: normal Keywords: easy, newcomer friendly

Created on 2020-04-14 16:54 by guchao, last changed 2020-05-24 13:56 by DahlitzFlorian.

Messages (4)
msg366401 - (view) Author: guchao (guchao) Date: 2020-04-14 16:54
refer to circle() in the url: https://docs.python.org/2/library/turtle.html#turtle.circle

[current]
... Draw the arc in counterclockwise direction if radius is positive, otherwise in clockwise direction. 

[suggestion]
... Draw the arc in counterclockwise direction if extent is positive, otherwise in clockwise direction. 

[explanation]
It should be "extent" , instead of "radius", that affects the direction.
msg367722 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-04-30 00:39
It would be bizarre if the current doc were correct, but have you verified by experiment that the change is correct?

The patch itself would be trivial, hence the keyword addition.  PR author can request that I review.
msg368290 - (view) Author: Cajetan Rodrigues (cajetan.rodrigues) * Date: 2020-05-06 18:58
When I checked, I found the following:

turtle.circle(50, 50)   # counter-clockwise
turtle.circle(-50, -50) # counter-clockwise
turtle.circle(-50, 50)  # clockwise
turtle.circle(50, -50)  # clockwise

So it seems both radius and extent need to be of the same signage to effect a counter-clockwise draw. However, for the 2 cases where extent is negative, the draw happens through the turtle's tail rather than the head. Looks weird.
msg369800 - (view) Author: Florian Dahlitz (DahlitzFlorian) * Date: 2020-05-24 13:56
I tested it and can confirm the findings from @cajetan.rodrigues. However, this does not seem to be _not_ documented. The documentation clearly states that using a positive value for radius results in a counter-clockwise direction, whereas a negative number results in a clockwise direction. This is true.

Now, let's have a look at using radius _together_ with extent, which is not (clearly) documented as this point. Using a positive value results in the same direction, but in a not full drawn circle. This seems intuitive and is documented:

    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.

Using a negative value changes the direction of radius, which does also seem reasonable and intuitive.

My suggestion is not to replace "radius" by "extent" as suggested by @guchao as it is IMHO wrong. But I agree that it would be good to leave a note there or to add examples demonstrating the behaviour of different (signed) values of radius and extent, so the intent and behaviour is clearly documented.
History
Date User Action Args
2020-05-24 13:56:43DahlitzFloriansetnosy: + DahlitzFlorian
messages: + msg369800
2020-05-06 18:58:42cajetan.rodriguessetnosy: + cajetan.rodrigues
messages: + msg368290
2020-04-30 00:39:59terry.reedysettype: resource usage -> behavior
versions: + Python 3.7, Python 3.8, Python 3.9
keywords: + easy, newcomer friendly
nosy: + terry.reedy

messages: + msg367722
stage: needs patch
2020-04-14 16:54:40guchaocreate