Add words on anonymous unions

Author: encukou

peps/pep-0820.rst

@@ -14,8 +14,10 @@ Post-History: `06-Jan-2026 <https://discuss.python.org/t/105552>`__
 Abstract
 ========
 
-Replace type and module slots with a new, more type-safe structure that allows
-adding new slots in a more forward-compatible way.
+Replace type and module slots with a new structure: a tagged anonymous
+union with flags.
+This improves type safety and allows adding new slots
+in a more forward-compatible way.
 
 API added in 3.15 (:external+py3.15:c:func:`PyModule_FromSlotsAndSpec` and the
 new :external+py3.15:ref:`extension export hook <extension-export-hook>`)
@@ -662,6 +664,43 @@ Note that slots are not a good way for *extension modules* to add extra data
 to types or modules, as there is no API to retrieve the slots used to create
 a specific object.
 
+Avoiding anonymous unions
+-------------------------
+
+This PEP proposes a struct with *anonymous unions*, which are not yet used in
+CPython's documented public API.
+
+There is no known issue with adding these, but the following notes may
+be relevant:
+
+- Anonymous unions are only supported in C since C11.
+  But, CPython already requires the feature, and uses it for internal members
+  of the ``PyObject`` struct.
+
+- Until C++20, which adds C-style designated initializers, C++ initializers
+  only allow setting the first member of a union.
+  However, this is an issue for *named* unions as well.
+  Avoiding unions entirely would mean losing most of the type-safety
+  improvements of this PEP.
+
+  Note that the proposed flag ``PySlot_INTPTR``, and the workaround macros
+  ``PySlot_PTR`` & ``PySlot_PTR_STATIC``, allow using this API in
+  code that needs to be compatible with C++11 or has similar union-related
+  limitations.
+
+- C++ doesn't have anonymous *structs*.
+  This might surprise C programmers for whom anonymous structs/unions are
+  a single language feature.
+
+- Non-C/C++ language wrappers may need to give the union a name.
+  This is fine.
+  (Dear reader: if you need this, please open a CPython issue about
+  exposing a preferred name in headers and documentation.)
+
+For a bigger picture: anonymous unions can be a helpful tool for implemeting
+tagged unions and for evolving public API in backwards-compatible ways.
+This PEP intentionally opens the door to using them more often.
+
 
 Open Issues
 ===========
@@ -672,8 +711,8 @@ None yet.
 Acknowledgements
 ================
 
-Thanks to Da Woods and Antoine Pitrou for substantial input on this iteration
-of the proposal.
+Thanks to Da Woods, Antoine Pitrou and Mark Shannon
+for substantial input on this iteration of the proposal.
 
 
 Copyright