Confusing docs for turtle.colormode(cmode=None)

[sjlearmonth]

The documentation for the Turtle class attribute colormode below;

turtle.colormode(cmode=None)

is incorrect.

The Turtle class does not have the attribute colormode.

[zware]

That's referring to the module-level function turtle.colormode(), which is implemented by the turtle.TurtleScreen.colormode method.

[sjlearmonth]

Isn't turtle.colormode() a method of the turtle object instantiated by the Turtle class?

[zware]

No; except for in a couple of examples¹, the name turtle refers to the module² throughout the document. Also note that in the colormode example, the calls are to screen.colormode rather than turtle.colormode.

All that said, there's definitely room for improvement in the turtle docs; do you have any suggestions you would like to make either here or in a pull request?

Footnotes

1. namely turtle.onrelease() and turtle.shapetransform(), which could both stand being updated to avoid rebinding turtle ↩

2. There is some doctest trickery such that when running the examples via make doctest turtle really is an instance of Turtle(), but the intention for the reader is that turtle refers to the module. ↩

[sjlearmonth]

I'm confused.

I'm by no means an expert on Python but it strikes me as confusing when the documentation describes turtle.colormode(cmode=None) but it actually means turtle.screen.colormode(cmode=None)

[zware]

It doesn't; it means turtle.colormode(cmode=None) :)

>>> import turtle
>>> turtle.colormode
<function turtle.colormode(cmode=None)>

turtle is a very unusual module in that it is primarily designed for users to use module-level functions to manipulate global state, but implements those functions as methods on some public classes that can also be used as an advanced interface. The documentation is almost entirely geared towards the former, module-level function interface.

[sjlearmonth]

I'm confused.

[sjlearmonth]

That's referring to the module-level function turtle.colormode(), which is implemented by the turtle.TurtleScreen.colormode method.

Ah so what you mean is colormode() is a Python function in the turtle.py module file?

[picnixz]

Ah so what you mean is colormode() is a Python function in the turtle.py module file?

Yes. Actually, the function is not explicitly created but is automatically generated. It's kind of a shortcut. There is a comment in turtle.py:

The following mechanism makes all methods of RawTurtle and Turtle available
as functions. So we can enhance, change, add, delete methods to these
classes and do not need to change anything here.

[sjlearmonth]

What do you mean "...automatically generated..."?. Does the Python interpreter create code like Generative AI?