Document PEP 688

python · JelleZijlstra · May 4, 2023 · Mar 10, 2023 · Mar 10, 2023 · Mar 11, 2023
commit d55ca46c4a48fa03f1a8e1d823f74122a9498c8b
@@ -177,6 +177,7 @@ ABC                            Inherits from          Abstract Methods        Mi
 :class:`AsyncIterable` [1]_                           ``__aiter__``
 :class:`AsyncIterator` [1]_    :class:`AsyncIterable` ``__anext__``           ``__aiter__``
 :class:`AsyncGenerator` [1]_   :class:`AsyncIterator` ``asend``, ``athrow``   ``aclose``, ``__aiter__``, ``__anext__``
+:class:`Buffer` [1]_                                  ``__buffer__``
 ============================== ====================== ======================= ====================================================
 
 
@@ -346,6 +347,13 @@ Collections Abstract Base Classes -- Detailed Descriptions
 
    .. versionadded:: 3.6
 
+.. class:: Buffer
+
+   ABC for classes that provide the :meth:`__buffer__` method,
+   implementing the :ref:`buffer protocol <bufferobjects>`. See :pep:`688`.
+
+   .. versionadded:: 3.12
+
 Examples and Recipes
 --------------------
 

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
@@ -1070,7 +1070,7 @@ are always available.  They are listed here in alphabetical order.
 
 
 .. _func-memoryview:
-.. class:: memoryview(object)
+.. class:: memoryview(object, *, flags=BufferFlags.FULL_RO)
    :noindex:
 
    Return a "memory view" object created from the given argument.  See

diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
@@ -1575,6 +1575,41 @@ the following flags:
    for any introspection needs.
 
 
+Buffer flags
+------------
+
+The :mod:`inspect` module provides an :class:`enum.IntFlag`
+
+.. class:: BufferFlags
+
+   This is an :class:`enum.IntFlag` that represents the flags that
+   can be passed to the :meth:`__buffer__` method of objects
+   implementing the :ref:`buffer protocol <bufferobjects>`.
+
+   The meaning of the flags is explained at :ref:`buffer-request-types`.
+
+   .. attribute:: SIMPLE
+   .. attribute:: WRITABLE
+   .. attribute:: FORMAT
+   .. attribute:: ND
+   .. attribute:: STRIDES
+   .. attribute:: C_CONTIGUOUS
+   .. attribute:: F_CONTIGUOUS
+   .. attribute:: ANY_CONTIGUOUS
+   .. attribute:: INDIRECT
+   .. attribute:: CONTIG
+   .. attribute:: CONTIG_RO
+   .. attribute:: STRIDED
+   .. attribute:: STRIDED_RO
+   .. attribute:: RECORDS
+   .. attribute:: RECORDS_RO
+   .. attribute:: FULL
+   .. attribute:: FULL_RO
+   .. attribute:: READ
+   .. attribute:: WRITE
+
+   .. versionadded:: 3.12
+
 .. _inspect-module-cli:
 
 Command Line Interface

diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
@@ -3704,7 +3704,7 @@ Memory Views
 of an object that supports the :ref:`buffer protocol <bufferobjects>` without
 copying.
 
-.. class:: memoryview(object)
+.. class:: memoryview(object, *, flags=BufferFlags.FULL_RO)
 
    Create a :class:`memoryview` that references *object*.  *object* must
    support the buffer protocol.  Built-in objects that support the buffer
@@ -3789,6 +3789,15 @@ copying.
       >>> hash(v[::-2]) == hash(b'abcefg'[::-2])
       True
 
+   The optional ``flags`` can be used to control the :class:`inspect.BufferFlags <buffer flags>`
+   passed to the underlying buffer. For example::
+
+      >>> import inspect
+      >>> v = memoryview(b"x", flags=inspect.BufferFlags.WRITABLE)
+      ...
+      BufferError: Object is not writable.
+      >>> v = memoryview(b"x", flags=inspect.BufferFlags.SIMPLE)
+
    .. versionchanged:: 3.3
       One-dimensional memoryviews can now be sliced.
       One-dimensional memoryviews with formats 'B', 'b' or 'c' are now :term:`hashable`.
@@ -3800,6 +3809,9 @@ copying.
    .. versionchanged:: 3.5
       memoryviews can now be indexed with tuple of integers.
 
+   .. versionchanged:: 3.12
+      Added the ``flags`` argument.
+
    :class:`memoryview` has several methods:
 
    .. method:: __eq__(exporter)

@@ -2849,6 +2849,45 @@ a :exc:`TypeError`.
       The specification for the Python ``match`` statement.
 
 
+.. _python-buffer-protocol:
+
+Emulating buffer types
+----------------------
+
+The :ref:`buffer protocol <bufferobjects>` provides a way for Python
+objects to expose efficient access a low-level memory array. This protocol
+is implemented by builtin types such as :class:`bytes` and :class:`memoryview`,
+and third-party libraries may define additional buffer types.
+
+While buffer types are usually implemented in C, it is also possible to
+implement the protocol in Python.
+
+.. method:: object.__buffer__(self, flags)
+
+   Called when a buffer is requested from ``self`` (for example, by the
+   :class:`memoryview` constructor). The ``flags`` argument is an integer
+   representing the kind of buffer requested, affecting for example whether
+   the returned buffer is read-only or writable. :class:`inspect.BufferFlags`
+   provides a convenient way to interpret the flags. The method must return
+   a :class:`memoryview` object.
+
+.. method:: object.__release_buffer__(self, buffer)
+
+   Called when a buffer is no longer needed. The ``buffer`` argument is a
+   :class:`memoryview` object that was previously returned by
+   :meth:`__buffer__`. The method must release any resources associated
+   with the buffer. This method should return ``None``.
+
+.. versionadded:: 3.12
+
+.. seealso::
+
+   :pep:`688` - Making the buffer protocol accessible in Python
+      Introduces the Python ``__buffer__`` and ``__release_buffer__`` methods.
+
+   :class:`collections.abc.Buffer`
+      ABC for buffer types.
+
 .. _special-lookup:
 
 Special method lookup

diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
@@ -138,6 +138,18 @@ New Features
   with contributions from Gregory P. Smith [Google] and Mark Shannon
   in :gh:`96123`.)
 
+PEP 688: Making the buffer protocol accessible in Python
+--------------------------------------------------------
+
+:pep:`688` introduces a way to use the :ref:`buffer protocol <bufferobjects>`
+from Python code. Classes that implement the :meth:`__buffer__` method
+are now usable as buffer types.
+
+The new :class:`collections.abc.Buffer` ABC provides a standard
+way to represent buffer objects, for example in type annotations.
+:class:`memoryview` has a new ``flags`` argument to control the
+:class:`buffer flags <inspect.BufferFlags>` passed to the underlying buffer.
+(Contributed by Jelle Zijlstra in :gh:`102500`.)
 
 Other Language Changes
 ======================