From 5a0c79ef46aeac775a93ab1e69a2e31477c05d82 Mon Sep 17 00:00:00 2001
From: Sebastian Berg <sebastianb@nvidia.com>
Date: Mon, 4 May 2026 11:56:19 +0200
Subject: [PATCH] PEP 3118: Clarify format string "unimplemented" note

In order to wrap up the discussion around the choice of ``Zd`` vs. ``D``
a bit, I propose changing the "not implemented" note a bit.

Not sure if it comes quite across, but I think:
1. There is no good reason to break with any of the "additions" here
   (I.e. don't use `&` to mean something different).
2. Python should feel free to diverge, but I think the note
   pointing to NumPy (which is "just" an example) hopefully makes it
   clear that this isn't a void.
---
 peps/pep-3118.rst | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/peps/pep-3118.rst b/peps/pep-3118.rst
index 84710bb1dbd..fa08849df6a 100644
--- a/peps/pep-3118.rst
+++ b/peps/pep-3118.rst
@@ -14,7 +14,8 @@ Post-History: `09-Apr-2007 <https://mail.python.org/archives/list/python-dev@pyt
    Not all features proposed here were implemented. Specifically:
 
    - ``PyObject_CopyToObject`` was not added.
-   - :ref:`3118-struct-additions` were not added, except for ``?`` (``_Bool``).
+   - :ref:`3118-struct-additions` were only partially adopted by Python
+     and downstream libraries (see note there).
    - ``PyObject_GetMemoryView`` is named
      :external+python:c:type:`PyMemoryView_FromObject`.
 
@@ -648,6 +649,15 @@ object that does not provide the protocol.
 Additions to the struct string-syntax
 =====================================
 
+.. note::
+
+   Not all of the proposed extensions are implemented by Python, and
+   downstream libraries like NumPy use only a subset (i.e., NumPy does not
+   use ``X{}``, ``t``, ``&``, or the historic narrow-build ucs-2 ``u``).
+   Future additions to the buffer protocol format string should aim
+   not to conflict with the additions proposed here. However, Python
+   may adopt different conventions for those it has not implemented.
+
 The struct string-syntax is missing some characters to fully
 implement data-format descriptions already available elsewhere (in
 ctypes and NumPy for example).  The Python 2.5 specification is
@@ -666,8 +676,8 @@ Character         Description
 'u'               ucs-2
 'w'               ucs-4
 'O'               pointer to Python Object
-'Z'               complex (whatever the next specifier is)
-'&'               specific pointer (prefix before another character)
+'Z<specifier>'    complex (whatever the next specifier is, e.g. ``'Zd'``)
+'&<specifier>'    specific pointer (e.g. ``'&i'`` for a pointer to an int)
 'T{}'             structure (detailed layout inside {})
 '(k1,k2,...,kn)'  multi-dimensional array of whatever follows
 ':name:'          optional name of the preceding element