Skip to content

Documentation of turtle.circle() #84464

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 our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
guchao mannequin opened this issue Apr 14, 2020 · 4 comments
Open

Documentation of turtle.circle() #84464

guchao mannequin opened this issue Apr 14, 2020 · 4 comments
Labels
docs Documentation in the Doc dir easy type-bug An unexpected behavior, bug, or error

Comments

@guchao
Copy link
Mannequin

guchao mannequin commented Apr 14, 2020

BPO 40283
Nosy @terryjreedy, @DahlitzFlorian, @caje731, @fjhenigman, @mikeweilgart
PRs
  • bpo-40283: Clarify turtle.circle() documentation #20928
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
    closed_at = None
    created_at = <Date 2020-04-14.16:54:40.368>
    labels = ['easy', 'type-bug', '3.8', '3.9', '3.7', 'docs']
    title = 'Documentation of turtle.circle()'
    updated_at = <Date 2020-06-17.06:32:01.670>
    user = 'https://bugs.python.org/guchao'

    bugs.python.org fields:

    activity = <Date 2020-06-17.06:32:01.670>
    actor = 'Weildcard'
    assignee = 'docs@python'
    closed = False
    closed_date = None
    closer = None
    components = ['Documentation']
    creation = <Date 2020-04-14.16:54:40.368>
    creator = 'guchao'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 40283
    keywords = ['patch', 'easy', 'newcomer friendly']
    message_count = 4.0
    messages = ['366401', '367722', '368290', '369800']
    nosy_count = 7.0
    nosy_names = ['terry.reedy', 'docs@python', 'DahlitzFlorian', 'cajetan.rodrigues', 'guchao', 'fjh', 'Weildcard']
    pr_nums = ['20928']
    priority = 'normal'
    resolution = None
    stage = 'patch review'
    status = 'open'
    superseder = None
    type = 'behavior'
    url = 'https://bugs.python.org/issue40283'
    versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

    Linked PRs

    @guchao
    Copy link
    Mannequin Author

    guchao mannequin commented Apr 14, 2020

    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.

    @guchao guchao mannequin added the performance Performance or resource usage label Apr 14, 2020
    @guchao guchao mannequin assigned docspython Apr 14, 2020
    @guchao guchao mannequin added the docs Documentation in the Doc dir label Apr 14, 2020
    @terryjreedy
    Copy link
    Member

    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.

    @terryjreedy terryjreedy added easy 3.7 (EOL) end of life 3.8 (EOL) end of life 3.9 only security fixes type-bug An unexpected behavior, bug, or error and removed performance Performance or resource usage labels Apr 30, 2020
    @caje731
    Copy link
    Mannequin

    caje731 mannequin commented May 6, 2020

    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.

    @DahlitzFlorian
    Copy link
    Mannequin

    DahlitzFlorian mannequin commented May 24, 2020

    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.

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @picnixz picnixz removed 3.9 only security fixes 3.8 (EOL) end of life 3.7 (EOL) end of life labels Jan 19, 2025
    @picnixz picnixz added stdlib Python modules in the Lib dir and removed stdlib Python modules in the Lib dir labels Jan 19, 2025
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    docs Documentation in the Doc dir easy type-bug An unexpected behavior, bug, or error
    Projects
    Status: No status
    Status: Todo
    Development

    No branches or pull requests

    2 participants