Merge branch 'main' into drop-hasattr

Author: barneygale

Doc/c-api/type.rst

@@ -311,10 +311,6 @@ The following functions and structs are used to create
 
    Metaclasses that override :c:member:`~PyTypeObject.tp_new` are not
    supported, except if ``tp_new`` is ``NULL``.
-   (For backwards compatibility, other ``PyType_From*`` functions allow
-   such metaclasses. They ignore ``tp_new``, which may result in incomplete
-   initialization. This is deprecated and in Python 3.14+ such metaclasses will
-   not be supported.)
 
    The *bases* argument can be used to specify base classes; it can either
    be only one class or a tuple of classes.

Doc/library/ctypes.rst

@@ -657,12 +657,13 @@ Nested structures can also be initialized in the constructor in several ways::
    >>> r = RECT((1, 2), (3, 4))
 
 Field :term:`descriptor`\s can be retrieved from the *class*, they are useful
-for debugging because they can provide useful information::
+for debugging because they can provide useful information.
+See :class:`CField`::
 
-   >>> print(POINT.x)
-   <Field type=c_long, ofs=0, size=4>
-   >>> print(POINT.y)
-   <Field type=c_long, ofs=4, size=4>
+   >>> POINT.x
+   <ctypes.CField 'x' type=c_int, ofs=0, size=4>
+   >>> POINT.y
+   <ctypes.CField 'y' type=c_int, ofs=4, size=4>
    >>>
 
 
@@ -2812,6 +2813,98 @@ fields, or any other data types containing pointer type fields.
    present in :attr:`_fields_`.
 
 
+.. class:: CField(*args, **kw)
+
+   Descriptor for fields of a :class:`Structure` and :class:`Union`.
+   For example::
+
+      >>> class Color(Structure):
+      ...     _fields_ = (
+      ...         ('red', c_uint8),
+      ...         ('green', c_uint8),
+      ...         ('blue', c_uint8),
+      ...         ('intense', c_bool, 1),
+      ...         ('blinking', c_bool, 1),
+      ...    )
+      ...
+      >>> Color.red
+      <ctypes.CField 'red' type=c_ubyte, ofs=0, size=1>
+      >>> Color.green.type
+      <class 'ctypes.c_ubyte'>
+      >>> Color.blue.byte_offset
+      2
+      >>> Color.intense
+      <ctypes.CField 'intense' type=c_bool, ofs=3, bit_size=1, bit_offset=0>
+      >>> Color.blinking.bit_offset
+      1
+
+   All attributes are read-only.
+
+   :class:`!CField` objects are created via :attr:`~Structure._fields_`;
+   do not instantiate the class directly.
+
+   .. versionadded:: next
+
+      Previously, descriptors only had ``offset`` and ``size`` attributes
+      and a readable string representation; the :class:`!CField` class was not
+      available directly.
+
+   .. attribute:: name
+
+      Name of the field, as a string.
+
+   .. attribute:: type
+
+      Type of the field, as a :ref:`ctypes class <ctypes-data-types>`.
+
+   .. attribute:: offset
+                  byte_offset
+
+      Offset of the field, in bytes.
+
+      For bitfields, this is the offset of the underlying byte-aligned
+      *storage unit*; see :attr:`~CField.bit_offset`.
+
+   .. attribute:: byte_size
+
+      Size of the field, in bytes.
+
+      For bitfields, this is the size of the underlying *storage unit*.
+      Typically, it has the same size as the bitfield's type.
+
+   .. attribute:: size
+
+      For non-bitfields, equivalent to :attr:`~CField.byte_size`.
+
+      For bitfields, this contains a backwards-compatible bit-packed
+      value that combines :attr:`~CField.bit_size` and
+      :attr:`~CField.bit_offset`.
+      Prefer using the explicit attributes instead.
+
+   .. attribute:: is_bitfield
+
+      True if this is a bitfield.
+
+   .. attribute:: bit_offset
+                  bit_size
+
+      The location of a bitfield within its *storage unit*, that is, within
+      :attr:`~CField.byte_size` bytes of memory starting at
+      :attr:`~CField.byte_offset`.
+
+      To get the field's value, read the storage unit as an integer,
+      :ref:`shift left <shifting>` by :attr:`!bit_offset` and
+      take the :attr:`!bit_size` least significant bits.
+
+      For non-bitfields, :attr:`!bit_offset` is zero
+      and :attr:`!bit_size` is equal to ``byte_size * 8``.
+
+   .. attribute:: is_anonymous
+
+      True if this field is anonymous, that is, it contains nested sub-fields
+      that should be be merged into a containing structure or union.
+
+
 .. _ctypes-arrays-pointers:
 
 Arrays and pointers

Doc/library/importlib.metadata.rst

@@ -422,7 +422,7 @@ While the module level API described above is the most common and convenient usa
 you can get all of that information from the :class:`!Distribution` class.
 :class:`!Distribution` is an abstract object that represents the metadata for
 a Python `Distribution Package <https://packaging.python.org/en/latest/glossary/#term-Distribution-Package>`_.
-You can get the concreate :class:`!Distribution` subclass instance for an installed
+You can get the concrete :class:`!Distribution` subclass instance for an installed
 distribution package by calling the :func:`distribution` function::
 
     >>> from importlib.metadata import distribution  # doctest: +SKIP

Doc/library/mailbox.rst

@@ -587,12 +587,27 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
    remarks:
 
 
-   .. method:: get_file(key)
+   .. method:: get_bytes(key, from_=False)
+
+      Note: This method has an extra parameter (*from_*) compared with other classes.
+      The first line of an mbox file entry is the Unix "From " line.
+      If *from_* is False, the first line of the file is dropped.
+
+   .. method:: get_file(key, from_=False)
 
       Using the file after calling :meth:`~Mailbox.flush` or
       :meth:`~Mailbox.close` on the :class:`!mbox` instance may yield
       unpredictable results or raise an exception.
 
+      Note: This method has an extra parameter (*from_*) compared with other classes.
+      The first line of an mbox file entry is the Unix "From " line.
+      If *from_* is False, the first line of the file is dropped.
+
+   .. method:: get_string(key, from_=False)
+
+      Note: This method has an extra parameter (*from_*) compared with other classes.
+      The first line of an mbox file entry is the Unix "From " line.
+      If *from_* is False, the first line of the file is dropped.
 
    .. method:: lock()
                unlock()
@@ -851,12 +866,22 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF.
    remarks:
 
 
-   .. method:: get_file(key)
+   .. method:: get_bytes(key, from_=False)
+
+      Note: This method has an extra parameter (*from_*) compared with other classes.
+      The first line of an mbox file entry is the Unix "From " line.
+      If *from_* is False, the first line of the file is dropped.
+
+   .. method:: get_file(key, from_=False)
 
       Using the file after calling :meth:`~Mailbox.flush` or
       :meth:`~Mailbox.close` on the :class:`!MMDF` instance may yield
       unpredictable results or raise an exception.
 
+      Note: This method has an extra parameter (*from_*) compared with other classes.
+      The first line of an mbox file entry is the Unix "From " line.
+      If *from_* is False, the first line of the file is dropped.
+
 
    .. method:: lock()
                unlock()

Doc/library/urllib.request.rst

@@ -1215,48 +1215,49 @@ In addition to the examples below, more examples are given in
 :ref:`urllib-howto`.
 
 This example gets the python.org main page and displays the first 300 bytes of
-it. ::
+it::
 
    >>> import urllib.request
    >>> with urllib.request.urlopen('http://www.python.org/') as f:
    ...     print(f.read(300))
    ...
-   b'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n\n\n<html
-   xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">\n\n<head>\n
-   <meta http-equiv="content-type" content="text/html; charset=utf-8" />\n
-   <title>Python Programming '
+   b'<!doctype html>\n<!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->\n<!--[if IE 7]>      <html class="no-js ie7 lt-ie8 lt-ie9">          <![endif]-->\n<!--[if IE 8]>      <html class="no-js ie8 lt-ie9">
 
 Note that urlopen returns a bytes object.  This is because there is no way
 for urlopen to automatically determine the encoding of the byte stream
 it receives from the HTTP server. In general, a program will decode
 the returned bytes object to string once it determines or guesses
 the appropriate encoding.
 
-The following W3C document, https://www.w3.org/International/O-charset\ , lists
-the various ways in which an (X)HTML or an XML document could have specified its
+The following HTML spec document, https://html.spec.whatwg.org/#charset, lists
+the various ways in which an HTML or an XML document could have specified its
 encoding information.
 
+For additional information, see the W3C document: https://www.w3.org/International/questions/qa-html-encoding-declarations.
+
 As the python.org website uses *utf-8* encoding as specified in its meta tag, we
-will use the same for decoding the bytes object. ::
+will use the same for decoding the bytes object::
 
    >>> with urllib.request.urlopen('http://www.python.org/') as f:
    ...     print(f.read(100).decode('utf-8'))
    ...
-   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-   "http://www.w3.org/TR/xhtml1/DTD/xhtm
+   <!doctype html>
+   <!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->
+   <!-
 
 It is also possible to achieve the same result without using the
-:term:`context manager` approach. ::
+:term:`context manager` approach::
 
    >>> import urllib.request
    >>> f = urllib.request.urlopen('http://www.python.org/')
    >>> try:
    ...     print(f.read(100).decode('utf-8'))
    ... finally:
    ...     f.close()
-   <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-   "http://www.w3.org/TR/xhtml1/DTD/xhtm
+   ...
+   <!doctype html>
+   <!--[if lt IE 7]>   <html class="no-js ie6 lt-ie7 lt-ie8 lt-ie9">   <![endif]-->
+   <!--
 
 In the following example, we are sending a data-stream to the stdin of a CGI
 and reading the data it returns to us. Note that this example will only work

Doc/whatsnew/3.14.rst

@@ -502,6 +502,11 @@ ctypes
   to help match a non-default ABI.
   (Contributed by Petr Viktorin in :gh:`97702`.)
 
+* The class of :class:`~ctypes.Structure`/:class:`~ctypes.Union`
+  field descriptors is now available as :class:`~ctypes.CField`,
+  and has new attributes to aid debugging and introspection.
+  (Contributed by Petr Viktorin in :gh:`128715`.)
+
 * On Windows, the :exc:`~ctypes.COMError` exception is now public.
   (Contributed by Jun Komoda in :gh:`126686`.)
 

Include/internal/pycore_global_objects_fini_generated.h

@@ -247,6 +247,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(_get_sourcefile)
         STRUCT_FOR_ID(_handle_fromlist)
         STRUCT_FOR_ID(_initializing)
+        STRUCT_FOR_ID(_internal_use)
         STRUCT_FOR_ID(_io)
         STRUCT_FOR_ID(_is_text_encoding)
         STRUCT_FOR_ID(_isatty_open_only)
@@ -297,6 +298,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(before)
         STRUCT_FOR_ID(big)
         STRUCT_FOR_ID(binary_form)
+        STRUCT_FOR_ID(bit_offset)
         STRUCT_FOR_ID(bit_size)
         STRUCT_FOR_ID(block)
         STRUCT_FOR_ID(bound)
@@ -307,6 +309,8 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(buffers)
         STRUCT_FOR_ID(bufsize)
         STRUCT_FOR_ID(builtins)
+        STRUCT_FOR_ID(byte_offset)
+        STRUCT_FOR_ID(byte_size)
         STRUCT_FOR_ID(byteorder)
         STRUCT_FOR_ID(bytes)
         STRUCT_FOR_ID(bytes_per_sep)

Include/internal/pycore_global_strings.h

@@ -189,8 +189,11 @@ _PyFrame_SetStackPointer(_PyInterpreterFrame *frame, _PyStackRef *stack_pointer)
  * Frames on the frame stack are incomplete until the
  * first RESUME instruction.
  * Frames owned by a generator are always complete.
+ *
+ * NOTE: We allow racy accesses to the instruction pointer
+ * from other threads for sys._current_frames() and similar APIs.
  */
-static inline bool
+static inline bool _Py_NO_SANITIZE_THREAD
 _PyFrame_IsIncomplete(_PyInterpreterFrame *frame)
 {
     if (frame->owner >= FRAME_OWNED_BY_INTERPRETER) {