gh-126008: Improve docstrings for Tkinter cget and configure methods #133303

serhiy-storchaka · 2025-05-02T14:37:09Z

Explain the behavior of Widget.configure() depending on arguments.
Unify descriptions.
Replace "resource" with "option".

Issue: Tkinter ttk widgets cget() returning _tkinter.Tcl_Obj instead of str #126008

…thods * Explain the behavior of Widget.configure() depending on arguments. * Unify descriptions. * Replace "resource" with "option".

tomasr8 · 2025-05-02T15:02:35Z

Lib/tkinter/__init__.py

-        option(s) to have the given value(s); in this case the
-        command returns an empty string. The following options
-        are supported:
+        """Query or modify the configuration options for window TAGORID.


It took me a while to understand what TAGORID meant, maybe it'd be better if we match the parameter name, i.e. use tarOrId (and similar for the other cases)?

As I indicated elsewhere, I think the raw test should be *tagOrID* as italicizing option names is better than all-capping them.

In THIS file, capitalization is used for parameter names. It is not ideal, but we should be consistent.

Lib/tkinter/__init__.py

terryjreedy · 2025-05-03T23:44:25Z

Lib/tkinter/__init__.py

        return self.tk.call(
            (self._w, 'itemcget') + (tagOrId, '-'+option))

    def itemconfigure(self, tagOrId, cnf=None, **kw):
-        """Configure resources of an item TAGORID.
+        """Query or modify the configuration options of an item TAGORID.


Suggested change

"""Query or modify the configuration options of an item TAGORID.

"""Query or modify the configuration options of item *tagOrID*.

Just remembered that

https://peps.python.org/pep-0257/#multi-line-docstrings says "Do not use the Emacs convention of mentioning the arguments of functions or methods in upper case in running text. Python is case sensitive and the argument names can be used for keyword arguments, so the docstring should document the correct argument names." 'tagOrID' is an example of why not. It goes on to suggest " It is best to list each argument on a separate line. For example:..." but this tends to bloat the doc. Don't add *s if you do not want, but please drop the all caps at least here.

Using different convention for different methods will do more harm than good. This is a different issue, we will change the convention after fixing all docstrings.

terryjreedy · 2025-05-03T23:49:53Z

Lib/tkinter/__init__.py

-        option(s) to have the given value(s); in this case the
-        command returns an empty string. The following options
-        are supported:
+        """Query or modify the configuration options for window TAGORID.


As I indicated elsewhere, I think the raw test should be *tagOrID* as italicizing option names is better than all-capping them.

bedevere-app · 2025-05-03T23:50:10Z

When you're done making the requested changes, leave the comment: I have made the requested changes; please review again.

bskinn · 2025-06-02T20:36:29Z

Lib/tkinter/__init__.py

 under Tk.

 Widgets are positioned with one of the geometry managers Place, Pack
 or Grid. These managers can be called with methods place, pack, grid
 available in every Widget.

-Actions are bound to events by resources (e.g. keyword argument
-command) or with the method bind.
+Actions are bound to events by options (e.g. the command


Either this, or "command" should be a docs cross-reference.

Suggested change

Actions are bound to events by options (e.g. the command

Actions are bound to events by options (e.g., the *command*

Posted this before seeing the discussion about omitting formatting from docstrings. This should be consistent with whatever is decided.

bskinn · 2025-06-02T20:37:29Z

Lib/tkinter/__init__.py

-Actions are bound to events by resources (e.g. keyword argument
-command) or with the method bind.
+Actions are bound to events by options (e.g. the command
+keyword argument) or with the bind() method.


I think this is right; or, it should be inserted as a docs crossref if possible:

Suggested change

keyword argument) or with the bind() method.

keyword argument) or with the *bind()* method.

Posted this before seeing the discussion about omitting formatting from docstrings. This should be consistent with whatever is decided.

bskinn · 2025-06-02T20:38:04Z

Lib/tkinter/__init__.py

@@ -847,7 +847,7 @@ def tk_focusNext(self):
        The focus order first goes to the next child, then to
        the children of the child recursively and then to the
        next sibling which is higher in the stacking order.  A
-        widget is omitted if it has the takefocus resource set
+        widget is omitted if it has the takefocus option set


Formatting, or crossref if possible:

Suggested change

widget is omitted if it has the takefocus option set

widget is omitted if it has the *takefocus* option set

Posted this before seeing the discussion about omitting formatting from docstrings. This should be consistent with whatever is decided.

bskinn · 2025-06-02T20:38:52Z

Lib/tkinter/__init__.py

-        The values for resources are specified as keyword
-        arguments. To get an overview about
-        the allowed keyword arguments call the method keys.
+        If no arguments is specified, return a dictionary describing


Suggested change

If no arguments is specified, return a dictionary describing

If no arguments are specified, return a dictionary describing

bskinn · 2025-06-02T20:45:33Z

Lib/tkinter/__init__.py

-
-        Option may be any value allowed by the paneconfigure subcommand
-        """
+        """Return the value of option for window."""


Not sure about the parameter naming here. The method only has a child param... perhaps something like:

Suggested change

"""Return the value of option for window."""

"""Return the value of option for a the window child."""

Understandability here would definitely benefit from adding formatting, as long as it would render in the docs: *child*

pythongh-126008: Improve docstrings for Tkinter cget and configure me…

c7f9234

…thods * Explain the behavior of Widget.configure() depending on arguments. * Unify descriptions. * Replace "resource" with "option".

serhiy-storchaka added docs Documentation in the Doc dir skip news needs backport to 3.13 bugs and security fixes labels May 2, 2025

serhiy-storchaka requested a review from terryjreedy May 2, 2025 14:37

github-project-automation bot added this to Docs PRs May 2, 2025

github-project-automation bot moved this to Todo in Docs PRs May 2, 2025

bedevere-app bot mentioned this pull request May 2, 2025

Tkinter ttk widgets cget() returning _tkinter.Tcl_Obj instead of str #126008

Open

bedevere-app bot added the awaiting core review label May 2, 2025

tomasr8 reviewed May 2, 2025

View reviewed changes

terryjreedy requested changes May 3, 2025

View reviewed changes

bedevere-app bot removed the awaiting core review label May 3, 2025

bedevere-app bot added the awaiting changes label May 3, 2025

Address some review comments.

c17b0db

serhiy-storchaka added the needs backport to 3.14 bugs and security fixes label May 8, 2025

serhiy-storchaka requested a review from a team May 13, 2025 10:36

Merge branch 'main' into docs-tkinter-configure

3076927

bskinn reviewed Jun 2, 2025

View reviewed changes

	"""Query or modify the configuration options of an item TAGORID.
	"""Query or modify the configuration options of item tagOrID.

	Actions are bound to events by options (e.g. the command
	Actions are bound to events by options (e.g., the command

	keyword argument) or with the bind() method.
	keyword argument) or with the bind() method.

	widget is omitted if it has the takefocus option set
	widget is omitted if it has the takefocus option set

	If no arguments is specified, return a dictionary describing
	If no arguments are specified, return a dictionary describing

	"""Return the value of option for window."""
	"""Return the value of option for a the window child."""

Uh oh!

gh-126008: Improve docstrings for Tkinter cget and configure methods #133303

Are you sure you want to change the base?

gh-126008: Improve docstrings for Tkinter cget and configure methods #133303

Uh oh!

Conversation

serhiy-storchaka commented May 2, 2025 • edited by bedevere-app bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bedevere-app bot commented May 3, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

serhiy-storchaka commented May 2, 2025 •

edited by bedevere-app bot

Loading