pushinmg

Author: palakkhinvasara

.github/workflows/reusable-san.yml

@@ -39,6 +39,8 @@ jobs:
       run: |
         sudo ./.github/workflows/posix-deps-apt.sh
         # On ubuntu-26.04 image, clang is clang-21 by default
+        # NOTE: when bumping to a new version of clang,
+        # please update the versions in `Tools/pixi-packages/variants.yaml` too.
         echo "CC=clang" >> "$GITHUB_ENV"
         echo "CXX=clang++" >> "$GITHUB_ENV"
     - name: TSan option setup

Doc/library/curses.ascii.rst

@@ -176,15 +176,18 @@ C library:
 
    Checks for a non-ASCII character (ordinal values 0x80 and above).
 
-These functions accept either integers or single-character strings; when the argument is a
-string, it is first converted using the built-in function :func:`ord`.
+These functions accept an integer, a single-character string, or a
+:class:`curses.complexchar`.
+A string is converted using the built-in function :func:`ord`, and a
+complexchar by the code of its single character; a complexchar that holds
+combining characters is not a single character and matches no class.
 
 Note that all these functions check ordinal bit values derived from the
 character of the string you pass in; they do not actually know anything about
 the host machine's character encoding.
 
-The following two functions take either a single-character string or integer
-byte value; they return a value of the same type.
+The following three functions take either a single-character string or an
+integer byte value; they return a value of the same type.
 
 
 .. function:: ascii(c)
@@ -194,16 +197,22 @@ byte value; they return a value of the same type.
 
 .. function:: ctrl(c)
 
-   Return the control character corresponding to the given character (the character
-   bit value is bitwise-anded with 0x1f).
+   Return the control character corresponding to the given ASCII character (the
+   character bit value is bitwise-anded with 0x1f).  A non-ASCII character has no
+   control character and is returned unchanged.
+
+   .. versionchanged:: next
+      A non-ASCII argument is now returned unchanged instead of masked to a
+      control character.
 
 
 .. function:: alt(c)
 
    Return the 8-bit character corresponding to the given ASCII character (the
    character bit value is bitwise-ored with 0x80).
 
-The following function takes either a single-character string or integer value;
+The following function takes a single-character string, an integer value, or a
+:class:`curses.complexchar`;
 it returns a string.
 
 

Doc/library/imaplib.rst

@@ -188,9 +188,10 @@ enclosed with either parentheses or double quotes) each string is quoted.
 However, the *password* argument to the ``LOGIN`` command is always quoted. If
 you want to avoid having an argument string quoted (eg: the *flags* argument to
 ``STORE``) then enclose the string in parentheses (eg: ``r'(\Deleted)'``).
-In general, pass arguments unquoted and let the module quote them as needed.
-An argument that is already enclosed in double quotes is left unchanged,
-so that code which quotes arguments itself keeps working.
+Or you can quote the string yourself;
+an argument that is already enclosed in double quotes is left unchanged.
+In general, however, it is better to pass arguments unquoted
+and let the module quote them as needed.
 
 Mailbox names are encoded as modified UTF-7 (:rfc:`3501`, section 5.1.3),
 so a mailbox name containing non-ASCII characters can be passed as an
@@ -211,11 +212,70 @@ or mandated results from the command. Each *data* is either a ``bytes``, or a
 tuple. If a tuple, then the first part is the header of the response, and the
 second part contains the data (ie: 'literal' value).
 
-The *message_set* options to commands below is a string specifying one or more
-messages to be acted upon.  It may be a simple message number (``'1'``), a range
-of message numbers (``'2:4'``), or a group of non-contiguous ranges separated by
-commas (``'1:3,6:9'``).  A range can contain an asterisk to indicate an infinite
-upper bound (``'3:*'``).
+The *message_set* options to the commands below can be a string specifying
+one or more messages to be acted upon.
+It may be a simple message number (``'1'``),
+a range of message numbers (``'2:4'``),
+or a group of non-contiguous ranges separated by commas (``'1:3,6:9'``).
+A range can contain an asterisk
+to indicate an infinite upper bound (``'3:*'``).
+
+Alternatively it can be specified using integers and :class:`range` objects.
+It may be a single message number or a sequence.
+The sequence items may be integers, ``(start, stop)`` tuples
+(where ``None`` or ``'*'`` stands for the last message),
+or :class:`range` objects.
+For example, ``[1, (3, 5), 8]`` and ``[range(1, 6), 8]``
+are both equivalent to ``'1,3:5,8'``.
+
+.. versionchanged:: next
+   Added support for the structured *message_set*.
+
+Command arguments that are parenthesized lists of atoms ---
+such as the *flag_list* argument of :meth:`~IMAP4.store` and the *flags*
+argument of :meth:`~IMAP4.append`,
+the *names* argument of :meth:`~IMAP4.status`,
+the *sort_criteria* argument of :meth:`~IMAP4.sort`,
+or the *message_parts* argument of :meth:`~IMAP4.fetch` ---
+can be passed as a sequence of strings instead of a single preformatted string.
+For example, ``[r'\Seen', r'\Answered']``
+is equivalent to ``(\Seen \Answered)``.
+
+.. versionchanged:: next
+   Added support for passing these arguments as a sequence.
+
+.. _imap4-params:
+
+The value-bearing arguments of the search and fetch commands
+can be quoted by hand, but this is error prone.
+Instead, they may contain ``?`` placeholders that are substituted, and quoted
+as required, from a *params* keyword argument,
+in the manner of :mod:`sqlite3` parameter substitution::
+
+   # SEARCH FROM me@example.com SUBJECT "trip report"
+   M.search(None, 'FROM ? SUBJECT ?', params=['me@example.com', 'trip report'])
+
+   # FETCH 1:5 (FLAGS BODY[HEADER.FIELDS (DATE FROM)])
+   M.fetch('1:5', 'FLAGS BODY[HEADER.FIELDS ?]', params=[['DATE', 'FROM']])
+
+The placeholders are:
+
+* ``?`` --- an ``astring``: a string (which will be quoted if necessary),
+  an integer, or a list of integers and/or strings
+  (which will be sent as a parenthesized list);
+* ``?f`` --- a flag or a list of flags, sent verbatim without quoting;
+* ``?s`` --- a *message_set* in the structured form described above.
+
+``??`` stands for a literal ``?``.
+
+Substitution is only performed when *params* is given;
+if no *params* are given, an argument containing a literal ``?`` is unchanged.
+The *params* keyword is accepted by :meth:`~IMAP4.search`,
+:meth:`~IMAP4.fetch`, :meth:`~IMAP4.sort`, :meth:`~IMAP4.thread` and
+:meth:`~IMAP4.uid`.
+
+.. versionadded:: next
+   The *params* keyword argument.
 
 An :class:`IMAP4` instance has the following methods:
 
@@ -324,7 +384,7 @@ An :class:`IMAP4` instance has the following methods:
       Added the *message_set* and *uid* parameters.
 
 
-.. method:: IMAP4.fetch(message_set, message_parts, *, uid=False)
+.. method:: IMAP4.fetch(message_set, message_parts, *, uid=False, params=None)
 
    Fetch (parts of) messages.  *message_parts* should be a string of message part
    names enclosed within parentheses, eg: ``"(UID BODY[TEXT])"``.  Returned data
@@ -333,8 +393,11 @@ An :class:`IMAP4` instance has the following methods:
    If *uid* is true, *message_set* is a set of UIDs and the message numbers in
    the response are UIDs (``UID FETCH``).
 
+   If *params* is given, ``?`` placeholders in *message_parts* are substituted
+   with the quoted parameters (see :ref:`the placeholders <imap4-params>`).
+
    .. versionchanged:: next
-      Added the *uid* parameter.
+      Added the *params* and *uid* parameters.
 
 
 .. method:: IMAP4.getacl(mailbox)
@@ -598,7 +661,7 @@ An :class:`IMAP4` instance has the following methods:
    code, instead of the usual type.
 
 
-.. method:: IMAP4.search(charset, criterion[, ...], *, uid=False)
+.. method:: IMAP4.search(charset, criterion[, ...], *, uid=False, params=None)
 
    Search mailbox for matching messages.  *charset* may be ``None``, in which case
    no ``CHARSET`` will be specified in the request to the server.  The IMAP
@@ -617,18 +680,22 @@ An :class:`IMAP4` instance has the following methods:
    When *charset* is ``None`` (as it must be under ``UTF8=ACCEPT``),
    the criterion is sent using the connection's encoding instead.
 
+   If *params* is given, ``?`` placeholders in the criteria are substituted
+   with the quoted parameters (see :ref:`the placeholders <imap4-params>`).
+
    Example::
 
       # M is a connected IMAP4 instance...
-      typ, msgnums = M.search(None, 'FROM', '"LDJ"')
+      typ, msgnums = M.search(None, 'FROM', '"John Smith"')
 
       # or:
-      typ, msgnums = M.search(None, '(FROM "LDJ")')
+      typ, msgnums = M.search(None, '(FROM "John Smith")')
 
-   .. versionchanged:: next
-      Added the *uid* parameter.
+      # or, letting the module quote the value (this is recommended):
+      typ, msgnums = M.search(None, 'FROM ?', params=['John Smith'])
 
    .. versionchanged:: next
+      Added the *params* and *uid* parameters.
       ``str`` search criteria are encoded to *charset*.
 
 
@@ -675,7 +742,7 @@ An :class:`IMAP4` instance has the following methods:
    Returns socket instance used to connect to server.
 
 
-.. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...], *, uid=False)
+.. method:: IMAP4.sort(sort_criteria, charset, search_criterion[, ...], *, uid=False, params=None)
 
    The ``sort`` command is a variant of ``search`` with sorting semantics for the
    results.  Returned data contains a space separated list of matching message
@@ -696,12 +763,13 @@ An :class:`IMAP4` instance has the following methods:
    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.
+   If *params* is given, ``?`` placeholders in the search criteria are
+   substituted with the quoted parameters (see :ref:`the placeholders <imap4-params>`).
 
-   .. versionchanged:: next
-      Added the *uid* parameter.
+   This is an ``IMAP4rev1`` extension command.
 
    .. versionchanged:: next
+      Added the *params* and *uid* parameters.
       ``str`` search criteria are encoded to *charset*.
 
 
@@ -745,7 +813,7 @@ An :class:`IMAP4` instance has the following methods:
 
       typ, data = M.search(None, 'ALL')
       for num in data[0].split():
-         M.store(num, '+FLAGS', '\\Deleted')
+         M.store(num, '+FLAGS', r'\Deleted')
       M.expunge()
 
    .. note::
@@ -768,7 +836,7 @@ An :class:`IMAP4` instance has the following methods:
    Subscribe to new mailbox.
 
 
-.. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...], *, uid=False)
+.. method:: IMAP4.thread(threading_algorithm, charset, search_criterion[, ...], *, uid=False, params=None)
 
    The ``thread`` command is a variant of ``search`` with threading semantics for
    the results.  Returned data contains a space separated list of thread members.
@@ -793,22 +861,30 @@ An :class:`IMAP4` instance has the following methods:
    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.
+   If *params* is given, ``?`` placeholders in the search criteria are
+   substituted with the quoted parameters (see :ref:`the placeholders <imap4-params>`).
 
-   .. versionchanged:: next
-      Added the *uid* parameter.
+   This is an ``IMAP4rev1`` extension command.
 
    .. versionchanged:: next
+      Added the *params* and *uid* parameters.
       ``str`` search criteria are encoded to *charset*.
 
 
-.. method:: IMAP4.uid(command, arg[, ...])
+.. method:: IMAP4.uid(command, arg[, ...], *, params=None)
 
    Execute command args with messages identified by UID, rather than message
    number.  Returns response appropriate to command.  At least one argument must be
    supplied; if none are provided, the server will return an error and an exception
    will be raised.
 
+   If *params* is given, ``?`` placeholders in the ``SEARCH``, ``SORT`` and
+   ``THREAD`` criteria or in the ``FETCH`` parts are substituted with the quoted
+   parameters (see :ref:`the placeholders <imap4-params>`).
+
+   .. versionchanged:: next
+      Added the *params* parameter.
+
 
 .. method:: IMAP4.unsubscribe(mailbox)
 

Doc/library/symtable.rst

@@ -20,6 +20,8 @@ Generating Symbol Tables
 .. function:: symtable(code, filename, compile_type, *, module=None)
 
    Return the toplevel :class:`SymbolTable` for the Python source *code*.
+   *code* can be a string, a bytes object, or an AST object,
+   as for the builtin :func:`compile`.
    *filename* is the name of the file containing the code.  *compile_type* is
    like the *mode* argument to :func:`compile`.
    The optional argument *module* specifies the module name.
@@ -29,6 +31,9 @@ Generating Symbol Tables
    .. versionadded:: 3.15
       Added the *module* parameter.
 
+   .. versionchanged:: next
+      *code* can now be an AST object.
+
 
 Examining Symbol Tables
 -----------------------

Doc/whatsnew/3.16.rst

@@ -290,6 +290,17 @@ imaplib
   the criteria are sent using the connection encoding instead.
   (Contributed by Serhiy Storchaka in :gh:`153494`.)
 
+* Command methods now accept structured arguments,
+  so the module takes care of quoting instead of the caller.
+  A *message_set* and lists of flags or other atoms
+  can be passed as sequences instead of preformatted strings,
+  and the :meth:`~imaplib.IMAP4.search`, :meth:`~imaplib.IMAP4.fetch`,
+  :meth:`~imaplib.IMAP4.sort`, :meth:`~imaplib.IMAP4.thread` and
+  :meth:`~imaplib.IMAP4.uid` methods accept a *params* keyword argument
+  that substitutes and quotes ``?`` placeholders,
+  in the manner of :mod:`sqlite3` parameter substitution.
+  (Contributed by Serhiy Storchaka in :gh:`153521`.)
+
 
 ipaddress
 ---------
@@ -368,6 +379,14 @@ shlex
   (Contributed by Jay Berry in :gh:`148846`.)
 
 
+symtable
+--------
+
+* :func:`symtable.symtable` now accepts an AST object,
+  like the builtin :func:`compile`.
+  (Contributed by Serhiy Storchaka in :gh:`153844`.)
+
+
 tkinter
 -------
 

Lib/curses/ascii.py

@@ -1,5 +1,8 @@
 """Constants and membership tests for ASCII characters"""
 
+# A character-cell type, present on wide and narrow builds.
+from _curses import complexchar as _complexchar
+
 NUL     = 0x00  # ^@
 SOH     = 0x01  # ^A
 STX     = 0x02  # ^B
@@ -48,8 +51,12 @@
 def _ctoi(c):
     if isinstance(c, str):
         return ord(c)
-    else:
-        return c
+    if isinstance(c, _complexchar):
+        # A character cell: its single character, or -1 (matches no class)
+        # for a cell with combining characters.
+        s = str(c)
+        return ord(s) if len(s) == 1 else -1
+    return c
 
 def isalnum(c): return isalpha(c) or isdigit(c)
 def isalpha(c): return isupper(c) or islower(c)
@@ -69,22 +76,23 @@ def isctrl(c): return 0 <= _ctoi(c) < 32
 def ismeta(c): return _ctoi(c) > 127
 
 def ascii(c):
-    if isinstance(c, str):
-        return chr(_ctoi(c) & 0x7f)
-    else:
+    if isinstance(c, int):
         return _ctoi(c) & 0x7f
+    else:
+        return chr(_ctoi(c) & 0x7f)
 
 def ctrl(c):
-    if isinstance(c, str):
-        return chr(_ctoi(c) & 0x1f)
-    else:
-        return _ctoi(c) & 0x1f
+    code = _ctoi(c)
+    if not 0 <= code < 128:
+        # No control character outside ASCII: return c unchanged.
+        return c if isinstance(c, int) else str(c)
+    return code & 0x1f if isinstance(c, int) else chr(code & 0x1f)
 
 def alt(c):
-    if isinstance(c, str):
-        return chr(_ctoi(c) | 0x80)
-    else:
+    if isinstance(c, int):
         return _ctoi(c) | 0x80
+    else:
+        return chr(_ctoi(c) | 0x80)
 
 def unctrl(c):
     bits = _ctoi(c)