Merge branch 'main' into gh-130110-email-hyphen-param

Author: Phantom-d-e-v

Doc/deprecations/pending-removal-in-3.19.rst

@@ -40,3 +40,11 @@ Pending removal in Python 3.19
     Before Python 3.14, this property was used to implement the corresponding
     ``read()`` and ``readline()`` methods for :class:`~imaplib.IMAP4` but this
     is no longer the case since then.
+
+* :mod:`tkinter`:
+
+  * :func:`tkinter.filedialog.askopenfiles` has been deprecated since Python
+    3.16.  Iterate over the names returned by
+    :func:`~tkinter.filedialog.askopenfilenames` and open them one by one
+    instead.
+    (Contributed by Serhiy Storchaka in :gh:`152638`.)

Doc/library/asyncio-queue.rst

@@ -71,6 +71,8 @@ Queue
       Return an item if one is immediately available, else raise
       :exc:`QueueEmpty`.
 
+      Raises :exc:`QueueShutDown` if the queue has been shut down and is empty.
+
    .. method:: join()
       :async:
 
@@ -96,6 +98,8 @@ Queue
 
       If no free slot is immediately available, raise :exc:`QueueFull`.
 
+      Raises :exc:`QueueShutDown` if the queue has been shut down.
+
    .. method:: qsize()
 
       Return the number of items in the queue.
@@ -188,8 +192,9 @@ Exceptions
 
 .. exception:: QueueShutDown
 
-   Exception raised when :meth:`~Queue.put` or :meth:`~Queue.get` is
-   called on a queue which has been shut down.
+   Exception raised when :meth:`~Queue.put`, :meth:`~Queue.put_nowait`,
+   :meth:`~Queue.get` or :meth:`~Queue.get_nowait` is called
+   on a queue which has been shut down.
 
    .. versionadded:: 3.13
 

Doc/library/dialog.rst

@@ -163,15 +163,23 @@ cancelled it is the empty value documented for that function -- an empty
 string, an empty tuple, an empty list or ``None``.
 
 .. function:: askopenfile(mode="r", **options)
-              askopenfiles(mode="r", **options)
 
-   Create an :class:`Open` dialog.
-   :func:`askopenfile` returns the opened file object, or ``None`` if the
-   dialog is cancelled.
-   :func:`askopenfiles` returns a list of the opened file objects, or an empty
-   list if cancelled.
+   Create an :class:`Open` dialog and return the opened file object,
+   or ``None`` if the dialog is cancelled.
+   The file is opened in mode *mode* (read-only ``'r'`` by default).
+
+.. function:: askopenfiles(mode="r", **options)
+
+   Create an :class:`Open` dialog and return a list of the opened file objects,
+   or an empty list if cancelled.
    The files are opened in mode *mode* (read-only ``'r'`` by default).
 
+   .. deprecated-removed:: next 3.19
+      Opening several files at once is error-prone,
+      and the returned list cannot be used in a :keyword:`with` statement.
+      Iterate over the names returned by :func:`askopenfilenames`
+      and open them one by one instead.
+
 .. function:: asksaveasfile(mode="w", **options)
 
    Create a :class:`SaveAs` dialog and return the opened file object, or
@@ -201,19 +209,16 @@ string, an empty tuple, an empty list or ``None``.
 
 .. class:: Open(master=None, **options)
            SaveAs(master=None, **options)
+           Directory(master=None, **options)
 
-   The above two classes provide native dialog windows for saving and loading
-   files.
+   The above three classes provide native dialog windows for loading and saving
+   files and for selecting a directory.
 
 **Convenience classes**
 
 The below classes are used for creating file/directory windows from scratch.
 These do not emulate the native look-and-feel of the platform.
 
-.. class:: Directory(master=None, **options)
-
-   Create a dialog prompting the user to select a directory.
-
 .. note::  The *FileDialog* class should be subclassed for custom event
    handling and behaviour.
 
@@ -353,23 +358,25 @@ the classic (non-themed) Tk widgets.
 
 .. data:: DIALOG_ICON
 
-   The name of the default bitmap (``'questhead'``) displayed by a
-   :class:`Dialog`.
+   The name of a bitmap (``'questhead'``) suitable for use as the *bitmap*
+   of a :class:`Dialog`.
 
 .. class:: Dialog(master=None, cnf={}, **kw)
 
    Display a modal dialog box built from the classic (non-themed) Tk widgets
    and wait for the user to press one of its buttons.
-   The options, given through *cnf* or as keyword arguments, include *title*
-   (the window title), *text* (the message), *bitmap* (an icon,
-   :data:`DIALOG_ICON` by default), *default* (the index of the default button)
-   and *strings* (the sequence of button labels).
+   The options, given through *cnf* or as keyword arguments, are all required:
+   *title* (the window title), *text* (the message), *bitmap* (the name of a
+   bitmap icon, such as :data:`DIALOG_ICON`), *default* (the index of the
+   default button) and *strings* (the sequence of button labels).
    After construction, the :attr:`!num` attribute holds the index of the button
    the user pressed.
 
    .. method:: destroy()
 
-      Destroy the dialog window.
+      Do nothing.
+      The dialog window is destroyed automatically before the constructor
+      returns, so there is nothing left for this method to do.
 
 
 .. seealso::

Doc/library/tk.rst

@@ -33,9 +33,11 @@ alternative `GUI frameworks and tools <https://wiki.python.org/moin/GuiProgrammi
    tkinter.rst
    tkinter.colorchooser.rst
    tkinter.font.rst
+   tkinter.fontchooser.rst
    dialog.rst
    tkinter.messagebox.rst
    tkinter.scrolledtext.rst
+   tkinter.systray.rst
    tkinter.dnd.rst
    tkinter.ttk.rst
    idle.rst

Doc/library/tkinter.fontchooser.rst

@@ -0,0 +1,90 @@
+:mod:`!tkinter.fontchooser` --- Font selection dialog
+=====================================================
+
+.. module:: tkinter.fontchooser
+   :synopsis: Font selection dialog
+
+.. versionadded:: next
+
+**Source code:** :source:`Lib/tkinter/fontchooser.py`
+
+--------------
+
+The :mod:`!tkinter.fontchooser` module provides the :class:`FontChooser` class
+as an interface to the native font selection dialog.
+
+The font dialog is application-global:
+there is a single font dialog per Tcl interpreter,
+and all :class:`FontChooser` instances configure the same dialog.
+
+Depending on the platform, the dialog may be modal or modeless,
+so :meth:`~FontChooser.show` may return immediately.
+The selected font is not returned:
+it is passed as a :class:`~tkinter.font.Font` object to the callback
+specified with the *command* option.
+
+The dialog also generates two virtual events on the parent window
+(see the *parent* option):
+
+``<<TkFontchooserVisibility>>``
+   Generated when the dialog is shown or hidden.
+   Query the *visible* option to tell which.
+
+``<<TkFontchooserFontChanged>>``
+   Generated when the selected font changes.
+
+.. note::
+
+   The *command* callback is the only reliable way to obtain the selected font.
+   On some platforms the *font* option is not updated to the user's choice.
+
+.. class:: FontChooser(master=None, **options)
+
+   The class implementing the font selection dialog.
+
+   *master* is the widget whose Tcl interpreter owns the dialog.
+   If omitted, it defaults to *parent* if that is given,
+   or to the default root window otherwise.
+
+   The supported configuration options are:
+
+   * *parent* --- the window to which the dialog and its virtual events are related.
+     It defaults to the main window;
+     on macOS the dialog is shown as a sheet attached to it,
+     rather than as a free-standing panel.
+   * *title* --- the title of the dialog.
+   * *font* --- the font that is currently selected in the dialog.
+   * *command* --- a callback that is called
+     with a :class:`~tkinter.font.Font` object wrapping the selected font
+     when the user selects a font.
+   * *visible* --- whether the dialog is currently displayed (read-only).
+
+   The *font* option accepts the forms supported by :class:`tkinter.font.Font`.
+
+   .. method:: configure(**options)
+               config(**options)
+
+      Query or modify the options of the font dialog.
+      With no arguments, return a dict of all option values.
+      With a string argument, return the value of that option.
+      Otherwise, set the given options.
+
+   .. method:: cget(option)
+
+      Return the value of the given option of the font dialog.
+
+   .. method:: show()
+
+      Display the font dialog.
+      Depending on the platform, this method may return immediately
+      or only once the dialog has been withdrawn.
+
+   .. method:: hide()
+
+      Hide the font dialog if it is displayed.
+
+
+.. seealso::
+
+   Module :mod:`tkinter.font`
+      Tkinter font-handling utilities

Doc/library/tkinter.messagebox.rst

@@ -13,9 +13,7 @@ a variety of convenience methods for commonly used configurations.
 The message boxes are modal: each blocks until the user responds, then returns
 a value that depends on the function.
 The ``show*`` functions and :meth:`Message.show` return the symbolic name of
-the button the user pressed, as a string (such as :data:`OK` or :data:`YES`),
-while the ``ask*`` functions return a :class:`bool` or ``None`` (see each
-function below).
+the button the user pressed, as a string (such as :data:`OK` or :data:`YES`).
 Common message box styles and layouts include but are not limited to:
 
 .. figure:: tk_msg.png

Doc/library/tkinter.rst

@@ -146,6 +146,9 @@ The modules that provide Tk support include:
 :mod:`tkinter.font`
    Utilities to help work with fonts.
 
+:mod:`tkinter.fontchooser`
+   Dialog to let the user choose a font.
+
 :mod:`tkinter.messagebox`
    Access to standard Tk dialog boxes.
 
@@ -155,6 +158,9 @@ The modules that provide Tk support include:
 :mod:`tkinter.simpledialog`
    Basic dialogs and convenience functions.
 
+:mod:`tkinter.systray`
+   System tray icon and desktop notifications.
+
 :mod:`tkinter.ttk`
    Themed widget set introduced in Tk 8.5, providing modern alternatives
    for many of the classic widgets in the main :mod:`!tkinter` module.
@@ -539,11 +545,8 @@ arguments, or by calling the :meth:`~Misc.keys` method on that widget.
 The return value of these calls is a dictionary whose key is the name of the
 option as a string (for example, ``'relief'``) and whose values are 5-tuples.
 
-Some options, like ``bg`` are synonyms for common options with long names
-(``bg`` is shorthand for "background"). Passing the ``config()`` method the name
-of a shorthand option will return a 2-tuple, not 5-tuple. The 2-tuple passed
-back will contain the name of the synonym and the "real" option (such as
-``('bg', 'background')``).
+Some options, like ``bg``, are synonyms for common options with long names
+(``bg`` is shorthand for "background").
 
 +-------+---------------------------------+--------------+
 | Index | Meaning                         | Example      |
@@ -2353,8 +2356,8 @@ Base and mixin classes
       If all four arguments are given, the window manager keeps the ratio
       between ``minNumer/minDenom`` and ``maxNumer/maxDenom``; passing empty
       strings removes any existing restriction.
-      With no arguments, return a tuple of the four current values, or an empty
-      string if no aspect restriction is in effect.
+      With no arguments, return a tuple of the four current values, or ``None``
+      if no aspect restriction is in effect.
       :meth:`wm_aspect` is an alias of :meth:`!aspect`.
 
    .. method:: wm_attributes(*args, return_python_dict=False, **kwargs)
@@ -2579,8 +2582,8 @@ Base and mixin classes
       window's internally requested size, and *widthInc* and *heightInc* are
       the pixel sizes of a horizontal and vertical grid unit.
       Empty strings turn off gridded management.
-      With no arguments, return a tuple of the four current values, or an empty
-      string if the window is not gridded.
+      With no arguments, return a tuple of the four current values, or ``None``
+      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`.
@@ -2693,8 +2696,8 @@ Base and mixin classes
       Set or query a hint to the window manager about where the window's icon
       should be positioned.
       Empty strings cancel an existing hint.
-      With no arguments, return a tuple of the two current values, or an empty
-      string if no hint is in effect.
+      With no arguments, return a tuple of the two current values, or ``None``
+      if no hint is in effect.
       :meth:`wm_iconposition` is an alias of :meth:`!iconposition`.
 
    .. method:: wm_iconwindow(pathName=None)
@@ -2763,7 +2766,8 @@ Base and mixin classes
       When this flag is set, the window is ignored by the window manager: it is
       not reparented into a decorative frame and the user cannot manipulate it
       through the usual window manager controls.
-      With no argument, return a boolean indicating whether the flag is set.
+      With no argument, return a boolean indicating whether the flag is set,
+      or ``None`` if it has not been set.
       The flag is reliably honored only when the window is first mapped or
       remapped from the withdrawn state.
       :meth:`wm_overrideredirect` is an alias of :meth:`!overrideredirect`.
@@ -3555,6 +3559,13 @@ Widget classes
    A newly created item is placed at the top of the list; the order can be
    changed with :meth:`tag_raise` and :meth:`tag_lower`.
 
+   .. method:: tk_print()
+
+      Print the contents of the canvas using the native print dialog.
+      Requires Tk 8.7/9.0 or newer.
+
+      .. versionadded:: next
+
    .. method:: create_arc(*args, **kw)
                create_bitmap(*args, **kw)
                create_image(*args, **kw)
@@ -4925,13 +4936,13 @@ Widget classes
       containing *child*.
       *option* may be any value allowed by :meth:`paneconfigure`.
 
-   .. method:: paneconfig(tagOrId, cnf=None, **kw)
+   .. method:: paneconfig(child, cnf=None, **kw)
       :no-typesetting:
 
-   .. method:: paneconfigure(tagOrId, cnf=None, **kw)
+   .. method:: paneconfigure(child, cnf=None, **kw)
 
       Query or modify the management options of the pane containing the widget
-      *tagOrId*.
+      *child*.
       With no options, it returns a dictionary describing all of the available
       options for the pane; given a single option name as a string, it returns
       a description of that one option; otherwise it sets the given options.
@@ -4946,6 +4957,10 @@ Widget classes
       ``'always'``, ``'first'``, ``'last'``, ``'middle'`` or ``'never'``).
       :meth:`paneconfig` is an alias of :meth:`!paneconfigure`.
 
+      .. deprecated-removed:: next 3.18
+         The first parameter was renamed from *tagOrId* to *child*.
+         The old name is still accepted as a keyword argument.
+
    .. method:: identify(x, y)
 
       Identify the panedwindow component underneath the point given by *x* and
@@ -5366,6 +5381,13 @@ Widget classes
    to its base; several modifiers may be combined and are applied from left to
    right, for example ``'insert wordstart - 1 c'``.
 
+   .. method:: tk_print()
+
+      Print the contents of the text widget using the native print dialog.
+      Requires Tk 8.7/9.0 or newer.
+
+      .. versionadded:: next
+
    .. method:: insert(index, chars, *args)
 
       Insert the string *chars* just before the character at *index* (if