gh-153550: Modernize the older prose sections of the tkinter documentation by serhiy-storchaka · Pull Request #153647 · python/cpython

serhiy-storchaka · 2026-07-13T07:33:57Z

Follow-up of gh-86726, closing gh-153550.

The tkinter reference sections were overhauled in gh-86726 and #153549, but the narrative prose preceding them — Tkinter life preserver and Handy reference in Doc/library/tkinter.rst, plus the tkinter.ttk front matter — still read like a late-1990s tutorial. This is an editorial pass to match. No API changes.

tkinter.rst

Replace The packer with a general Geometry management section covering grid, pack and place, with an example and use case for each, grid as the default, and a warning against mixing pack and grid in one container.
Rework The window manager and Coupling widget variables: modern Tk()/ttk examples instead of the dated App(Frame) idiom, and correct explanations (e.g. a widget links to a Variable because Python can't notify Tk when a plain variable is reassigned).
Drop the Ousterhout page-number citations for the relevant Tk man pages; reconcile the Packer options and Tk option data types lists with the reference; fill in the empty Entry-index list; point classic examples at the ttk widgets.

tkinter.ttk.rst

Lead the intro with the native-theme benefit; fix the TIP 48 link; recommend the explicit from tkinter import ttk form; refresh the theme-engine links (ttk::intro + the illustrated Tile Widget Set paper); add cross-references to tkinter.rst.

tkinter.dnd.rst

Fix the malformed target-selection list and mark up source/event as parameters.

Docs-only; no Misc/NEWS.d entry.

Issue: Modernize the older prose sections of the tkinter documentation #153550

@6

…cumentation Refresh the narrative "Tkinter life preserver" and "Handy reference" sections to match the overhauled reference (pythongh-86726 and pythongh-153549). * Rework "The packer" into a general "Geometry management" section that covers grid, pack and place, with a short example and use case for each, presents grid as the flexible default, and warns against mixing pack and grid in one container. Add symmetric cross-links between the Grid, Pack and Place reference classes and this section. * Rework "The window manager": explain what the window manager is, state that the Wm mixin is inherited by Tk and Toplevel so its methods are called directly on a top-level window, and replace the dated App(Frame) example (which reached the window through master) with a direct Tk() example. Drop the private _root() aside and cross-link the section and the Wm reference class to each other. * Rework "Coupling widget variables": explain that a widget links to a Variable object rather than a plain Python variable because Python cannot notify Tk when a variable is reassigned, and replace the dated App(Frame) example (whose entry was attached to the wrong parent) with a direct ttk example showing both get() and set(). * Remove the page-number citations to Ousterhout's book and point to the relevant Tk man pages instead. * Refresh the Tcl/Tk links in tkinter.ttk: add the official ttk::intro man page as the current explanation of the theme engine, keep Joe English's illustrated 2004 "Tile Widget Set" paper for its element and layout diagrams, and drop the now-redundant conversion monograph. * Modernize the tkinter.ttk front matter: lead the introduction with the native-theme benefit instead of peripheral features, update the TIP 48 link to its canonical URL, and add a note recommending the explicit "from tkinter import ttk" form over the star-import override. * Add cross-references between the two documents: point the tkinter.ttk introduction at the shared concepts documented for tkinter, and link the themed-widgets note in the tkinter introduction to tkinter.ttk. * Reconcile the "Packer options" and "Tk option data types" lists with the reference: replace the incomplete packer list with a cross-link to Pack.pack_configure, and frame the data-types list as the shared value types the reference refers to. * Fill in the empty Entry index list under "The index parameter", and describe "@6" as a string rather than an integer. * Point the classic base-widget examples at the themed ttk widgets. * Fix the malformed target-selection list in tkinter.dnd: make it a single ordered list with the sub-steps nested under the search step, and mark up "source" and "event" as parameters. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

read-the-docs-community · 2026-07-13T07:39:34Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #33593361 | 📁 Comparing a172023 against main (adebb68)

🔍 Preview build

11 files changed · ± 11 modified

±Modified

Renaming the "The packer" section to "Geometry management" and folding away the "Packer options" subsection removed their implicit HTML ids, breaking existing deep links. Restore both as explicit targets on the new section. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

terryjreedy

I mostly ignored sphinx formatting, focusing on content. Many chunks are improved. Only a few suggestions.

bedevere-app · 2026-07-15T04:45:56Z

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

…etry docs Address review comments: forward-reference the grid/pack warning from the geometry managers intro, and mention that frames and toplevels are containers too (toplevels being managed by the window manager). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

serhiy-storchaka · 2026-07-15T05:37:24Z

I have made the requested changes; please review again.

bedevere-app · 2026-07-15T05:37:29Z

Thanks for making the requested changes!

@terryjreedy: please review the changes made to this pull request.

serhiy-storchaka · 2026-07-15T05:38:50Z

I merged suggestions on my side because they needed re-wraping the lines.

miss-islington-app · 2026-07-15T16:19:04Z

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

bedevere-app · 2026-07-15T16:19:19Z

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

miss-islington-app · 2026-07-15T16:19:21Z

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 93beea7e5a3c5a03253e6812a06f2497505aeb30 3.13

bedevere-app · 2026-07-15T16:19:26Z

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

…ocumentation (GH-153647) (GH-153774) Refresh the narrative "Tkinter life preserver" and "Handy reference" sections to match the overhauled reference (gh-86726 and gh-153549). * Rework "The packer" into a general "Geometry management" section covering grid, pack and place, and cross-link it with the Grid, Pack and Place reference classes. * Rework "The window manager" and "Coupling widget variables", replacing the dated App(Frame) examples with direct Tk() and ttk examples. * Replace page-number citations to Ousterhout's book with links to the relevant Tk man pages. * Modernize the tkinter.ttk front matter and its Tcl/Tk links, and add cross-references between the two documents. * Reconcile the "Packer options" and "Tk option data types" lists with the reference, and fill in the empty Entry index list. * Fix the malformed target-selection list in tkinter.dnd. (cherry picked from commit 93beea7) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ocumentation (GH-153647) (GH-153773) Refresh the narrative "Tkinter life preserver" and "Handy reference" sections to match the overhauled reference (gh-86726 and gh-153549). * Rework "The packer" into a general "Geometry management" section covering grid, pack and place, and cross-link it with the Grid, Pack and Place reference classes. * Rework "The window manager" and "Coupling widget variables", replacing the dated App(Frame) examples with direct Tk() and ttk examples. * Replace page-number citations to Ousterhout's book with links to the relevant Tk man pages. * Modernize the tkinter.ttk front matter and its Tcl/Tk links, and add cross-references between the two documents. * Reconcile the "Packer options" and "Tk option data types" lists with the reference, and fill in the empty Entry index list. * Fix the malformed target-selection list in tkinter.dnd. (cherry picked from commit 93beea7) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

bedevere-app · 2026-07-15T16:44:40Z

GH-153775 is a backport of this pull request to the 3.13 branch.

…ocumentation (GH-153647) (GH-153775) Refresh the narrative "Tkinter life preserver" and "Handy reference" sections to match the overhauled reference (gh-86726 and gh-153549). * Rework "The packer" into a general "Geometry management" section covering grid, pack and place, and cross-link it with the Grid, Pack and Place reference classes. * Rework "The window manager" and "Coupling widget variables", replacing the dated App(Frame) examples with direct Tk() and ttk examples. * Replace page-number citations to Ousterhout's book with links to the relevant Tk man pages. * Modernize the tkinter.ttk front matter and its Tcl/Tk links, and add cross-references between the two documents. * Reconcile the "Packer options" and "Tk option data types" lists with the reference, and fill in the empty Entry index list. * Fix the malformed target-selection list in tkinter.dnd. (cherry picked from commit 93beea7)

bedevere-appBot added docs Documentation in the Doc dir skip news labels Jul 13, 2026

github-project-automationBot added this to Docs PRs Jul 13, 2026

github-project-automationBot moved this to Todo in Docs PRs Jul 13, 2026

bedevere-appBot mentioned this pull request Jul 13, 2026
Modernize the older prose sections of the tkinter documentation #153550
Closed
5 tasks

serhiy-storchaka marked this pull request as ready for review July 13, 2026 07:46

bedevere-appBot added the awaiting core review label Jul 13, 2026

serhiy-storchaka requested review from hugovk and terryjreedy July 13, 2026 07:48

serhiy-storchaka added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Jul 13, 2026

terryjreedy requested changes Jul 15, 2026
View reviewed changes

Comment threadDoc/library/tkinter.rst Outdated
Comment threadDoc/library/tkinter.rst
Comment threadDoc/library/tkinter.rst Outdated

bedevere-appBot removed the awaiting core review label Jul 15, 2026

bedevere-appBot added the awaiting changes label Jul 15, 2026

bedevere-appBot added awaiting change review and removed awaiting changes labels Jul 15, 2026

bedevere-appBot requested a review from terryjreedy July 15, 2026 05:37

terryjreedy approved these changes Jul 15, 2026
View reviewed changes

bedevere-appBot added awaiting merge and removed awaiting change review labels Jul 15, 2026

serhiy-storchaka merged commit 93beea7 into python:mainJul 15, 2026
35 of 38 checks passed

github-project-automationBot moved this from Todo to Done in Docs PRs Jul 15, 2026

bedevere-appBot removed the awaiting merge label Jul 15, 2026

serhiy-storchaka deleted the gh-153550-modernize-tkinter-prose branch July 15, 2026 16:19

bedevere-appBot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jul 15, 2026

miss-islington-appBot assigned serhiy-storchaka Jul 15, 2026

bedevere-appBot removed the needs backport to 3.14 bugs and security fixes label Jul 15, 2026

serhiy-storchaka removed their assignment Jul 15, 2026

serhiy-storchaka mentioned this pull request Jul 15, 2026
[3.13] gh-153550: Modernize the older prose sections of the tkinter documentation (GH-153647) #153775
Merged

bedevere-appBot removed the needs backport to 3.13 bugs and security fixes label Jul 15, 2026

serhiy-storchaka mentioned this pull request Jul 15, 2026
gh-153550: Remove out-of-date page-number citations from tkinter docs #153642
Closed

Uh oh!

Uh oh!

Conversation

serhiy-storchaka commented Jul 13, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-communityBot commented Jul 13, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

terryjreedy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bedevere-appBot commented Jul 15, 2026

Uh oh!

serhiy-storchaka commented Jul 15, 2026

Uh oh!

bedevere-appBot commented Jul 15, 2026

Uh oh!

serhiy-storchaka commented Jul 15, 2026

Uh oh!

Uh oh!

miss-islington-appBot commented Jul 15, 2026

Uh oh!

bedevere-appBot commented Jul 15, 2026

Uh oh!

miss-islington-appBot commented Jul 15, 2026

Uh oh!

bedevere-appBot commented Jul 15, 2026

Uh oh!

bedevere-appBot commented Jul 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

serhiy-storchaka commented Jul 13, 2026•
edited
Loading

read-the-docs-communityBot commented Jul 13, 2026•
edited
Loading