gh-146175: Soft-deprecate outdated macros; convert internal usage

Author: encukou

Doc/c-api/intro.rst

@@ -526,14 +526,26 @@ to the C language.
 Outdated macros
 ---------------
 
-The following macros have been used to features that have been standardized
-in C11.
+The following :term:`soft deprecated` macros have been used to features that
+have been standardized in C11 (or previous standards).
 
 .. c:macro:: Py_ALIGNED(num)
 
-   Specify alignment to *num* bytes on compilers that support it.
+   On some GCC-like compilers, specify alignment to *num* bytes.
+   This does nothing on other compilers.
 
-   Consider using the C11 standard ``_Alignas`` specifier over this macro.
+   Use the standard ``alignas`` specifier rather than this macro.
+
+   .. deprecated:: next
+      The macro is :term:`soft deprecated`.
+
+.. c:macro:: PY_FORMAT_SIZE_T
+
+   The :c:func:`printf` formatting modifier for :c:type:`size_t`.
+   Use ``"z"`` directly instead.
+
+   .. deprecated:: next
+      The macro is :term:`soft deprecated`.
 
 .. c:macro:: Py_LL(number)
              Py_ULL(number)
@@ -546,6 +558,38 @@ in C11.
 
    Consider using the C99 standard suffixes ``LL`` and ``LLU`` directly.
 
+   .. deprecated:: next
+      The macro is :term:`soft deprecated`.
+
+.. c:macro:: PY_LONG_LONG
+             PY_INT32_T
+             PY_UINT32_T
+             PY_INT64_T
+             PY_UINT64_T
+
+   Aliases for the types :c:type:`!long long`, :c:type:`!int32_t`,
+   :c:type:`!uint32_t`. :c:type:`!int64_t` and :c:type:`!uint64_t`,
+   respectively.
+   Historically, these types needed compiler-specific extensions.
+
+   .. deprecated:: next
+      These macros are :term:`soft deprecated`.
+
+.. c:macro:: PY_LLONG_MIN
+             PY_LLONG_MAX
+             PY_ULLONG_MAX
+             PY_SIZE_MAX
+
+   Aliases for the values :c:macro:`!LLONG_MIN`, :c:macro:`!LLONG_MAX`,
+   :c:macro:`!ULLONG_MAX`, and :c:macro:`!SIZE_MAX`, respectively.
+   Use these standard names instead.
+
+   The required header, ``<limits.h>``,
+   :ref:`is included <capi-system-includes>` in ``Python.h``.
+
+   .. deprecated:: next
+      These macros are :term:`soft deprecated`.
+
 .. c:macro:: Py_MEMCPY(dest, src, n)
 
    This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
@@ -554,6 +598,25 @@ in C11.
    .. deprecated:: 3.14
       The macro is :term:`soft deprecated`.
 
+.. c:macro:: Py_UNICODE_SIZE
+
+   Size of the :c:type:`!wchar_t` type.
+   Use ``sizeof(wchar_t)`` or ``WCHAR_WIDTH/8`` instead.
+
+   The required header for the latter, ``<limits.h>``,
+   :ref:`is included <capi-system-includes>` in ``Python.h``.
+
+   .. deprecated:: next
+      The macro is :term:`soft deprecated`.
+
+.. c:macro:: Py_UNICODE_WIDE
+
+   Defined if ``wchar_t`` can hold a Unicode character (UCS-4).
+   Use ``sizeof(wchar_t) >= 4`` instead
+
+   .. deprecated:: next
+      The macro is :term:`soft deprecated`.
+
 .. c:macro:: Py_VA_COPY
 
    This is a :term:`soft deprecated` alias to the C99-standard ``va_copy``
@@ -564,6 +627,9 @@ in C11.
    .. versionchanged:: 3.6
       This is now an alias to ``va_copy``.
 
+   .. deprecated:: next
+      The macro is :term:`soft deprecated`.
+
 
 .. _api-objects:
 

Doc/deprecations/c-api-pending-removal-in-3.15.rst

@@ -7,8 +7,6 @@ Pending removal in Python 3.15
   Use :c:func:`PyWeakref_GetRef` instead. The `pythoncapi-compat project
   <https://github.com/python/pythoncapi-compat/>`__ can be used to get
   :c:func:`PyWeakref_GetRef` on Python 3.12 and older.
-* :c:type:`Py_UNICODE` type and the :c:macro:`!Py_UNICODE_WIDE` macro:
-  Use :c:type:`wchar_t` instead.
 * :c:func:`!PyUnicode_AsDecodedObject`:
   Use :c:func:`PyCodec_Decode` instead.
 * :c:func:`!PyUnicode_AsDecodedUnicode`:

Doc/whatsnew/3.15.rst

@@ -1861,6 +1861,24 @@ Deprecated C APIs
   use the C11 standard ``<math.h>`` :c:macro:`!INFINITY` instead.
   (Contributed by Sergey B Kirpichev in :gh:`141004`.)
 
+* The following macros are :term:`soft deprecated`:
+
+  - :c:macro:`Py_ALIGNED`: Prefer ``alignas`` instead.
+  - :c:macro:`PY_FORMAT_SIZE_T`: Use ``"z"`` directly.
+  - :c:macro:`Py_LL` & :c:macro:`Py_ULL`:
+    Use standard suffixes, ``LL`` & ``ULL``.
+  - :c:macro:`PY_LONG_LONG`, :c:macro:`PY_LLONG_MIN`, :c:macro:`PY_LLONG_MAX`,
+    :c:macro:`PY_ULLONG_MAX`, :c:macro:`PY_INT32_T`, :c:macro:`PY_UINT32_T`,
+    :c:macro:`PY_INT64_T`, :c:macro:`PY_UINT64_T`, :c:macro:`PY_SIZE_MAX`:
+    Use C99 types/limits.
+  - :c:macro:`Py_UNICODE_SIZE`: Use ``sizeof(wchar_t)`` directly.
+  - :c:macro:`Py_VA_COPY`: Use ``va_copy`` directly.
+
+  The macro :c:macro:`Py_UNICODE_WIDE`, which was scheduled for removal,
+  is :term:`soft deprecated` instead.
+
+  (Contributed by Petr Viktorin in :gh:`146175`.)
+
 * :c:macro:`!Py_MATH_El` and :c:macro:`!Py_MATH_PIl` are deprecated
   since 3.15 and will be removed in 3.20.
   (Contributed by Sergey B Kirpichev in :gh:`141004`.)

Include/internal/pycore_object.h

@@ -144,7 +144,7 @@ static inline void _Py_RefcntAdd(PyObject* op, Py_ssize_t n)
         new_refcnt = _Py_IMMORTAL_INITIAL_REFCNT;
     }
 #  if SIZEOF_VOID_P > 4
-    op->ob_refcnt = (PY_UINT32_T)new_refcnt;
+    op->ob_refcnt = (uint32_t)new_refcnt;
 #  else
     op->ob_refcnt = new_refcnt;
 #  endif

Include/object.h

@@ -127,7 +127,7 @@ whose size is determined when the object is allocated.
 struct _object {
     _Py_ANONYMOUS union {
 #if SIZEOF_VOID_P > 4
-        PY_INT64_T ob_refcnt_full; /* This field is needed for efficient initialization with Clang on ARM */
+        int64_t ob_refcnt_full; /* This field is needed for efficient initialization with Clang on ARM */
         struct {
 #  if PY_BIG_ENDIAN
             uint16_t ob_flags;

Include/pyport.h

@@ -446,7 +446,9 @@ extern "C" {
 /*
  * Specify alignment on compilers that support it.
  */
-#if defined(__GNUC__) && __GNUC__ >= 3
+#ifdef Py_BUILD_CORE
+// always use _Py_ALIGNED_DEF instead
+#elif defined(__GNUC__) && __GNUC__ >= 3
 #define Py_ALIGNED(x) __attribute__((aligned(x)))
 #else
 #define Py_ALIGNED(x)

Include/refcount.h

@@ -126,7 +126,7 @@ static inline Py_ALWAYS_INLINE int _Py_IsImmortal(PyObject *op)
     return (_Py_atomic_load_uint32_relaxed(&op->ob_ref_local) ==
             _Py_IMMORTAL_REFCNT_LOCAL);
 #elif SIZEOF_VOID_P > 4
-    return _Py_CAST(PY_INT32_T, op->ob_refcnt) < 0;
+    return _Py_CAST(int32_t, op->ob_refcnt) < 0;
 #else
     return op->ob_refcnt >= _Py_IMMORTAL_MINIMUM_REFCNT;
 #endif
@@ -164,7 +164,7 @@ static inline void Py_SET_REFCNT(PyObject *ob, Py_ssize_t refcnt) {
     }
 #ifndef Py_GIL_DISABLED
 #if SIZEOF_VOID_P > 4
-    ob->ob_refcnt = (PY_UINT32_T)refcnt;
+    ob->ob_refcnt = (uint32_t)refcnt;
 #else
     ob->ob_refcnt = refcnt;
 #endif
@@ -278,7 +278,7 @@ static inline Py_ALWAYS_INLINE void Py_INCREF(PyObject *op)
         _Py_atomic_add_ssize(&op->ob_ref_shared, (1 << _Py_REF_SHARED_SHIFT));
     }
 #elif SIZEOF_VOID_P > 4
-    PY_UINT32_T cur_refcnt = op->ob_refcnt;
+    uint32_t cur_refcnt = op->ob_refcnt;
     if (cur_refcnt >= _Py_IMMORTAL_INITIAL_REFCNT) {
         // the object is immortal
         _Py_INCREF_IMMORTAL_STAT_INC();
@@ -387,7 +387,7 @@ static inline void Py_DECREF(const char *filename, int lineno, PyObject *op)
 #if SIZEOF_VOID_P > 4
     /* If an object has been freed, it will have a negative full refcnt
      * If it has not it been freed, will have a very large refcnt */
-    if (op->ob_refcnt_full <= 0 || op->ob_refcnt > (((PY_UINT32_T)-1) - (1<<20))) {
+    if (op->ob_refcnt_full <= 0 || op->ob_refcnt > (((uint32_t)-1) - (1<<20))) {
 #else
     if (op->ob_refcnt <= 0) {
 #endif

Include/unicodeobject.h

@@ -64,13 +64,9 @@ Copyright (c) Corporation for National Research Initiatives.
 #error Must define SIZEOF_WCHAR_T
 #endif
 
+/* Soft-deprecated defines */
 #define Py_UNICODE_SIZE SIZEOF_WCHAR_T
-
-/* If wchar_t can be used for UCS-4 storage, set Py_UNICODE_WIDE.
-   Otherwise, Unicode strings are stored as UCS-2 (with limited support
-   for UTF-16) */
-
-#if Py_UNICODE_SIZE >= 4
+#if SIZEOF_WCHAR_T >= 4
 #define Py_UNICODE_WIDE
 #endif
 

Misc/NEWS.d/next/C_API/2026-03-19-16-50-27.gh-issue-146175.pISQGX.rst

@@ -0,0 +1,12 @@
+The following macros are :term:`soft deprecated`:
+:c:macro:`Py_ALIGNED`,
+:c:macro:`PY_FORMAT_SIZE_T`,
+:c:macro:`Py_LL`, :c:macro:`Py_ULL`,
+:c:macro:`PY_LONG_LONG`, :c:macro:`PY_LLONG_MIN`, :c:macro:`PY_LLONG_MAX`,
+:c:macro:`PY_ULLONG_MAX`, :c:macro:`PY_INT32_T`, :c:macro:`PY_UINT32_T`,
+:c:macro:`PY_INT64_T`, :c:macro:`PY_UINT64_T`, :c:macro:`PY_SIZE_MAX`,
+:c:macro:`Py_UNICODE_SIZE`,
+:c:macro:`Py_VA_COPY`.
+
+The macro :c:macro:`Py_UNICODE_WIDE`, which was scheduled for removal, is
+:term:`soft deprecated` instead.

Modules/_io/stringio.c

@@ -111,7 +111,7 @@ resize_buffer(stringio *self, size_t size)
         alloc = size + 1;
     }
 
-    if (alloc > PY_SIZE_MAX / sizeof(Py_UCS4))
+    if (alloc > SIZE_MAX / sizeof(Py_UCS4))
         goto overflow;
     new_buf = (Py_UCS4 *)PyMem_Realloc(self->buf, alloc * sizeof(Py_UCS4));
     if (new_buf == NULL) {