Merge branch 'main' into list-int-compact-guard-main

Author: KRRT7

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/asyncio-tools.rst

@@ -24,7 +24,7 @@ The following commands inspect the process identified by ``PID``:
 
 The commands read the target process state without executing any code in it.
 They are only available on supported platforms and may require permission to
-inspect another process.  See the :ref:`permission-requirements <permission-requirements>` for details.
+inspect another process.  See the :ref:`permission requirements <permission-requirements>` for details.
 
 .. seealso::
 

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/imaplib.rst

@@ -610,6 +610,13 @@ An :class:`IMAP4` instance has the following methods:
    If *uid* is true, the message numbers in the response are UIDs
    (``UID SEARCH``).
 
+   A criterion passed as :class:`str` is encoded to *charset*
+   (which must name a codec known to Python);
+   pass :class:`bytes` to send a criterion that is already encoded,
+   for example when *charset* is one that Python does not support.
+   When *charset* is ``None`` (as it must be under ``UTF8=ACCEPT``),
+   the criterion is sent using the connection's encoding instead.
+
    Example::
 
       # M is a connected IMAP4 instance...
@@ -621,6 +628,9 @@ An :class:`IMAP4` instance has the following methods:
    .. versionchanged:: next
       Added the *uid* parameter.
 
+   .. versionchanged:: next
+      ``str`` search criteria are encoded to *charset*.
+
 
 .. method:: IMAP4.select(mailbox='INBOX', readonly=False)
 
@@ -682,11 +692,18 @@ An :class:`IMAP4` instance has the following methods:
 
    If *uid* is true, the message numbers in the response are UIDs (``UID SORT``).
 
+   As with :meth:`search`,
+   a *search_criterion* passed as :class:`str` is encoded to *charset*;
+   pass :class:`bytes` to send one already encoded.
+
    This is an ``IMAP4rev1`` extension command.
 
    .. versionchanged:: next
       Added the *uid* parameter.
 
+   .. versionchanged:: next
+      ``str`` search criteria are encoded to *charset*.
+
 
 .. method:: IMAP4.starttls(ssl_context=None)
 
@@ -772,11 +789,18 @@ An :class:`IMAP4` instance has the following methods:
    If *uid* is true, the message numbers in the response are UIDs
    (``UID THREAD``).
 
+   As with :meth:`search`,
+   a *search_criterion* passed as :class:`str` is encoded to *charset*;
+   pass :class:`bytes` to send one already encoded.
+
    This is an ``IMAP4rev1`` extension command.
 
    .. versionchanged:: next
       Added the *uid* parameter.
 
+   .. versionchanged:: next
+      ``str`` search criteria are encoded to *charset*.
+
 
 .. method:: IMAP4.uid(command, arg[, ...])
 

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