Merge branch 'main' into clear_NameError_suggestion

Author: Locked-chess-official

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/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

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.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      |
@@ -3555,6 +3558,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 +4935,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 +4956,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 +5380,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

Doc/library/tkinter.systray.rst

@@ -0,0 +1,72 @@
+:mod:`!tkinter.systray` --- System tray icon and notifications
+==============================================================
+
+.. module:: tkinter.systray
+   :synopsis: System tray icon and desktop notifications
+
+**Source code:** :source:`Lib/tkinter/systray.py`
+
+.. versionadded:: next
+
+--------------
+
+The :mod:`!tkinter.systray` module provides the :class:`SysTrayIcon` class
+as an interface to the system tray (or taskbar) icon,
+and the :func:`notify` function which sends a desktop notification.
+They require Tk 8.7/9.0 or newer.
+
+Only one system tray icon is supported per Tcl interpreter.
+
+.. class:: SysTrayIcon(master=None, *, exists=False, **options)
+
+   The class implementing the system tray icon.
+
+   With *exists* false (the default), a new icon is created;
+   creating a second one raises :exc:`~tkinter.TclError`.
+   With *exists* true, the instance refers to the already-existing icon
+   instead of creating one, reconfiguring it with any given options.
+
+   The supported configuration options are:
+
+   * *image* --- the image displayed in the system tray
+     (required when creating an icon).
+     On Windows, it must be a :class:`!PhotoImage`.
+   * *text* --- the text displayed in the tooltip of the icon.
+   * *button1* --- a callback that is called without arguments
+     when the icon is clicked with the left mouse button.
+   * *button3* --- a callback that is called without arguments
+     when the icon is clicked with the right mouse button.
+
+   .. method:: configure(**options)
+               config(**options)
+
+      Query or modify the options of the system tray icon.
+      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 system tray icon.
+
+   .. method:: exists()
+
+      Return whether the system tray icon exists.
+
+   .. method:: destroy()
+
+      Destroy the system tray icon.
+      A new icon can be created afterwards.
+
+   .. method:: notify(title, message)
+
+      Send a desktop notification with the given title and message.
+
+
+.. function:: notify(title, message, *, master=None)
+
+   Send a desktop notification with the given title and message
+   without creating a system tray icon first.
+   On Windows, sending a notification requires an existing system
+   tray icon, which is also displayed in the notification;
+   use the :meth:`SysTrayIcon.notify` method instead.

Doc/whatsnew/3.16.rst

@@ -406,6 +406,11 @@ tkinter
   report the user idle time.
   (Contributed by Serhiy Storchaka in :gh:`151881`.)
 
+* Added the :meth:`!tk_print` method to :class:`tkinter.Canvas` and
+  :class:`tkinter.Text` which prints the contents of the widget using the
+  native print dialog.  It requires Tk 8.7/9.0 or newer.
+  (Contributed by Serhiy Storchaka in :gh:`153256`.)
+
 * Added new window-management methods :meth:`~tkinter.Misc.winfo_isdark`
   (dark mode detection), :meth:`~tkinter.Wm.wm_iconbadge` (application icon
   badge) and :meth:`~tkinter.Wm.wm_stackorder` (toplevel stacking order).
@@ -456,6 +461,12 @@ tkinter
   them.
   (Contributed by Serhiy Storchaka in :gh:`59396`.)
 
+* Added the :mod:`tkinter.systray` module which provides the
+  :class:`~tkinter.systray.SysTrayIcon` class as an interface to the system
+  tray icon and the :func:`~tkinter.systray.notify` function which sends a
+  desktop notification.  They require Tk 8.7/9.0 or newer.
+  (Contributed by Serhiy Storchaka in :gh:`153259`.)
+
 * :class:`tkinter.scrolledtext.ScrolledText` gained a *use_ttk* parameter to use
   the themed :mod:`tkinter.ttk` frame and scroll bar instead of the classic
   :mod:`tkinter` widgets.
@@ -467,6 +478,11 @@ tkinter
   :meth:`~tkinter.font.Font.measure` and :meth:`~tkinter.font.Font.metrics`.
   (Contributed by Serhiy Storchaka in :gh:`143990`.)
 
+* Added the :mod:`tkinter.fontchooser` module which provides the
+  :class:`~tkinter.fontchooser.FontChooser` class as an interface to the
+  native font selection dialog.
+  (Contributed by Serhiy Storchaka in :gh:`72880`.)
+
 * Values of several Tcl object types returned by :mod:`tkinter` are now
   converted to the corresponding Python type instead of being wrapped in a
   :class:`!_tkinter.Tcl_Obj`: ``index``, ``window``, ``nsName`` and
@@ -655,6 +671,15 @@ New deprecations
     Use the new public :class:`tempfile.TemporaryFileWrapper` instead,
     which is the return type of :func:`tempfile.NamedTemporaryFile`.
 
+* :mod:`tkinter`:
+
+  * :func:`tkinter.filedialog.askopenfiles` is deprecated and slated for
+    removal in Python 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:`~tkinter.filedialog.askopenfilenames` and
+    open them one by one instead.
+    (Contributed by Serhiy Storchaka in :gh:`152638`.)
+
 .. Add deprecations above alphabetically, not here at the end.
 
 .. include:: ../deprecations/pending-removal-in-3.17.rst

Lib/test/test_asyncio/test_base_events.py

@@ -1092,7 +1092,11 @@ async def sock_connect(sock, address):
                 await asyncio.sleep(1)
             sock.connect(address)
 
-        loop = asyncio.new_event_loop()
+        # gh-151540: use a selector event loop instead of the platform
+        # default; the Windows proactor loop would register the mocked
+        # socket with a real IOCP handle instead of the mocked
+        # _add_reader/_add_writer below.
+        loop = asyncio.SelectorEventLoop()
         loop._add_writer = mock.Mock()
         loop._add_writer = mock.Mock()
         loop._add_reader = mock.Mock()
@@ -1124,7 +1128,8 @@ async def sock_connect(sock, address):
                 await asyncio.sleep(1)
             sock.connect(address)
 
-        loop = asyncio.new_event_loop()
+        # gh-151540: see test_create_connection_happy_eyeballs above.
+        loop = asyncio.SelectorEventLoop()
         loop._add_writer = mock.Mock()
         loop._add_writer = mock.Mock()
         loop._add_reader = mock.Mock()

Lib/test/test_tkinter/test_filedialog.py

@@ -203,5 +203,13 @@ def test_type_ahead(self):
         self.assertEqual([d.files.get(i) for i in sel], ['charlie'])
 
 
+class DeprecationTest(unittest.TestCase):
+
+    def test_askopenfiles_deprecated(self):
+        with swap_attr(filedialog, 'askopenfilenames', lambda **kw: ()):
+            with self.assertWarns(DeprecationWarning):
+                filedialog.askopenfiles()
+
+
 if __name__ == "__main__":
     unittest.main()