From 57a254d56f382a0e35a410f5f45a75f451cefec8 Mon Sep 17 00:00:00 2001
From: Irit Katriel <1055913+iritkatriel@users.noreply.github.com>
Date: Sat, 1 Apr 2023 21:30:23 +0100
Subject: [PATCH] gh-102192: deprecate _PyErr_ChainExceptions (#102935)

---
 Doc/whatsnew/3.12.rst                                       | 6 ++++++
 Include/cpython/pyerrors.h                                  | 2 +-
 .../2023-03-31-12-22-25.gh-issue-102192.gYxJP_.rst          | 2 ++
 3 files changed, 9 insertions(+), 1 deletion(-)
 create mode 100644 Misc/NEWS.d/next/Core and Builtins/2023-03-31-12-22-25.gh-issue-102192.gYxJP_.rst

diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
index 6df6fb12ae7df1d..90897a163415d8b 100644
--- a/Doc/whatsnew/3.12.rst
+++ b/Doc/whatsnew/3.12.rst
@@ -978,6 +978,10 @@ New Features
   This is less error prone and a bit more efficient.
   (Contributed by Mark Shannon in :gh:`101578`.)
 
+* Add ``_PyErr_ChainExceptions1``, which takes an exception instance,
+  to replace the legacy-API ``_PyErr_ChainExceptions``, which is now
+  deprecated. (Contributed by Mark Shannon in :gh:`101578`.)
+
 * Add :c:func:`PyException_GetArgs` and :c:func:`PyException_SetArgs`
   as convenience functions for retrieving and modifying
   the :attr:`~BaseException.args` passed to the exception's constructor.
@@ -1128,6 +1132,8 @@ Deprecated
 * :c:func:`!PyErr_Display` is deprecated. Use :c:func:`PyErr_DisplayException`
   instead. (Contributed by Irit Katriel in :gh:`102755`).
 
+* ``_PyErr_ChainExceptions`` is deprecated. Use ``_PyErr_ChainExceptions1``
+  instead. (Contributed by Irit Katriel in :gh:`102192`.)
 
 Removed
 -------
diff --git a/Include/cpython/pyerrors.h b/Include/cpython/pyerrors.h
index 65bdc942f5067a8..758804ade2baa7a 100644
--- a/Include/cpython/pyerrors.h
+++ b/Include/cpython/pyerrors.h
@@ -98,7 +98,7 @@ PyAPI_FUNC(void) _PyErr_GetExcInfo(PyThreadState *, PyObject **, PyObject **, Py
 
 /* Context manipulation (PEP 3134) */
 
-PyAPI_FUNC(void) _PyErr_ChainExceptions(PyObject *, PyObject *, PyObject *);
+Py_DEPRECATED(3.12) PyAPI_FUNC(void) _PyErr_ChainExceptions(PyObject *, PyObject *, PyObject *);
 PyAPI_FUNC(void) _PyErr_ChainExceptions1(PyObject *);
 
 /* Like PyErr_Format(), but saves current exception as __context__ and
diff --git a/Misc/NEWS.d/next/Core and Builtins/2023-03-31-12-22-25.gh-issue-102192.gYxJP_.rst b/Misc/NEWS.d/next/Core and Builtins/2023-03-31-12-22-25.gh-issue-102192.gYxJP_.rst
new file mode 100644
index 000000000000000..10dd72b1abc4221
--- /dev/null
+++ b/Misc/NEWS.d/next/Core and Builtins/2023-03-31-12-22-25.gh-issue-102192.gYxJP_.rst	
@@ -0,0 +1,2 @@
+Deprecated ``_PyErr_ChainExceptions`` in favour of
+``_PyErr_ChainExceptions1``.