Skip to content

gh-78335: Improve tkinter widget docstrings #21118

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.

Sign up for GitHub

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
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

gh-78335: Improve tkinter widget docstrings #21118

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2a706a3
bpo-34154: Improve tkinter widget docstrings
ZackerySpytz Jun 24, 2020
ced2629
Merge branch 'main' into bpo-34154-tkinter-widget-docstrings
erlend-aasland Jan 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 45 additions & 40 deletions Lib/tkinter/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2600,8 +2600,8 @@ def __init__(self, master=None, cnf={}, **kw):

Valid resource names: background, bd, bg, borderwidth, class,
colormap, container, cursor, height, highlightbackground,
highlightcolor, highlightthickness, menu, relief, screen, takefocus,
use, visual, width."""
highlightcolor, highlightthickness, menu, padx, pady, relief,
screen, takefocus, use, visual, width."""
if kw:
cnf = _cnfmerge((cnf, kw))
extra = ()
Expand Down Expand Up @@ -2986,12 +2986,13 @@ def __init__(self, master=None, cnf={}, **kw):
"""Construct a checkbutton widget with the parent MASTER.

Valid resource names: activebackground, activeforeground, anchor,
background, bd, bg, bitmap, borderwidth, command, cursor,
background, bd, bg, bitmap, borderwidth, command, compound, cursor,
disabledforeground, fg, font, foreground, height,
highlightbackground, highlightcolor, highlightthickness, image,
indicatoron, justify, offvalue, onvalue, padx, pady, relief,
selectcolor, selectimage, state, takefocus, text, textvariable,
underline, variable, width, wraplength."""
indicatoron, justify, offrelief, offvalue, onvalue, overrelief,
padx, pady, relief, selectcolor, selectimage, state, takefocus,
text, textvariable, tristateimage, tristatevalue, underline,
variable, width, wraplength."""
Widget.__init__(self, master, 'checkbutton', cnf, kw)

def deselect(self):
Expand Down Expand Up @@ -3022,10 +3023,11 @@ def __init__(self, master=None, cnf={}, **kw):
"""Construct an entry widget with the parent MASTER.

Valid resource names: background, bd, bg, borderwidth, cursor,
exportselection, fg, font, foreground, highlightbackground,
highlightcolor, highlightthickness, insertbackground,
insertborderwidth, insertofftime, insertontime, insertwidth,
invalidcommand, invcmd, justify, relief, selectbackground,
disabledbackground, disabledforeground, exportselection,
fg, font, foreground, highlightbackground, highlightcolor,
highlightthickness, insertbackground, insertborderwidth,
insertofftime, insertontime, insertwidth, invalidcommand,
invcmd, justify, readonlybackground, relief, selectbackground,
Copy link
Member

@terryjreedy terryjreedy Jun 25, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tk docs do not list 'invcmd' but do list 'vcmd'. So I will presume without conrary evidence that this is either missing from the tk doc or is added by tkinter.

Copy link
Member

@serhiy-storchaka serhiy-storchaka Jul 15, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

invcmd is an alias of invalidcommand and vcmd is an alias of validatecommand.

selectborderwidth, selectforeground, show, state, takefocus,
textvariable, validate, validatecommand, vcmd, width,
xscrollcommand."""
Expand Down Expand Up @@ -3109,7 +3111,8 @@ def __init__(self, master=None, cnf={}, **kw):

Valid resource names: background, bd, bg, borderwidth, class,
colormap, container, cursor, height, highlightbackground,
highlightcolor, highlightthickness, relief, takefocus, visual, width."""
highlightcolor, highlightthickness, padx, pady, relief, takefocus,
visual, width."""
cnf = _cnfmerge((cnf, kw))
extra = ()
if 'class_' in cnf:
Expand All @@ -3130,8 +3133,8 @@ def __init__(self, master=None, cnf={}, **kw):
STANDARD OPTIONS

activebackground, activeforeground, anchor,
background, bitmap, borderwidth, cursor,
disabledforeground, font, foreground,
background, bitmap, borderwidth, compound,
Copy link
Member

@terryjreedy terryjreedy Jun 25, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

tk docs include bg, even though they do not for many of widgets above.

Suggested change
background, bitmap, borderwidth, compound,
background, bg, bitmap, borderwidth, compound,

cursor, disabledforeground, font, foreground,
highlightbackground, highlightcolor,
highlightthickness, image, justify,
padx, pady, relief, takefocus, text,
Expand All @@ -3151,11 +3154,12 @@ class Listbox(Widget, XView, YView):
def __init__(self, master=None, cnf={}, **kw):
"""Construct a listbox widget with the parent MASTER.

Valid resource names: background, bd, bg, borderwidth, cursor,
exportselection, fg, font, foreground, height, highlightbackground,
highlightcolor, highlightthickness, relief, selectbackground,
selectborderwidth, selectforeground, selectmode, setgrid, takefocus,
width, xscrollcommand, yscrollcommand, listvariable."""
Valid resource names: activestyle, background, bd, bg, borderwidth,
cursor, disabledforeground, exportselection, fg, font, foreground,
height, highlightbackground, highlightcolor, highlightthickness,
justify, listvariable, relief, selectbackground, selectborderwidth,
selectforeground, selectmode, setgrid, state, takefocus, width,
xscrollcommand, yscrollcommand."""
Widget.__init__(self, master, 'listbox', cnf, kw)

def activate(self, index):
Expand Down Expand Up @@ -3412,12 +3416,12 @@ def __init__(self, master=None, cnf={}, **kw):
"""Construct a radiobutton widget with the parent MASTER.

Valid resource names: activebackground, activeforeground, anchor,
background, bd, bg, bitmap, borderwidth, command, cursor,
disabledforeground, fg, font, foreground, height,
highlightbackground, highlightcolor, highlightthickness, image,
indicatoron, justify, padx, pady, relief, selectcolor, selectimage,
state, takefocus, text, textvariable, underline, value, variable,
width, wraplength."""
background, bd, bg, bitmap, borderwidth, command, compound, cursor,
disabledforeground, fg, font, foreground, height, highlightbackground,
highlightcolor, highlightthickness, image, indicatoron, justify,
offrelief, overrelief, padx, pady, relief, selectcolor, selectimage,
state, takefocus, text, textvariable, tristateimage, tristatevalue,
underline, value, variable, width, wraplength."""
Widget.__init__(self, master, 'radiobutton', cnf, kw)

def deselect(self):
Expand Down Expand Up @@ -3535,22 +3539,22 @@ def __init__(self, master=None, cnf={}, **kw):

STANDARD OPTIONS

background, borderwidth, cursor,
exportselection, font, foreground,
highlightbackground, highlightcolor,
highlightthickness, insertbackground,
insertborderwidth, insertofftime,
insertontime, insertwidth, padx, pady,
relief, selectbackground,
background, blockcursor, borderwidth,
Copy link
Member

@terryjreedy terryjreedy Jun 25, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The list of standard options was correct. The 6 additions
blockcursor, endline (spelled correctly), inactiveselectbackground, insertunfocused, startline, tabstyle,
should be moved to WIDGET-SPECIFIC OPTIONS

cursor, endine, exportselection, font,
foreground, highlightbackground, highlightcolor,
highlightthickness, inactiveselectbackground,
insertbackground, insertborderwidth,
insertofftime, insertontime, insertunfocused,
insertwidth, padx, pady, relief, selectbackground,
selectborderwidth, selectforeground,
setgrid, takefocus,
xscrollcommand, yscrollcommand,
setgrid, startline, tabstyle, takefocus,
xscrollcommand, yscrollcommand.

WIDGET-SPECIFIC OPTIONS

autoseparators, height, maxundo,
spacing1, spacing2, spacing3,
state, tabs, undo, width, wrap,
state, tabs, undo, width, wrap.

"""
Widget.__init__(self, master, 'text', cnf, kw)
Expand Down Expand Up @@ -4169,8 +4173,8 @@ def __init__(self, master=None, cnf={}, **kw):
insertborderwidth, insertofftime,
insertontime, insertwidth, justify, relief,
repeatdelay, repeatinterval,
selectbackground, selectborderwidth
selectforeground, takefocus, textvariable
selectbackground, selectborderwidth,
selectforeground, takefocus, textvariable,
xscrollcommand.

WIDGET-SPECIFIC OPTIONS
Expand All @@ -4181,8 +4185,8 @@ def __init__(self, master=None, cnf={}, **kw):
disabledforeground, format, from,
invalidcommand, increment,
readonlybackground, state, to,
validate, validatecommand values,
width, wrap,
validate, validatecommand, values,
width, wrap.
"""
Widget.__init__(self, master, 'spinbox', cnf, kw)

Expand Down Expand Up @@ -4365,13 +4369,14 @@ def __init__(self, master=None, cnf={}, **kw):
STANDARD OPTIONS

background, borderwidth, cursor, height,
orient, relief, width
orient, proxybackground, proxyborderwidth,
Copy link
Member

@terryjreedy terryjreedy Jun 25, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

height and width were misplaced as standard. They and the 3 new proxy... options should be moved down.

proxyrelief, relief, width.

WIDGET-SPECIFIC OPTIONS

handlepad, handlesize, opaqueresize,
sashcursor, sashpad, sashrelief,
sashwidth, showhandle,
sashwidth, showhandle.
"""
Widget.__init__(self, master, 'panedwindow', cnf, kw)

Expand Down
1 change: 1 addition & 0 deletions Misc/NEWS.d/next/Library/2020-06-24-08-44-06.bpo-34154.coStMk.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Improve the docstrings in the :mod:`tkinter` module.