Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-08 17:41:42 +00:00
Code Issues Projects Releases Packages Wiki Activity

[3.13] gh-138772: Fix and improve documentation for turtle color functions (GH-139325) (GH-140048)

Browse source 
Use multiple signatures for clarity.
Explain different forms of bgcolor() in details.
Fix outdated docstrings.
(cherry picked from commit 525dcfe523)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
This commit is contained in:
Miss Islington (bot) 2025-10-13 17:56:31 +02:00 • committed by GitHub
parent 278384150a
commit 0e7893207b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 110 additions and 57 deletions
Download patch file Download diff file Expand all files Collapse all files

52
Doc/library/turtle.rst
View file

@ -743,13 +743,17 @@ Turtle motion
180.0 180.0
.. function:: dot(size=None, *color) .. function:: dot()
dot(size)
dot(color, /)
dot(size, color, /)
dot(size, r, g, b, /)
:param size: an integer >= 1 (if given) :param size: an integer >= 1 (if given)
:param color: a colorstring or a numeric color tuple :param color: a colorstring or a numeric color tuple
Draw a circular dot with diameter *size*, using *color*. If *size* is Draw a circular dot with diameter *size*, using *color*. If *size* is
not given, the maximum of pensize+4 and 2*pensize is used. not given, the maximum of ``pensize+4`` and ``2*pensize`` is used.
.. doctest:: .. doctest::
@ -1118,7 +1122,9 @@ Drawing state
Color control Color control
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
.. function:: pencolor(*args) .. function:: pencolor()
pencolor(color, /)
pencolor(r, g, b, /)
Return or set the pencolor. Return or set the pencolor.
@ -1127,7 +1133,7 @@ Color control
``pencolor()`` ``pencolor()``
Return the current pencolor as color specification string or Return the current pencolor as color specification string or
as a tuple (see example). May be used as input to another as a tuple (see example). May be used as input to another
color/pencolor/fillcolor call. color/pencolor/fillcolor/bgcolor call.
``pencolor(colorstring)`` ``pencolor(colorstring)``
Set pencolor to *colorstring*, which is a Tk color specification string, Set pencolor to *colorstring*, which is a Tk color specification string,
@ -1167,7 +1173,9 @@ Color control
(50.0, 193.0, 143.0) (50.0, 193.0, 143.0)
.. function:: fillcolor(*args) .. function:: fillcolor()
fillcolor(color, /)
fillcolor(r, g, b, /)
Return or set the fillcolor. Return or set the fillcolor.
@ -1176,7 +1184,7 @@ Color control
``fillcolor()`` ``fillcolor()``
Return the current fillcolor as color specification string, possibly Return the current fillcolor as color specification string, possibly
in tuple format (see example). May be used as input to another in tuple format (see example). May be used as input to another
color/pencolor/fillcolor call. color/pencolor/fillcolor/bgcolor call.
``fillcolor(colorstring)`` ``fillcolor(colorstring)``
Set fillcolor to *colorstring*, which is a Tk color specification string, Set fillcolor to *colorstring*, which is a Tk color specification string,
@ -1210,7 +1218,10 @@ Color control
(255.0, 255.0, 255.0) (255.0, 255.0, 255.0)
.. function:: color(*args) .. function:: color()
color(color, /)
color(r, g, b, /)
color(pencolor, fillcolor, /)
Return or set pencolor and fillcolor. Return or set pencolor and fillcolor.
@ -1796,13 +1807,32 @@ Most of the examples in this section refer to a TurtleScreen instance called
Window control Window control
-------------- --------------
.. function:: bgcolor(*args) .. function:: bgcolor()
bgcolor(color, /)
bgcolor(r, g, b, /)
:param args: a color string or three numbers in the range 0..colormode or a Return or set the background color of the TurtleScreen.
3-tuple of such numbers
Four input formats are allowed:
Set or return background color of the TurtleScreen. ``bgcolor()``
Return the current background color as color specification string or
as a tuple (see example). May be used as input to another
color/pencolor/fillcolor/bgcolor call.
``bgcolor(colorstring)``
Set the background color to *colorstring*, which is a Tk color
specification string, such as ``"red"``, ``"yellow"``, or ``"#33cc8c"``.
``bgcolor((r, g, b))``
Set the background color to the RGB color represented by the tuple of
*r*, *g*, and *b*.
Each of *r*, *g*, and *b* must be in the range 0..colormode, where
colormode is either 1.0 or 255 (see :func:`colormode`).
``bgcolor(r, g, b)``
Set the background color to the RGB color represented by *r*, *g*, and *b*. Each of
*r*, *g*, and *b* must be in the range 0..colormode.
.. doctest:: .. doctest::
:skipif: _tkinter is None :skipif: _tkinter is None

115
Lib/turtle.py
View file

@ -1213,16 +1213,32 @@ def turtles(self):
def bgcolor(self, *args): def bgcolor(self, *args):
"""Set or return backgroundcolor of the TurtleScreen. """Set or return backgroundcolor of the TurtleScreen.
Arguments (if given): a color string or three numbers Four input formats are allowed:
in the range 0..colormode or a 3-tuple of such numbers. - bgcolor()
Return the current background color as color specification
string or as a tuple (see example). May be used as input
to another color/pencolor/fillcolor/bgcolor call.
- bgcolor(colorstring)
Set the background color to colorstring, which is a Tk color
specification string, such as "red", "yellow", or "#33cc8c".
- bgcolor((r, g, b))
Set the background color to the RGB color represented by
the tuple of r, g, and b. Each of r, g, and b must be in
the range 0..colormode, where colormode is either 1.0 or 255
(see colormode()).
- bgcolor(r, g, b)
Set the background color to the RGB color represented by
r, g, and b. Each of r, g, and b must be in the range
0..colormode.
Example (for a TurtleScreen instance named screen): Example (for a TurtleScreen instance named screen):
>>> screen.bgcolor("orange") >>> screen.bgcolor("orange")
>>> screen.bgcolor() >>> screen.bgcolor()
'orange' 'orange'
>>> screen.bgcolor(0.5,0,0.5) >>> colormode(255)
>>> screen.bgcolor('#800080')
>>> screen.bgcolor() >>> screen.bgcolor()
'#800080' (128.0, 0.0, 128.0)
""" """
if args: if args:
color = self._colorstr(args) color = self._colorstr(args)
@ -1624,7 +1640,7 @@ def forward(self, distance):
Example (for a Turtle instance named turtle): Example (for a Turtle instance named turtle):
>>> turtle.position() >>> turtle.position()
(0.00, 0.00) (0.00,0.00)
>>> turtle.forward(25) >>> turtle.forward(25)
>>> turtle.position() >>> turtle.position()
(25.00,0.00) (25.00,0.00)
@ -1647,10 +1663,10 @@ def back(self, distance):
Example (for a Turtle instance named turtle): Example (for a Turtle instance named turtle):
>>> turtle.position() >>> turtle.position()
(0.00, 0.00) (0.00,0.00)
>>> turtle.backward(30) >>> turtle.backward(30)
>>> turtle.position() >>> turtle.position()
(-30.00, 0.00) (-30.00,0.00)
""" """
self._go(-distance) self._go(-distance)
@ -1757,7 +1773,7 @@ def goto(self, x, y=None):
Example (for a Turtle instance named turtle): Example (for a Turtle instance named turtle):
>>> tp = turtle.pos() >>> tp = turtle.pos()
>>> tp >>> tp
(0.00, 0.00) (0.00,0.00)
>>> turtle.setpos(60,30) >>> turtle.setpos(60,30)
>>> turtle.pos() >>> turtle.pos()
(60.00,30.00) (60.00,30.00)
@ -1837,7 +1853,7 @@ def distance(self, x, y=None):
Example (for a Turtle instance named turtle): Example (for a Turtle instance named turtle):
>>> turtle.pos() >>> turtle.pos()
(0.00, 0.00) (0.00,0.00)
>>> turtle.distance(30,40) >>> turtle.distance(30,40)
50.0 50.0
>>> pen = Turtle() >>> pen = Turtle()
@ -2176,19 +2192,17 @@ def color(self, *args):
Arguments: Arguments:
Several input formats are allowed. Several input formats are allowed.
They use 0, 1, 2, or 3 arguments as follows: They use 0 to 3 arguments as follows:
- color()
color() Return the current pencolor and the current fillcolor as
Return the current pencolor and the current fillcolor a pair of color specification strings or tuples as returned
as a pair of color specification strings as are returned by pencolor() and fillcolor().
by pencolor and fillcolor. - color(colorstring), color((r,g,b)), color(r,g,b)
color(colorstring), color((r,g,b)), color(r,g,b) Inputs as in pencolor(), set both, fillcolor and pencolor,
inputs as in pencolor, set both, fillcolor and pencolor,
to the given value. to the given value.
color(colorstring1, colorstring2), - color(colorstring1, colorstring2), color((r1,g1,b1), (r2,g2,b2))
color((r1,g1,b1), (r2,g2,b2)) Equivalent to pencolor(colorstring1) and fillcolor(colorstring2)
equivalent to pencolor(colorstring1) and fillcolor(colorstring2) and analogously if the other input format is used.
and analogously, if the other input format is used.
If turtleshape is a polygon, outline and interior of that polygon If turtleshape is a polygon, outline and interior of that polygon
is drawn with the newly set colors. is drawn with the newly set colors.
@ -2199,9 +2213,9 @@ def color(self, *args):
>>> turtle.color() >>> turtle.color()
('red', 'green') ('red', 'green')
>>> colormode(255) >>> colormode(255)
>>> color((40, 80, 120), (160, 200, 240)) >>> color(('#285078', '#a0c8f0'))
>>> color() >>> color()
('#285078', '#a0c8f0') ((40.0, 80.0, 120.0), (160.0, 200.0, 240.0))
""" """
if args: if args:
l = len(args) l = len(args)
@ -2223,28 +2237,32 @@ def pencolor(self, *args):
Arguments: Arguments:
Four input formats are allowed: Four input formats are allowed:
- pencolor() - pencolor()
Return the current pencolor as color specification string, Return the current pencolor as color specification string or
possibly in hex-number format (see example). as a tuple (see example). May be used as input to another
May be used as input to another color/pencolor/fillcolor call. color/pencolor/fillcolor/bgcolor call.
- pencolor(colorstring) - pencolor(colorstring)
s is a Tk color specification string, such as "red" or "yellow" Set pencolor to colorstring, which is a Tk color
specification string, such as "red", "yellow", or "#33cc8c".
- pencolor((r, g, b)) - pencolor((r, g, b))
*a tuple* of r, g, and b, which represent, an RGB color, Set pencolor to the RGB color represented by the tuple of
and each of r, g, and b are in the range 0..colormode, r, g, and b. Each of r, g, and b must be in the range
where colormode is either 1.0 or 255 0..colormode, where colormode is either 1.0 or 255 (see
colormode()).
- pencolor(r, g, b) - pencolor(r, g, b)
r, g, and b represent an RGB color, and each of r, g, and b Set pencolor to the RGB color represented by r, g, and b.
are in the range 0..colormode Each of r, g, and b must be in the range 0..colormode.
If turtleshape is a polygon, the outline of that polygon is drawn If turtleshape is a polygon, the outline of that polygon is drawn
with the newly set pencolor. with the newly set pencolor.
Example (for a Turtle instance named turtle): Example (for a Turtle instance named turtle):
>>> turtle.pencolor('brown') >>> turtle.pencolor('brown')
>>> tup = (0.2, 0.8, 0.55)
>>> turtle.pencolor(tup)
>>> turtle.pencolor() >>> turtle.pencolor()
'#33cc8c' 'brown'
>>> colormode(255)
>>> turtle.pencolor('#32c18f')
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
""" """
if args: if args:
color = self._colorstr(args) color = self._colorstr(args)
@ -2261,26 +2279,31 @@ def fillcolor(self, *args):
Four input formats are allowed: Four input formats are allowed:
- fillcolor() - fillcolor()
Return the current fillcolor as color specification string, Return the current fillcolor as color specification string,
possibly in hex-number format (see example). possibly in tuple format (see example). May be used as
May be used as input to another color/pencolor/fillcolor call. input to another color/pencolor/fillcolor/bgcolor call.
- fillcolor(colorstring) - fillcolor(colorstring)
s is a Tk color specification string, such as "red" or "yellow" Set fillcolor to colorstring, which is a Tk color
specification string, such as "red", "yellow", or "#33cc8c".
- fillcolor((r, g, b)) - fillcolor((r, g, b))
*a tuple* of r, g, and b, which represent, an RGB color, Set fillcolor to the RGB color represented by the tuple of
and each of r, g, and b are in the range 0..colormode, r, g, and b. Each of r, g, and b must be in the range
where colormode is either 1.0 or 255 0..colormode, where colormode is either 1.0 or 255 (see
colormode()).
- fillcolor(r, g, b) - fillcolor(r, g, b)
r, g, and b represent an RGB color, and each of r, g, and b Set fillcolor to the RGB color represented by r, g, and b.
are in the range 0..colormode Each of r, g, and b must be in the range 0..colormode.
If turtleshape is a polygon, the interior of that polygon is drawn If turtleshape is a polygon, the interior of that polygon is drawn
with the newly set fillcolor. with the newly set fillcolor.
Example (for a Turtle instance named turtle): Example (for a Turtle instance named turtle):
>>> turtle.fillcolor('violet') >>> turtle.fillcolor('violet')
>>> col = turtle.pencolor() >>> turtle.fillcolor()
>>> turtle.fillcolor(col) 'violet'
>>> turtle.fillcolor(0, .5, 0) >>> colormode(255)
>>> turtle.fillcolor('#ffffff')
>>> turtle.fillcolor()
(255.0, 255.0, 255.0)
""" """
if args: if args:
color = self._colorstr(args) color = self._colorstr(args)