[3.13] gh-86726: Document tkinter method-name conflicts (GH-151917) (GH-151934)

Document where widget methods shadow inherited Misc, geometry-manager and
Wm methods, correct the inaccurate "size/bbox is an alias of
grid_size/grid_bbox" claims, and add "# overrides X" comments at the
definitions.

Also document the geometry-manager ambiguity: the short names forget, info,
slaves and propagate are defined by Pack, Place and Grid but
resolve to the pack variant.

Cross-reference the window-manager methods grid, forget and state with the
same-named grid geometry manager, Pack.forget and ttk.Widget.state.

(cherry picked from commit 4de5683)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: serhiy-storchaka

Doc/library/tkinter.rst

@@ -1266,11 +1266,19 @@ Base and mixin classes
       If *belowThis* is given, the widget is moved to be just below it in the
       stacking order instead.
 
+      :meth:`tkraise`/:meth:`lift` and :meth:`lower` are overridden by the
+      :class:`Canvas` widget,
+      where they restack canvas items instead.
+
    .. method:: image_names()
 
       Return the names of all images that currently exist in the Tcl
       interpreter.
 
+      This is overridden by the :class:`Text` widget,
+      where :meth:`!image_names` returns the names of its embedded images
+      instead.
+
    .. method:: image_types()
 
       Return the available image types, such as ``'photo'`` and ``'bitmap'``.
@@ -1303,7 +1311,11 @@ Base and mixin classes
       column 0 to that cell; if *col2* and *row2* are also given, it spans from
       the cell (*column*, *row*) to the cell (*col2*, *row2*).
 
-      :meth:`bbox` is an alias of :meth:`!grid_bbox`.
+      :meth:`bbox` is an alias of :meth:`!grid_bbox`,
+      except on :class:`Canvas`, :class:`Listbox`, :class:`Spinbox`,
+      :class:`Text`, :class:`ttk.Entry <tkinter.ttk.Entry>` and
+      :class:`ttk.Treeview <tkinter.ttk.Treeview>`,
+      which provide their own :meth:`!bbox` method.
 
    .. method:: columnconfigure(index, cnf={}, **kw)
       :no-typesetting:
@@ -1378,7 +1390,9 @@ Base and mixin classes
       Return the size of the grid managed by this container as a
       ``(columns, rows)`` tuple.
 
-      :meth:`size` is an alias of :meth:`!grid_size`.
+      :meth:`size` is an alias of :meth:`!grid_size`,
+      except on the :class:`Listbox` widget,
+      which provides its own :meth:`!size` method.
 
    .. method:: grid_slaves(row=None, column=None)
 
@@ -1647,7 +1661,10 @@ Base and mixin classes
       widget's display, the widget is remembered as the focus window for its
       top level, and the focus will be redirected to it the next time the
       window manager gives the focus to the top level.
-      :meth:`focus` is an alias of :meth:`!focus_set`.
+      :meth:`focus` is an alias of :meth:`!focus_set`,
+      except on the :class:`Canvas` and
+      :class:`ttk.Treeview <tkinter.ttk.Treeview>` widgets,
+      which provide their own :meth:`!focus` method.
 
    .. method:: focus_force()
 
@@ -1749,6 +1766,10 @@ Base and mixin classes
       The *displayof* keyword argument names a widget that determines the
       display on which to operate, and defaults to this widget.
 
+      This is overridden by the :class:`Entry`, :class:`Listbox` and
+      :class:`Spinbox` widgets,
+      where :meth:`!selection_clear` clears the widget's own selection instead.
+
    .. method:: selection_get(**kw)
 
       Return the contents of the current X selection.
@@ -1826,7 +1847,7 @@ Base and mixin classes
       first and ``STRING`` is used as a fallback.
       The *displayof* keyword argument names a widget that determines the
       display, and defaults to the root window of the application.
-      This is equivalent to ``selection_get(selection= 'CLIPBOARD')``.
+      This is equivalent to ``selection_get(selection='CLIPBOARD')``.
 
    .. method:: option_add(pattern, value, priority=None)
 
@@ -2512,6 +2533,8 @@ Base and mixin classes
       widget is managed again.
       :meth:`wm_forget` is an alias of :meth:`!forget`.
 
+      Not to be confused with :meth:`Pack.forget`.
+
       .. versionadded:: 3.3
 
    .. method:: wm_frame()
@@ -2557,6 +2580,8 @@ Base and mixin classes
       string if the window is not gridded.
       :meth:`wm_grid` is an alias of :meth:`!grid`.
 
+      Not to be confused with the grid geometry manager :meth:`Grid.grid`.
+
    .. method:: wm_group(pathName=None)
       :no-typesetting:
 
@@ -2794,6 +2819,9 @@ Base and mixin classes
       :meth:`iconwindow`); the ``'icon'`` state cannot be set.
       :meth:`wm_state` is an alias of :meth:`!state`.
 
+      Not to be confused with :meth:`ttk.Widget.state
+      <tkinter.ttk.Widget.state>`.
+
    .. method:: wm_title(string=None)
       :no-typesetting:
 
@@ -2845,6 +2873,21 @@ Base and mixin classes
    *pack* geometry manager.
    See also :ref:`pack-the-packer`.
 
+   .. note::
+
+      :class:`Pack`, :class:`Place` and :class:`Grid` all define the short
+      method names :meth:`!forget`, :meth:`!info`, :meth:`!slaves`,
+      :meth:`!content` and :meth:`!propagate`.
+      On a widget the bare names resolve to the *pack* manager's versions,
+      since :class:`Pack` and :class:`Misc` precede :class:`Place` and
+      :class:`Grid` in the method resolution order,
+      whatever manager actually manages the widget;
+      and :meth:`!configure`/:meth:`!config` configure the widget's options,
+      not its geometry.
+      Use the explicit ``pack_*``, ``grid_*`` and ``place_*`` methods
+      (and ``pack``, ``grid``, ``place`` for geometry configuration)
+      to act on a specific geometry manager.
+
    .. method:: configure(cnf={}, **kw)
       :no-typesetting:
 
@@ -2907,7 +2950,13 @@ Base and mixin classes
       Unmap the widget and remove it from the packing order, forgetting its
       packing options.
       It can be packed again later with :meth:`pack_configure`.
-      :meth:`forget` is an alias of :meth:`!pack_forget`.
+      :meth:`forget` is an alias of :meth:`!pack_forget`,
+      except on :class:`PanedWindow`,
+      :class:`ttk.Notebook <tkinter.ttk.Notebook>` and
+      :class:`ttk.PanedWindow <tkinter.ttk.PanedWindow>`,
+      which provide their own :meth:`!forget` method.
+
+      Not to be confused with :meth:`Wm.forget`.
 
    .. method:: info()
       :no-typesetting:
@@ -3004,15 +3053,13 @@ Base and mixin classes
 
       Unmap the widget and remove it from the placement, forgetting its place
       options.
-      :meth:`forget` is an alias of :meth:`!place_forget`.
 
    .. method:: info()
       :no-typesetting:
 
    .. method:: place_info()
 
       Return a dictionary of the widget's current place options.
-      :meth:`info` is an alias of :meth:`!place_info`.
 
    .. method:: slaves()
       :no-typesetting:
@@ -3021,7 +3068,6 @@ Base and mixin classes
 
       Same as :meth:`Misc.place_slaves`: return the list of widgets placed in
       this widget.
-      :meth:`slaves` is an alias of :meth:`!place_slaves`.
 
 
 .. class:: Grid()
@@ -3041,6 +3087,9 @@ Base and mixin classes
                grid(cnf={}, **kw)
 
       Position the widget in a cell of its container's grid.
+
+      Not to be confused with :meth:`Wm.grid`.
+
       The supported options are:
 
       *row*, *column*
@@ -3085,7 +3134,6 @@ Base and mixin classes
 
       Unmap the widget and remove it from the grid, forgetting its grid
       options.
-      :meth:`forget` is an alias of :meth:`!grid_forget`.
 
    .. method:: grid_remove()
 
@@ -3098,15 +3146,18 @@ Base and mixin classes
    .. method:: grid_info()
 
       Return a dictionary of the widget's current grid options.
-      :meth:`info` is an alias of :meth:`!grid_info`.
 
    .. method:: bbox(column=None, row=None, col2=None, row2=None)
       :no-typesetting:
 
    .. method:: grid_bbox(column=None, row=None, col2=None, row2=None)
 
       Same as :meth:`Misc.grid_bbox`.
-      :meth:`bbox` is an alias of :meth:`!grid_bbox`.
+      :meth:`bbox` is an alias of :meth:`!grid_bbox`,
+      except on :class:`Canvas`, :class:`Listbox`, :class:`Spinbox`,
+      :class:`Text`, :class:`ttk.Entry <tkinter.ttk.Entry>` and
+      :class:`ttk.Treeview <tkinter.ttk.Treeview>`,
+      which provide their own :meth:`!bbox` method.
 
    .. method:: columnconfigure(index, cnf={}, **kw)
       :no-typesetting:
@@ -3142,7 +3193,9 @@ Base and mixin classes
 
       Same as :meth:`Misc.grid_size`: return a ``(columns, rows)`` tuple giving
       the size of the grid.
-      :meth:`size` is an alias of :meth:`!grid_size`.
+      :meth:`size` is an alias of :meth:`!grid_size`,
+      except on the :class:`Listbox` widget,
+      which provides its own :meth:`!size` method.
 
    .. method:: propagate()
                propagate(flag)
@@ -3152,7 +3205,6 @@ Base and mixin classes
                grid_propagate(flag)
 
       Same as :meth:`Misc.grid_propagate`.
-      :meth:`propagate` is an alias of :meth:`!grid_propagate`.
 
    .. method:: slaves(row=None, column=None)
       :no-typesetting:
@@ -3161,7 +3213,6 @@ Base and mixin classes
 
       Same as :meth:`Misc.grid_slaves`: return the widgets managed in the grid,
       optionally restricted to a *row* and/or *column*.
-      :meth:`slaves` is an alias of :meth:`!grid_slaves`.
 
 
 .. class:: XView()
@@ -3761,6 +3812,14 @@ Widget classes
       This has no effect on embedded window items.
       :meth:`lower` is an alias of :meth:`!tag_lower`.
 
+      .. note::
+
+         On a :class:`Canvas`, :meth:`tkraise`/:meth:`lift` and :meth:`lower`
+         restack canvas items,
+         shadowing the inherited :meth:`Misc.tkraise`/:meth:`Misc.lift` and
+         :meth:`Misc.lower` methods that restack the widget itself,
+         which are therefore not available.
+
    .. method:: tag_bind(tagOrId, sequence=None, func=None, add=None)
 
       Bind the callback *func* to the event *sequence* for all items given by
@@ -3796,6 +3855,9 @@ Widget classes
       Return ``None`` if no item matches or the matching items have nothing to
       display.
 
+      This shadows the inherited :meth:`!Misc.bbox`;
+      use :meth:`~Misc.grid_bbox` for the grid bounding box.
+
    .. method:: canvasx(screenx, gridspacing=None)
 
       Given a window x-coordinate *screenx*, return the canvas x-coordinate
@@ -3822,6 +3884,9 @@ Widget classes
       An item only displays the insertion cursor when both it is the focus item
       and its canvas has the input focus.
 
+      This shadows the inherited :meth:`!Misc.focus`;
+      use :meth:`~Misc.focus_set` to focus the widget itself.
+
    .. method:: icursor(tagOrId, index, /)
 
       Set the insertion cursor of the items given by *tagOrId* to just before
@@ -4019,6 +4084,12 @@ Widget classes
       If the selection is not in this widget the method has no effect.
       :meth:`select_clear` is an alias of :meth:`!selection_clear`.
 
+      .. note::
+
+         This shadows the inherited :meth:`Misc.selection_clear`,
+         which clears the X selection;
+         that method is not available on an :class:`Entry`.
+
    .. method:: select_from(index)
       :no-typesetting:
 
@@ -4158,6 +4229,9 @@ Widget classes
 
       Return the total number of items in the listbox.
 
+      This shadows the inherited :meth:`!Misc.size`;
+      use :meth:`~Misc.grid_size` for the grid size.
+
    .. method:: index(index)
 
       Return the integer index value corresponding to *index*, or ``None`` if
@@ -4174,6 +4248,9 @@ Widget classes
       visible, the result still gives the full area of the item, including the
       parts that are not visible.
 
+      This shadows the inherited :meth:`!Misc.bbox`;
+      use :meth:`~Misc.grid_bbox` for the grid bounding box.
+
    .. method:: nearest(y)
 
       Given a y-coordinate within the listbox window, return the index of the
@@ -4222,6 +4299,12 @@ Widget classes
       The selection state of items outside this range is not changed.
       :meth:`select_clear` is an alias of :meth:`!selection_clear`.
 
+      .. note::
+
+         This shadows the inherited :meth:`Misc.selection_clear`,
+         which clears the X selection;
+         that method is not available on a :class:`Listbox`.
+
    .. method:: select_includes(index)
       :no-typesetting:
 
@@ -4603,6 +4686,9 @@ Widget classes
       Remove the pane containing *child* from the panedwindow.
       All geometry management options for *child* are forgotten.
       :meth:`forget` is an alias of :meth:`!remove`.
+      This shadows the inherited geometry-manager :meth:`!forget`;
+      use :meth:`~Pack.pack_forget`, :meth:`~Grid.grid_forget` or
+      :meth:`~Place.place_forget` to remove the widget itself from its manager.
 
    .. method:: panes()
 
@@ -4894,6 +4980,9 @@ Widget classes
       The bounding box may refer to a region outside the visible area of the
       window.
 
+      This shadows the inherited :meth:`!Misc.bbox`;
+      use :meth:`~Misc.grid_bbox` for the grid bounding box.
+
    .. method:: identify(x, y)
 
       Return the name of the window element at the pixel coordinates *x*, *y*:
@@ -4955,6 +5044,12 @@ Widget classes
       Clear the selection if it is currently in this widget.
       If the selection is not in this widget, the method has no effect.
 
+      .. note::
+
+         This shadows the inherited :meth:`Misc.selection_clear`,
+         which clears the X selection;
+         that method is not available on a :class:`Spinbox`.
+
    .. method:: selection_element(element=None)
 
       Set or get the currently selected element.
@@ -5112,6 +5207,9 @@ Widget classes
       pixels, of the visible part of the character at *index*, or ``None`` if
       that character is not visible on the screen.
 
+      This shadows the inherited :meth:`!Misc.bbox`;
+      use :meth:`~Misc.grid_bbox` for the grid bounding box.
+
    .. method:: dlineinfo(index)
 
       Return a tuple ``(x, y, width, height, baseline)`` describing the display
@@ -5366,6 +5464,12 @@ Widget classes
 
       Return a tuple of the names of all images embedded in the widget.
 
+      .. note::
+
+         This shadows the inherited :meth:`Misc.image_names`,
+         which returns the names of all images in the Tcl interpreter;
+         that method is not available on a :class:`Text`.
+
    .. method:: window_create(index, cnf={}, **kw)
 
       Embed a window (any widget) at *index*.
@@ -5556,6 +5660,7 @@ Variable classes
    .. method:: set(value)
 
       Set the variable to *value*.
+      :meth:`initialize` is an alias of :meth:`!set`.
 
       .. versionadded:: 3.3
          The *initialize* spelling.
@@ -5602,6 +5707,7 @@ Variable classes
       *mode* is one of the strings ``'r'``, ``'w'`` or ``'u'``, for read, write
       or unset.
       Return the internal name of the registered callback.
+      :meth:`trace` is an alias of :meth:`!trace_variable`.
 
       .. deprecated:: 3.6
          Use :meth:`trace_add` instead.  This method wraps a Tcl feature that
@@ -5673,6 +5779,7 @@ Variable classes
    .. method:: set(value)
 
       Set the variable to *value*, converting it to a boolean.
+      :meth:`initialize` is an alias of :meth:`!set`.
 
       .. versionadded:: 3.3
          The *initialize* spelling.