From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sun, 21 Jun 2026 15:10:43 +0000 (+0200)
Subject: [3.15] gh-86726: Document tkinter.simpledialog query options and Dialog.result (GH... 
X-Git-Tag: v3.15.0b3~14
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=aa83ca3ec884d37a03910e76242d80ae045c80e3;p=thirdparty%2FPython%2Fcpython.git

[3.15] gh-86726: Document tkinter.simpledialog query options and Dialog.result (GH-151851) (GH-151852)

(cherry picked from commit 8270ae560c632f2ee88ab6c6b33562227d0deaae)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
---

diff --git a/Doc/library/dialog.rst b/Doc/library/dialog.rst
index 952fd1f07836..402cfcfe7536 100644
--- a/Doc/library/dialog.rst
+++ b/Doc/library/dialog.rst
@@ -15,16 +15,31 @@ The :mod:`!tkinter.simpledialog` module contains convenience classes and
 functions for creating simple modal dialogs to get a value from the user.
 
 
-.. function:: askfloat(title, prompt, **kw)
-              askinteger(title, prompt, **kw)
-              askstring(title, prompt, **kw)
+.. function:: askfloat(title, prompt, *, initialvalue=None, minvalue=None, maxvalue=None, parent=None)
+              askinteger(title, prompt, *, initialvalue=None, minvalue=None, maxvalue=None, parent=None)
+              askstring(title, prompt, *, initialvalue=None, show=None, parent=None)
 
-   The above three functions provide dialogs that prompt the user to enter a value
-   of the desired type.
+   Prompt the user to enter a value of the desired type and return it, or
+   ``None`` if the dialog is cancelled.
+
+   *title* is the dialog title and *prompt* the message shown above the entry.
+   *initialvalue* is the value initially placed in the entry.
+   *parent* is the window over which the dialog is shown.
+   :func:`askinteger` and :func:`askfloat` also accept *minvalue* and
+   *maxvalue*, which bound the accepted value.
+   :func:`askstring` also accepts *show*, a character used to mask the entered
+   text, for example ``'*'`` to hide a password.
 
 .. class:: Dialog(parent, title=None)
 
    The base class for custom dialogs.
+   Instantiating it shows the dialog modally and returns once the user closes
+   it; the entered value is then available in the :attr:`!result` attribute.
+
+   .. attribute:: result
+
+      The value produced by :meth:`apply`, or ``None`` if the dialog was
+      cancelled.
 
    .. method:: body(master)
 
@@ -46,7 +61,8 @@ functions for creating simple modal dialogs to get a value from the user.
 
    .. method:: apply()
 
-      Process the data entered by the user.
+      Process the data entered by the user, for example by storing it in the
+      :attr:`!result` attribute.
       Called after :meth:`validate` succeeds and just before the dialog is
       destroyed.
       The default implementation does nothing; override it to act on or store