[Python-checkins] gh-102500: Document PEP 688 (#102571)

[JelleZijlstra]

https://github.com/python/cpython/commit/b7a0a521960a6e9ea46b79b51cbcc3c4ffcc7057
commit: b7a0a521960a6e9ea46b79b51cbcc3c4ffcc7057
branch: main
author: Jelle Zijlstra <jelle.zijlstra at gmail.com>
committer: JelleZijlstra <jelle.zijlstra at gmail.com>
date: 2023-05-04T08:23:40-07:00
summary:

gh-102500: Document PEP 688 (#102571)

Co-authored-by: Hugo van Kemenade <hugovk at users.noreply.github.com>
Co-authored-by: Shantanu <12621235+hauntsaninja at users.noreply.github.com>

files:
M Doc/library/collections.abc.rst
M Doc/library/inspect.rst
M Doc/reference/datamodel.rst
M Doc/whatsnew/3.12.rst

diff --git a/Doc/library/collections.abc.rst b/Doc/library/collections.abc.rst
index 1ada0d352a0c..669b7345499a 100644
--- a/Doc/library/collections.abc.rst
+++ b/Doc/library/collections.abc.rst
@@ -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:`~object.__buffer__` method,
+   implementing the :ref:`buffer protocol <bufferobjects>`. See :pep:`688`.
+
+   .. versionadded:: 3.12
+
 Examples and Recipes
 --------------------
 
diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst
index 88f843c03b1d..7884308a3330 100644
--- a/Doc/library/inspect.rst
+++ b/Doc/library/inspect.rst
@@ -1603,6 +1603,39 @@ the following flags:
    for any introspection needs.
 
 
+Buffer flags
+------------
+
+.. class:: BufferFlags
+
+   This is an :class:`enum.IntFlag` that represents the flags that
+   can be passed to the :meth:`~object.__buffer__` method of objects
+   implementing the :ref:`buffer protocol <bufferobjects>`.
+
+   The meaning of the flags is explained at :ref:`buffer-request-types`.
+
+   .. attribute:: BufferFlags.SIMPLE
+   .. attribute:: BufferFlags.WRITABLE
+   .. attribute:: BufferFlags.FORMAT
+   .. attribute:: BufferFlags.ND
+   .. attribute:: BufferFlags.STRIDES
+   .. attribute:: BufferFlags.C_CONTIGUOUS
+   .. attribute:: BufferFlags.F_CONTIGUOUS
+   .. attribute:: BufferFlags.ANY_CONTIGUOUS
+   .. attribute:: BufferFlags.INDIRECT
+   .. attribute:: BufferFlags.CONTIG
+   .. attribute:: BufferFlags.CONTIG_RO
+   .. attribute:: BufferFlags.STRIDED
+   .. attribute:: BufferFlags.STRIDED_RO
+   .. attribute:: BufferFlags.RECORDS
+   .. attribute:: BufferFlags.RECORDS_RO
+   .. attribute:: BufferFlags.FULL
+   .. attribute:: BufferFlags.FULL_RO
+   .. attribute:: BufferFlags.READ
+   .. attribute:: BufferFlags.WRITE
+
+   .. versionadded:: 3.12
+
 .. _inspect-module-cli:
 
 Command Line Interface
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 1294d683e268..0a9cabc158b9 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -2865,6 +2865,47 @@ 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 to 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:`~object.__buffer__`. The method must release any resources associated
+   with the buffer. This method should return ``None``.
+   Buffer objects that do not need to perform any cleanup are not required
+   to implement this method.
+
+.. 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
index edbf92146755..3fe3310a26e5 100644
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -149,6 +149,19 @@ New Features
   In Python 3.14, the default will switch to ``'data'``.
   (Contributed by Petr Viktorin in :pep:`706`.)
 
+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:`~object.__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.
+The new :class:`inspect.BufferFlags` enum represents the flags that
+can be used to customize buffer creation.
+(Contributed by Jelle Zijlstra in :gh:`102500`.)
+
 New Features Related to Type Hints
 ==================================
 
@@ -179,7 +192,6 @@ See :pep:`692` for more details.
 
 (PEP written by Franek Magiera)
 
-
 Other Language Changes
 ======================