gh-86726: Document the full public API of tkinter by serhiy-storchaka · Pull Request #151579 · python/cpython

serhiy-storchaka · 2026-06-17T06:49:56Z

Replace the previously sparse reference documentation with full coverage of the public API of the tkinter package, written from the Tcl/Tk manual pages, the existing documentation and the module docstrings.

Doc/library/tkinter.rst gains a "Reference" section documenting every public class, method, function and constant of the core module -- the widgets, the Misc, Wm, Pack, Place, Grid, XView and YView mix-ins, the Variable and image classes, the module-level functions and the symbolic constants.
Doc/library/tkinter.ttk.rst, dialog.rst, tkinter.font.rst and the other module pages document their remaining classes, methods and functions.

The descriptions are Python-oriented (correct return types -- tuples rather than Tcl lists, booleans, integers, None on cancellation, and so on) and were checked against the Tcl/Tk 9.1 manual pages and the implementation.

versionadded, versionchanged and deprecated directives are added for the public API, determined from the git history relative to Python 3.0: the tkinter.ttk module (3.1); the Text, Wm, Menu and Misc methods exposing Tk 8.5 features (3.3); and the many later additions and behavior changes up to 3.15. The Tk version required by features added after Tk 8.6 is noted as well. The bundled Tcl/Tk version is updated to 9.0 and the manual-page links point at the tcl9.0 reference.

Issue: Tkinter extention modules have no documentation #59551

Issue: Improve Tkinter Documentation #86726

Replace the previously sparse reference documentation with full coverage of the public API of the tkinter package, written from the Tcl/Tk manual pages, the existing documentation and the module docstrings. * Doc/library/tkinter.rst gains a "Reference" section documenting every public class, method, function and constant of the core module -- the widgets, the Misc, Wm, Pack, Place, Grid, XView and YView mix-ins, the Variable and image classes, the module-level functions and the symbolic constants. * Doc/library/tkinter.ttk.rst, dialog.rst, tkinter.font.rst and the other module pages document their remaining classes, methods and functions. The descriptions are Python-oriented (correct return types -- tuples rather than Tcl lists, booleans, integers, None on cancellation, and so on) and were checked against the Tcl/Tk 9.1 manual pages and the implementation. versionadded, versionchanged and deprecated directives are added for the public API, determined from the git history relative to Python 3.0: the tkinter.ttk module (3.1); the Text, Wm, Menu and Misc methods exposing Tk 8.5 features (3.3); and the many later additions and behavior changes up to 3.15. The Tk version required by features added after Tk 8.6 is noted as well. The bundled Tcl/Tk version is updated to 9.0 and the manual-page links point at the tcl9.0 reference. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

read-the-docs-community · 2026-06-17T06:53:27Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #33199555 | 📁 Comparing 414cadf against main (9e863fa)

🔍 Preview build

21 files changed · ± 21 modified

± Modified

Merge alias methods into a single directive with stacked signatures instead of documenting each spelling separately: Font.config/configure, Variable.set/initialize, Variable.trace_variable/trace, and BooleanVar.set/initialize. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…nchors Document each alias as a :no-typesetting: directive placed just before its main definition, so the alias keeps an index entry and a reference anchor without rendering a duplicate signature. Each alias is named in the prose of the main method, with the alias spelling as a live link. The common geometry-manager spellings pack(), place() and grid() are kept as visible stacked signatures rather than hidden. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…natures Document the propagate(), pack_propagate() and grid_propagate() query/set methods with separate no-argument and one-argument signatures instead of exposing the internal ['_noarg_'] default placeholder. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Reflow the prose added or modified on this branch so that each sentence starts on a new line (semantic line breaks), wrapping long sentences at 79 columns. Only changed paragraphs are touched; tables, literal blocks, lists and definition lists are left as they were. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Use the standard "``wm_X`` is an alias of X" wording for the window-manager methods instead of the bespoke "the wm_-prefixed spelling is an equivalent alias" note. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Undocument the tclobjs_to_py() and setup_master() utility functions, which are internal helpers rather than public API. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Qualify references that did not resolve: the geometry/Frame classes in scrolledtext, Button.invoke in tkinter.rst, and Scrollbar.set, the Widget.configure methods (documented on Misc) and IntVar in ttk. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Restore the ``tkinter`` module context after the _tkinter entry in the "Additional modules" list (it was leaking until the Reference section), and qualify the bare method and attribute names used in the introductory prose so they resolve. Redirect the Widget.cget(), Widget.configure() and Widget.bind() references to the Misc methods where those are documented, add the missing Listbox.itemconfig alias anchor, document the TclError exception, and drop the markup from references that have no target (tkinter.constants and the X11 cursor name XC_hand2). Doc/library/tkinter.rst and Doc/library/tkinter.scrolledtext.rst are now free of nitpick warnings and are removed from Doc/tools/.nitignore. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…tation Resolve every nitpick reference warning in tkinter.ttk.rst: * give the ``ttk``-prefixed class references an explicit target while keeping their displayed names, and de-link the bare ``ttk`` module references; * qualify the methods inherited by the themed widgets -- the Widget methods and winfo_class() to Misc, the Entry methods to the base Entry, and grid() to the geometry-manager mix-in -- shown by their bare names in the inherited-method lists; * point the selection and xview method families at Entry.selection_adjust and XView.xview. Reflow the touched paragraphs using semantic line breaks, and drop tkinter.ttk.rst from Doc/tools/.nitignore now that it is warning-free. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…tions Revert the LoadFileDialog.ok_command and SaveFileDialog.ok_command paragraphs to their original line wrapping; these were re-wrapped without any change to their content. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

StanFromIreland · 2026-06-17T13:53:34Z

This is a massive PR, maybe split it up into a few to make it reviewable?

serhiy-storchaka · 2026-06-17T14:11:54Z

90% of it is one continuous piece in tkinter.rst. Committing other changes without this piece will not fix anything (it can even cause regression). Splitting that piece risks introducing errors and will make backporting more difficult. These changes were generated by AI under my management. I fixed every problem I could think of, and since I didn't write it, I'm not worried about the grammar.

Since it's not code, nothing bad will happen even if some errors are found later. In any case, it's better than no documentation.

So I'm going to quickly merge and backport this, and then move on to other issues.

hugovk · 2026-06-18T07:23:39Z

+   .. method:: anchor(anchor=None)
+      :no-typesetting:
+
+   .. method:: grid_anchor(anchor=None)
+
+      Same as :meth:`Misc.grid_anchor`.
+      :meth:`anchor` is an alias of :meth:`!grid_anchor`.


This is under the Grid class, but they don't exist there:

>>> import tkinter >>> tkinter.Grid.anchor Traceback (most recent call last): File "<python-input-3>", line 1, in <module> tkinter.Grid.anchor AttributeError: type object 'Grid' has no attribute 'anchor' >>> tkinter.Grid.grid_anchor Traceback (most recent call last): File "<python-input-2>", line 1, in <module> tkinter.Grid.grid_anchor AttributeError: type object 'Grid' has no attribute 'grid_anchor'

They are under Misc:

>>> tkinter.Misc.anchor <function Misc.grid_anchor at 0x1046707d0> >>> tkinter.Misc.grid_anchor <function Misc.grid_anchor at 0x1046707d0>

Gotcha!

I think this is a bug which we should fix in main, but for now we should documentation.

I think it would also be better to move implementations of these methods to Grid, but again, only in main.

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

serhiy-storchaka · 2026-06-18T07:55:51Z

+   .. method:: anchor(anchor=None)
+      :no-typesetting:
+
+   .. method:: grid_anchor(anchor=None)
+
+      Same as :meth:`Misc.grid_anchor`.
+      :meth:`anchor` is an alias of :meth:`!grid_anchor`.


Gotcha!

I think this is a bug which we should fix in main, but for now we should documentation.

I think it would also be better to move implementations of these methods to Grid, but again, only in main.

… documentation Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

… their Tk versions Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…-docs

miss-islington-app · 2026-06-18T12:39:11Z

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.14, 3.15.
🐍🍒⛏🤖

bedevere-app · 2026-06-18T12:39:26Z

GH-151649 is a backport of this pull request to the 3.15 branch.

bedevere-app · 2026-06-18T12:39:31Z

GH-151650 is a backport of this pull request to the 3.14 branch.

…H-151649) Replace the previously sparse reference documentation with full coverage of the public API of the tkinter package, written from the Tcl/Tk manual pages, the existing documentation and the module docstrings. * Doc/library/tkinter.rst gains a "Reference" section documenting every public class, method, function and constant of the core module -- the widgets, the Misc, Wm, Pack, Place, Grid, XView and YView mix-ins, the Variable and image classes, the module-level functions and the symbolic constants. * Doc/library/tkinter.ttk.rst, dialog.rst, tkinter.font.rst and the other module pages document their remaining classes, methods and functions. The descriptions are Python-oriented (correct return types -- tuples rather than Tcl lists, booleans, integers, None on cancellation, and so on) and were checked against the Tcl/Tk 9.1 manual pages and the implementation. versionadded, versionchanged and deprecated directives are added for the public API, determined from the git history relative to Python 3.0: the tkinter.ttk module (3.1); the Text, Wm, Menu and Misc methods exposing Tk 8.5 features (3.3); and the many later additions and behavior changes up to 3.15. The Tk version required by features added after Tk 8.6 is noted as well. The bundled Tcl/Tk version is updated to 9.0 and the manual-page links point at the tcl9.0 reference. -------- (cherry picked from commit 8b270b7) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

serhiy-storchaka added docs Documentation in the Doc dir needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Jun 17, 2026

github-project-automation Bot moved this to Todo in Docs PRs Jun 17, 2026

github-project-automation Bot added this to Docs PRs Jun 17, 2026

bedevere-app Bot added the awaiting core review label Jun 17, 2026

bedevere-app Bot mentioned this pull request Jun 17, 2026

Tkinter extention modules have no documentation #59551

Open

serhiy-storchaka and others added 9 commits June 17, 2026 10:11

pythongh-59551: Remove docs for internal ttk helpers

2935f81

Undocument the tclobjs_to_py() and setup_master() utility functions, which are internal helpers rather than public API. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

serhiy-storchaka requested review from AA-Turner, StanFromIreland and hugovk as code owners June 17, 2026 13:13

serhiy-storchaka and others added 2 commits June 17, 2026 16:31

pythongh-86726: Correct the issue number of the tkinter docs NEWS entry

1a8e499

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

serhiy-storchaka changed the title ~~gh-59551: Document the full public API of tkinter~~ gh-86726: Document the full public API of tkinter Jun 17, 2026

bedevere-app Bot mentioned this pull request Jun 17, 2026

Improve Tkinter Documentation #86726

Open

hugovk reviewed Jun 18, 2026

View reviewed changes

serhiy-storchaka and others added 2 commits June 18, 2026 10:56

Apply suggestions from code review

ab6edbd

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

pythongh-59551: Spell out e.g. and i.e. in the tkinter documentation

3074205

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

pythongh-59551: Document grid_anchor only as a Misc method

1bd252f

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

serhiy-storchaka commented Jun 18, 2026

View reviewed changes

pythongh-59551: Use sentence case for section headings in the tkinter…

774052b

… documentation Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

hugovk reviewed Jun 18, 2026

View reviewed changes

Comment thread Doc/library/dialog.rst Outdated

Comment thread Doc/library/dialog.rst Outdated

Comment thread Doc/library/tkinter.scrolledtext.rst Outdated

Apply suggestions from code review

01fcf71

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

hugovk approved these changes Jun 18, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Jun 18, 2026

serhiy-storchaka and others added 2 commits June 18, 2026 15:15

pythongh-59551: Document the supported options of tkinter widgets and…

3417306

… their Tk versions Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Merge branch 'tk-docs' of github.com:serhiy-storchaka/cpython into tk…

414cadf

…-docs

serhiy-storchaka merged commit 8b270b7 into python:main Jun 18, 2026
30 checks passed

github-project-automation Bot moved this from Todo to Done in Docs PRs Jun 18, 2026

bedevere-app Bot removed the awaiting merge label Jun 18, 2026

serhiy-storchaka deleted the tk-docs branch June 18, 2026 12:39

bedevere-app Bot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jun 18, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Jun 18, 2026

Uh oh!

Conversation

serhiy-storchaka commented Jun 17, 2026 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

StanFromIreland commented Jun 17, 2026

Uh oh!

serhiy-storchaka commented Jun 17, 2026

Uh oh!

hugovk Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

serhiy-storchaka Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

miss-islington-app Bot commented Jun 18, 2026

Uh oh!

bedevere-app Bot commented Jun 18, 2026

Uh oh!

bedevere-app Bot commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

serhiy-storchaka commented Jun 17, 2026 •

edited by bedevere-app Bot

Loading

read-the-docs-community Bot commented Jun 17, 2026 •

edited

Loading