Merge branch 'main' into bytes_per_sep-maxsize

Author: serhiy-storchaka

Doc/c-api/descriptor.rst

@@ -8,13 +8,31 @@ 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: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)
 
-.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
+   Create a new member descriptor for extension type *type* from the
+   :c:type:`PyMemberDef` structure *member*.
 
+   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
 
@@ -30,22 +48,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
 
@@ -58,6 +107,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)
 
@@ -66,8 +125,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.
 
 .. c:macro:: PyDescr_COMMON
 
@@ -104,9 +173,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)

Doc/library/base64.rst

@@ -146,13 +146,20 @@ POST request.
       Accepting the ``+`` and ``/`` characters is now deprecated.
 
 
-.. function:: b32encode(s)
+.. function:: b32encode(s, *, wrapcol=0)
 
    Encode the :term:`bytes-like object` *s* using Base32 and return the
    encoded :class:`bytes`.
 
+   If *wrapcol* is non-zero, insert a newline (``b'\n'``) character
+   after at most every *wrapcol* characters.
+   If *wrapcol* is zero (default), do not add any newlines.
+
+   .. versionchanged:: next
+      Added the *wrapcol* parameter.
+
 
-.. function:: b32decode(s, casefold=False, map01=None)
+.. function:: b32decode(s, casefold=False, map01=None, *, ignorechars=b'')
 
    Decode the Base32 encoded :term:`bytes-like object` or ASCII string *s* and
    return the decoded :class:`bytes`.
@@ -168,20 +175,29 @@ POST request.
    digit 0 is always mapped to the letter O).  For security purposes the default is
    ``None``, so that 0 and 1 are not allowed in the input.
 
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+
    A :exc:`binascii.Error` is raised if *s* is
    incorrectly padded or if there are non-alphabet characters present in the
    input.
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
 
-.. function:: b32hexencode(s)
+.. function:: b32hexencode(s, *, wrapcol=0)
 
    Similar to :func:`b32encode` but uses the Extended Hex Alphabet, as defined in
    :rfc:`4648`.
 
    .. versionadded:: 3.10
 
+   .. versionchanged:: next
+      Added the *wrapcol* parameter.
+
 
-.. function:: b32hexdecode(s, casefold=False)
+.. function:: b32hexdecode(s, casefold=False, *, ignorechars=b'')
 
    Similar to :func:`b32decode` but uses the Extended Hex Alphabet, as defined in
    :rfc:`4648`.
@@ -193,14 +209,24 @@ POST request.
 
    .. versionadded:: 3.10
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
 
-.. function:: b16encode(s)
+.. function:: b16encode(s, *, wrapcol=0)
 
    Encode the :term:`bytes-like object` *s* using Base16 and return the
    encoded :class:`bytes`.
 
+   If *wrapcol* is non-zero, insert a newline (``b'\n'``) character
+   after at most every *wrapcol* characters.
+   If *wrapcol* is zero (default), do not add any newlines.
+
+   .. versionchanged:: next
+      Added the *wrapcol* parameter.
 
-.. function:: b16decode(s, casefold=False)
+
+.. function:: b16decode(s, casefold=False, *, ignorechars=b'')
 
    Decode the Base16 encoded :term:`bytes-like object` or ASCII string *s* and
    return the decoded :class:`bytes`.
@@ -209,10 +235,17 @@ POST request.
    lowercase alphabet is acceptable as input.  For security purposes, the default
    is ``False``.
 
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+
    A :exc:`binascii.Error` is raised if *s* is
    incorrectly padded or if there are non-alphabet characters present in the
    input.
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
+
 .. _base64-base-85:
 
 Base85 Encodings
@@ -277,27 +310,40 @@ Refer to the documentation of the individual functions for more information.
    .. versionadded:: 3.4
 
 
-.. function:: b85encode(b, pad=False)
+.. function:: b85encode(b, pad=False, *, wrapcol=0)
 
    Encode the :term:`bytes-like object` *b* using base85 (as used in e.g.
    git-style binary diffs) and return the encoded :class:`bytes`.
 
    If *pad* is true, the input is padded with ``b'\0'`` so its length is a
    multiple of 4 bytes before encoding.
 
+   If *wrapcol* is non-zero, insert a newline (``b'\n'``) character
+   after at most every *wrapcol* characters.
+   If *wrapcol* is zero (default), do not add any newlines.
+
    .. versionadded:: 3.4
 
+   .. versionchanged:: next
+      Added the *wrapcol* parameter.
 
-.. function:: b85decode(b)
+
+.. function:: b85decode(b, *, ignorechars=b'')
 
    Decode the base85-encoded :term:`bytes-like object` or ASCII string *b* and
    return the decoded :class:`bytes`.  Padding is implicitly removed, if
    necessary.
 
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+
    .. versionadded:: 3.4
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
 
-.. function:: z85encode(s, pad=False)
+.. function:: z85encode(s, pad=False, *, wrapcol=0)
 
    Encode the :term:`bytes-like object` *s* using Z85 (as used in ZeroMQ)
    and return the encoded :class:`bytes`.  See `Z85  specification
@@ -306,20 +352,33 @@ Refer to the documentation of the individual functions for more information.
    If *pad* is true, the input is padded with ``b'\0'`` so its length is a
    multiple of 4 bytes before encoding.
 
+   If *wrapcol* is non-zero, insert a newline (``b'\n'``) character
+   after at most every *wrapcol* characters.
+   If *wrapcol* is zero (default), do not add any newlines.
+
    .. versionadded:: 3.13
 
    .. versionchanged:: 3.15
       The *pad* parameter was added.
 
+   .. versionchanged:: next
+      Added the *wrapcol* parameter.
+
 
-.. function:: z85decode(s)
+.. function:: z85decode(s, *, ignorechars=b'')
 
    Decode the Z85-encoded :term:`bytes-like object` or ASCII string *s* and
    return the decoded :class:`bytes`.  See `Z85  specification
    <https://rfc.zeromq.org/spec/32/>`_ for more information.
 
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+
    .. versionadded:: 3.13
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
 
 .. _base64-legacy: