mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-24 20:30:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

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

Browse source 
Use multiple signatures for clarity.
Explain different forms of bgcolor() in details.
Fix outdated docstrings.
This commit is contained in:
Serhiy Storchaka 2025-10-13 18:32:16 +03:00 • committed by GitHub
parent 88fc0a0fdc
commit 525dcfe523
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

@ -777,13 +777,17 @@ Turtle motion
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 color: a colorstring or a numeric color tuple
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::
@ -1152,7 +1156,9 @@ Drawing state
Color control
~~~~~~~~~~~~~
.. function:: pencolor(*args)
.. function:: pencolor()
pencolor(color, /)
pencolor(r, g, b, /)
Return or set the pencolor.
@ -1161,7 +1167,7 @@ Color control
``pencolor()``
Return the current pencolor as color specification string or
as a tuple (see example). May be used as input to another
color/pencolor/fillcolor call.
color/pencolor/fillcolor/bgcolor call.
``pencolor(colorstring)``
Set pencolor to *colorstring*, which is a Tk color specification string,
@ -1201,7 +1207,9 @@ Color control
(50.0, 193.0, 143.0)
.. function:: fillcolor(*args)
.. function:: fillcolor()
fillcolor(color, /)
fillcolor(r, g, b, /)
Return or set the fillcolor.
@ -1210,7 +1218,7 @@ Color control
``fillcolor()``
Return the current fillcolor as color specification string, possibly
in tuple format (see example). May be used as input to another
color/pencolor/fillcolor call.
color/pencolor/fillcolor/bgcolor call.
``fillcolor(colorstring)``
Set fillcolor to *colorstring*, which is a Tk color specification string,
@ -1244,7 +1252,10 @@ Color control
(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.
@ -1870,13 +1881,32 @@ Most of the examples in this section refer to a TurtleScreen instance called
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
3-tuple of such numbers
Return or set the background color of the TurtleScreen.
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::
:skipif: _tkinter is None

115
Lib/turtle.py
View file

@ -1214,16 +1214,32 @@ class TurtleScreen(TurtleScreenBase):
def bgcolor(self, *args):
"""Set or return backgroundcolor of the TurtleScreen.
Arguments (if given): a color string or three numbers
in the range 0..colormode or a 3-tuple of such numbers.
Four input formats are allowed:
- 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):
>>> screen.bgcolor("orange")
>>> screen.bgcolor()
'orange'
>>> screen.bgcolor(0.5,0,0.5)
>>> colormode(255)
>>> screen.bgcolor('#800080')
>>> screen.bgcolor()
'#800080'
(128.0, 0.0, 128.0)
"""
if args:
color = self._colorstr(args)
@ -1678,7 +1694,7 @@ class TNavigator(object):
Example (for a Turtle instance named turtle):
>>> turtle.position()
(0.00, 0.00)
(0.00,0.00)
>>> turtle.forward(25)
>>> turtle.position()
(25.00,0.00)
@ -1701,10 +1717,10 @@ class TNavigator(object):
Example (for a Turtle instance named turtle):
>>> turtle.position()
(0.00, 0.00)
(0.00,0.00)
>>> turtle.backward(30)
>>> turtle.position()
(-30.00, 0.00)
(-30.00,0.00)
"""
self._go(-distance)
@ -1811,7 +1827,7 @@ class TNavigator(object):
Example (for a Turtle instance named turtle):
>>> tp = turtle.pos()
>>> tp
(0.00, 0.00)
(0.00,0.00)
>>> turtle.setpos(60,30)
>>> turtle.pos()
(60.00,30.00)
@ -1891,7 +1907,7 @@ class TNavigator(object):
Example (for a Turtle instance named turtle):
>>> turtle.pos()
(0.00, 0.00)
(0.00,0.00)
>>> turtle.distance(30,40)
50.0
>>> pen = Turtle()
@ -2230,19 +2246,17 @@ class TPen(object):
Arguments:
Several input formats are allowed.
They use 0, 1, 2, or 3 arguments as follows:
color()
Return the current pencolor and the current fillcolor
as a pair of color specification strings as are returned
by pencolor and fillcolor.
color(colorstring), color((r,g,b)), color(r,g,b)
inputs as in pencolor, set both, fillcolor and pencolor,
They use 0 to 3 arguments as follows:
- color()
Return the current pencolor and the current fillcolor as
a pair of color specification strings or tuples as returned
by pencolor() and fillcolor().
- color(colorstring), color((r,g,b)), color(r,g,b)
Inputs as in pencolor(), set both, fillcolor and pencolor,
to the given value.
color(colorstring1, colorstring2),
color((r1,g1,b1), (r2,g2,b2))
equivalent to pencolor(colorstring1) and fillcolor(colorstring2)
and analogously, if the other input format is used.
- color(colorstring1, colorstring2), color((r1,g1,b1), (r2,g2,b2))
Equivalent to pencolor(colorstring1) and fillcolor(colorstring2)
and analogously if the other input format is used.
If turtleshape is a polygon, outline and interior of that polygon
is drawn with the newly set colors.
@ -2253,9 +2267,9 @@ class TPen(object):
>>> turtle.color()
('red', 'green')
>>> colormode(255)
>>> color((40, 80, 120), (160, 200, 240))
>>> color(('#285078', '#a0c8f0'))
>>> color()
('#285078', '#a0c8f0')
((40.0, 80.0, 120.0), (160.0, 200.0, 240.0))
"""
if args:
l = len(args)
@ -2277,28 +2291,32 @@ class TPen(object):
Arguments:
Four input formats are allowed:
- pencolor()
Return the current pencolor as color specification string,
possibly in hex-number format (see example).
May be used as input to another color/pencolor/fillcolor call.
Return the current pencolor as color specification string or
as a tuple (see example). May be used as input to another
color/pencolor/fillcolor/bgcolor call.
- 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))
*a tuple* of r, g, and b, which represent, an RGB color,
and each of r, g, and b are in the range 0..colormode,
where colormode is either 1.0 or 255
Set pencolor 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()).
- pencolor(r, g, b)
r, g, and b represent an RGB color, and each of r, g, and b
are in the range 0..colormode
Set pencolor to the RGB color represented by r, g, and b.
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
with the newly set pencolor.
Example (for a Turtle instance named turtle):
>>> turtle.pencolor('brown')
>>> tup = (0.2, 0.8, 0.55)
>>> turtle.pencolor(tup)
>>> turtle.pencolor()
'#33cc8c'
'brown'
>>> colormode(255)
>>> turtle.pencolor('#32c18f')
>>> turtle.pencolor()
(50.0, 193.0, 143.0)
"""
if args:
color = self._colorstr(args)
@ -2315,26 +2333,31 @@ class TPen(object):
Four input formats are allowed:
- fillcolor()
Return the current fillcolor as color specification string,
possibly in hex-number format (see example).
May be used as input to another color/pencolor/fillcolor call.
possibly in tuple format (see example). May be used as
input to another color/pencolor/fillcolor/bgcolor call.
- 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))
*a tuple* of r, g, and b, which represent, an RGB color,
and each of r, g, and b are in the range 0..colormode,
where colormode is either 1.0 or 255
Set fillcolor 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()).
- fillcolor(r, g, b)
r, g, and b represent an RGB color, and each of r, g, and b
are in the range 0..colormode
Set fillcolor to the RGB color represented by r, g, and b.
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
with the newly set fillcolor.
Example (for a Turtle instance named turtle):
>>> turtle.fillcolor('violet')
>>> col = turtle.pencolor()
>>> turtle.fillcolor(col)
>>> turtle.fillcolor(0, .5, 0)
>>> turtle.fillcolor()
'violet'
>>> colormode(255)
>>> turtle.fillcolor('#ffffff')
>>> turtle.fillcolor()
(255.0, 255.0, 255.0)
"""
if args:
color = self._colorstr(args)