Deploy preview for PR 1231 🛫

Author: pydoc-zh-tw[bot]

pr-preview/pr-1231/_sources/c-api/descriptor.rst.txt

@@ -8,18 +8,36 @@ Descriptor Objects
 "Descriptors" are objects that describe some attribute of an object. They are
 found in the dictionary of type objects.
 
-.. XXX document these!
-
 .. c:var:: PyTypeObject PyProperty_Type
 
    The type object for the built-in descriptor types.
 
 
 .. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
 
+   Create a new get-set descriptor for extension type *type* from the
+   :c:type:`PyGetSetDef` structure *getset*.
+
+   Get-set descriptors expose attributes implemented by C getter and setter
+   functions rather than stored directly in the instance. This is the same kind
+   of descriptor created for entries in :c:member:`~PyTypeObject.tp_getset`, and
+   it appears in Python as a :class:`types.GetSetDescriptorType` object.
+
+   On success, return a :term:`strong reference` to the descriptor. Return
+   ``NULL`` with an exception set on failure.
+
+.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *member)
+
+   Create a new member descriptor for extension type *type* from the
+   :c:type:`PyMemberDef` structure *member*.
 
-.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
+   Member descriptors expose fields in the type's C struct as Python
+   attributes. This is the same kind of descriptor created for entries in
+   :c:member:`~PyTypeObject.tp_members`, and it appears in Python as a
+   :class:`types.MemberDescriptorType` object.
 
+   On success, return a :term:`strong reference` to the descriptor. Return
+   ``NULL`` with an exception set on failure.
 
 .. c:var:: PyTypeObject PyMemberDescr_Type
 
@@ -35,22 +53,53 @@ found in the dictionary of type objects.
    The type object for get/set descriptor objects created from
    :c:type:`PyGetSetDef` structures. These descriptors implement attributes
    whose value is computed by C getter and setter functions, and are used
-   for many built-in type attributes.
+   for many built-in type attributes. They correspond to
+   :class:`types.GetSetDescriptorType` objects in Python.
 
 
 .. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
 
+   Create a new method descriptor for extension type *type* from the
+   :c:type:`PyMethodDef` structure *meth*.
+
+   Method descriptors expose C functions as methods on a type. This is the same
+   kind of descriptor created for entries in
+   :c:member:`~PyTypeObject.tp_methods`, and it appears in Python as a
+   :class:`types.MethodDescriptorType` object.
+
+   On success, return a :term:`strong reference` to the descriptor. Return
+   ``NULL`` with an exception set on failure.
 
 .. c:var:: PyTypeObject PyMethodDescr_Type
 
    The type object for method descriptor objects created from
    :c:type:`PyMethodDef` structures. These descriptors expose C functions as
-   methods on a type, and correspond to :class:`types.MemberDescriptorType`
+   methods on a type, and correspond to :class:`types.MethodDescriptorType`
    objects in Python.
 
 
-.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
+.. c:struct:: wrapperbase
+
+   Describes a slot wrapper used by :c:func:`PyDescr_NewWrapper`.
+
+   Each ``wrapperbase`` record stores the Python-visible name and metadata for a
+   special method implemented by a type slot, together with the wrapper
+   function used to adapt that slot to Python's calling convention.
 
+.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *base, void *wrapped)
+
+   Create a new wrapper descriptor for extension type *type* from the
+   :c:struct:`wrapperbase` structure *base* and the wrapped slot function
+   pointer
+   *wrapped*.
+
+   Wrapper descriptors expose special methods implemented by type slots. This
+   is the same kind of descriptor that CPython creates for slot-based special
+   methods such as ``__repr__`` or ``__add__``, and it appears in Python as a
+   :class:`types.WrapperDescriptorType` object.
+
+   On success, return a :term:`strong reference` to the descriptor. Return
+   ``NULL`` with an exception set on failure.
 
 .. c:var:: PyTypeObject PyWrapperDescr_Type
 
@@ -63,6 +112,16 @@ found in the dictionary of type objects.
 
 .. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
 
+   Create a new class method descriptor for extension type *type* from the
+   :c:type:`PyMethodDef` structure *method*.
+
+   Class method descriptors expose C methods that receive the class rather than
+   an instance when accessed. This is the same kind of descriptor created for
+   ``METH_CLASS`` entries in :c:member:`~PyTypeObject.tp_methods`, and it
+   appears in Python as a :class:`types.ClassMethodDescriptorType` object.
+
+   On success, return a :term:`strong reference` to the descriptor. Return
+   ``NULL`` with an exception set on failure.
 
 .. c:function:: int PyDescr_IsData(PyObject *descr)
 
@@ -71,8 +130,18 @@ found in the dictionary of type objects.
    no error checking.
 
 
-.. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)
+.. c:function:: PyObject* PyWrapper_New(PyObject *d, PyObject *self)
+
+   Create a new bound wrapper object from the wrapper descriptor *d* and the
+   instance *self*.
 
+   This is the bound form of a wrapper descriptor created by
+   :c:func:`PyDescr_NewWrapper`. CPython creates these objects when a slot
+   wrapper is accessed through an instance, and they appear in Python as
+   :class:`types.MethodWrapperType` objects.
+
+   On success, return a :term:`strong reference` to the wrapper object. Return
+   ``NULL`` with an exception set on failure.
 
 Built-in descriptors
 ^^^^^^^^^^^^^^^^^^^^
@@ -92,9 +161,9 @@ Built-in descriptors
 .. c:var:: PyTypeObject PyClassMethodDescr_Type
 
    The type object for C-level class method descriptor objects.
-   This is the type of the descriptors created for :func:`classmethod` defined in
-   C extension types, and is the same object as :class:`classmethod`
-   in Python.
+   This is the type of the descriptors created for :func:`classmethod` defined
+   in C extension types, and corresponds to
+   :class:`types.ClassMethodDescriptorType` objects in Python.
 
 
 .. c:function:: PyObject *PyClassMethod_New(PyObject *callable)
@@ -121,4 +190,3 @@ Built-in descriptors
    On success, this function returns a :term:`strong reference` to a new static
    method descriptor. On failure, this function returns ``NULL`` with an
    exception set.
-

pr-preview/pr-1231/_sources/howto/a-conceptual-overview-of-asyncio.rst.txt

@@ -115,7 +115,7 @@ The terms "coroutine function" and "coroutine object" are often conflated
 as coroutine.
 That can be confusing!
 In this article, coroutine specifically refers to a coroutine object, or more
-precisely, an instance of :data:`types.CoroutineType` (native coroutine).
+precisely, an instance of :class:`types.CoroutineType` (native coroutine).
 Note that coroutines can also exist as instances of
 :class:`collections.abc.Coroutine` -- a distinction that matters for type
 checking.

pr-preview/pr-1231/_sources/library/curses.panel.rst.txt

@@ -18,6 +18,14 @@ displayed.  Panels can be added, moved up or down in the stack, and removed.
 Functions
 ---------
 
+The module :mod:`!curses.panel` defines the following exception:
+
+
+.. exception:: error
+
+   Exception raised when a curses panel library function returns an error.
+
+
 The module :mod:`!curses.panel` defines the following functions:
 
 
@@ -50,73 +58,91 @@ The module :mod:`!curses.panel` defines the following functions:
 Panel objects
 -------------
 
-Panel objects, as returned by :func:`new_panel` above, are windows with a
-stacking order. There's always a window associated with a panel which determines
-the content, while the panel methods are responsible for the window's depth in
-the panel stack.
+.. raw:: html
+
+   <!-- Keep the old URL fragments working (see gh-89554) -->
+   <span id='curses.panel.Panel.above'></span>
+   <span id='curses.panel.Panel.below'></span>
+   <span id='curses.panel.Panel.bottom'></span>
+   <span id='curses.panel.Panel.hidden'></span>
+   <span id='curses.panel.Panel.hide'></span>
+   <span id='curses.panel.Panel.move'></span>
+   <span id='curses.panel.Panel.replace'></span>
+   <span id='curses.panel.Panel.set_userptr'></span>
+   <span id='curses.panel.Panel.show'></span>
+   <span id='curses.panel.Panel.top'></span>
+   <span id='curses.panel.Panel.userptr'></span>
+   <span id='curses.panel.Panel.window'></span>
+
+.. class:: panel
+
+   Panel objects, as returned by :func:`new_panel` above, are windows with a
+   stacking order.  There's always a window associated with a panel which
+   determines the content, while the panel methods are responsible for the
+   window's depth in the panel stack.
 
-Panel objects have the following methods:
+   Panel objects have the following methods:
 
 
-.. method:: Panel.above()
+.. method:: panel.above()
 
    Returns the panel above the current panel.
 
 
-.. method:: Panel.below()
+.. method:: panel.below()
 
    Returns the panel below the current panel.
 
 
-.. method:: Panel.bottom()
+.. method:: panel.bottom()
 
    Push the panel to the bottom of the stack.
 
 
-.. method:: Panel.hidden()
+.. method:: panel.hidden()
 
    Returns ``True`` if the panel is hidden (not visible), ``False`` otherwise.
 
 
-.. method:: Panel.hide()
+.. method:: panel.hide()
 
    Hide the panel. This does not delete the object, it just makes the window on
    screen invisible.
 
 
-.. method:: Panel.move(y, x)
+.. method:: panel.move(y, x)
 
    Move the panel to the screen coordinates ``(y, x)``.
 
 
-.. method:: Panel.replace(win)
+.. method:: panel.replace(win)
 
    Change the window associated with the panel to the window *win*.
 
 
-.. method:: Panel.set_userptr(obj)
+.. method:: panel.set_userptr(obj)
 
    Set the panel's user pointer to *obj*. This is used to associate an arbitrary
    piece of data with the panel, and can be any Python object.
 
 
-.. method:: Panel.show()
+.. method:: panel.show()
 
    Display the panel (which might have been hidden), placing it on top of
    the panel stack.
 
 
-.. method:: Panel.top()
+.. method:: panel.top()
 
    Push panel to the top of the stack.
 
 
-.. method:: Panel.userptr()
+.. method:: panel.userptr()
 
    Returns the user pointer for the panel.  This might be any Python object.
 
 
-.. method:: Panel.window()
+.. method:: panel.window()
 
    Returns the window object associated with the panel.
 

pr-preview/pr-1231/_sources/library/stdtypes.rst.txt

@@ -1720,7 +1720,11 @@ category.
 |                          |  :meth:`str.strip`                        |  :meth:`bytes.strip`                              |
 |                          +--------------------+----------------------+----------------------+----------------------------+
 |                          | :meth:`str.lstrip` | :meth:`str.rstrip`   | :meth:`bytes.lstrip` | :meth:`bytes.rstrip`       |
-+--------------------------+--------------------+----------------------+----------------------+----------------------------+
+|                          +--------------------+----------------------+----------------------+----------------------------+
+|                          |  :meth:`str.removeprefix`                 |  :meth:`bytes.removeprefix`                       |
+|                          +-------------------------------------------+---------------------------------------------------+
+|                          |  :meth:`str.removesuffix`                 |  :meth:`bytes.removesuffix`                       |
++--------------------------+-------------------------------------------+---------------------------------------------------+
 | Translation and Encoding |  :meth:`str.translate`                    |  :meth:`bytes.translate`                          |
 |                          +-------------------------------------------+---------------------------------------------------+
 |                          |  :meth:`str.maketrans`                    |  :meth:`bytes.maketrans`                          |

pr-preview/pr-1231/_sources/library/struct.rst.txt

@@ -68,6 +68,7 @@ The module defines the following exception and functions:
    Pack the values *v1*, *v2*, ... according to the format string *format* and
    write the packed bytes into the writable buffer *buffer* starting at
    position *offset*.  Note that *offset* is a required argument.
+   A negative *offset* counts from the end of *buffer*.
 
 
 .. function:: unpack(format, buffer)
@@ -84,6 +85,7 @@ The module defines the following exception and functions:
    string *format*.  The result is a tuple even if it contains exactly one
    item.  The buffer's size in bytes, starting at position *offset*, must be at
    least the size required by the format, as reflected by :func:`calcsize`.
+   A negative *offset* counts from the end of *buffer*.
 
 
 .. function:: iter_unpack(format, buffer)

pr-preview/pr-1231/_sources/library/tkinter.dnd.rst.txt

@@ -16,21 +16,22 @@ a single application, within the same window or between windows. To enable an
 object to be dragged, you must create an event binding for it that starts the
 drag-and-drop process. Typically, you bind a ButtonPress event to a callback
 function that you write (see :ref:`Bindings-and-Events`). The function should
-call :func:`dnd_start`, where 'source' is the object to be dragged, and 'event'
+call :func:`dnd_start`, where *source* is the object to be dragged, and *event*
 is the event that invoked the call (the argument to your callback function).
 
 Selection of a target object occurs as follows:
 
-#. Top-down search of area under mouse for target widget
+#. Top-down search of the area under the mouse for a target widget:
 
- * Target widget should have a callable *dnd_accept* attribute
- * If *dnd_accept* is not present or returns ``None``, search moves to parent widget
- * If no target widget is found, then the target object is ``None``
+   * the target widget should have a callable *dnd_accept* attribute;
+   * if *dnd_accept* is not present or returns ``None``,
+     the search moves to the parent widget;
+   * if no target widget is found, the target object is ``None``.
 
-2. Call to *<old_target>.dnd_leave(source, event)*
-#. Call to *<new_target>.dnd_enter(source, event)*
-#. Call to *<target>.dnd_commit(source, event)* to notify of drop
-#. Call to *<source>.dnd_end(target, event)* to signal end of drag-and-drop
+#. Call to ``<old_target>.dnd_leave(source, event)``.
+#. Call to ``<new_target>.dnd_enter(source, event)``.
+#. Call to ``<target>.dnd_commit(source, event)`` to notify of the drop.
+#. Call to ``<source>.dnd_end(target, event)`` to signal the end of drag-and-drop.
 
 
 .. class:: DndHandler(source, event)