gh-124665: add _PyCodec_UnregisterError and _codecs._unregister_error

Doc/c-api/codec.rst

@@ -97,6 +97,22 @@ Registry API for Unicode encoding error handlers
 
    Return ``0`` on success, ``-1`` on error.
 
+.. c:function:: int PyCodec_UnregisterError(const char *name)
+
+   Un-register the error handling callback function error under the given error
+   policy *name*. :ref:`Standard error policies <error-handlers>` cannot be
+   un-registered.
+
+   * Return ``-1`` and set a :exc:`ValueError` exception if *name* is a
+     standard error policy or if an error occurred (in which case the
+     existing exception is propagated).
+
+   * Return ``0`` if no error handler is associated with the given error policy.
+
+   * Return ``1`` if the error handler was successfully removed.
+
+   .. versionadded:: 3.14
+
 .. c:function:: PyObject* PyCodec_LookupError(const char *name)
 
    Lookup the error handling callback function registered under *name*.  As a

Doc/data/refcounts.dat

@@ -318,6 +318,9 @@ PyCodec_RegisterError:int:::
 PyCodec_RegisterError:const char*:name::
 PyCodec_RegisterError:PyObject*:error:+1:
 
+PyCodec_UnregisterError:int:::
+PyCodec_UnregisterError:const char*:name::
+
 PyCodec_LookupError:PyObject*::+1:
 PyCodec_LookupError:const char*:name::
 

Doc/library/codecs.rst

@@ -439,6 +439,17 @@ handler:
    replacement from the error handler will be put into the output directly.
 
 
+.. function:: unregister_error(name)
+
+   Attempt to un-register the error handling function under the name *name*.
+
+   This raises a :exc:`ValueError` if *name* denotes a standard error policy
+   as specified above. Otherwise, this returns ``True`` if an error handler
+   existed for the given *name* and ``False`` otherwise.
+
+   .. versionadded:: 3.14
+
+
 Previously registered error handlers (including the standard error handlers)
 can be looked up by name:
 

Doc/whatsnew/3.14.rst

@@ -216,6 +216,13 @@ ast
   (Contributed by Irit Katriel in :gh:`123958`.)
 
 
+codecs
+------
+
+* Added :func:`codecs.unregister_error` to un-register custom error handlers.
+  (Contributed by Bénédikt Tran in :gh:`124665`.)
+
+
 ctypes
 ------
 
@@ -672,6 +679,10 @@ New Features
   <https://peps.python.org/pep-0630/#type-checking>`__ mentioned in :pep:`630`
   (:gh:`124153`).
 
+* Add :c:func:`PyCodec_UnregisterError` to the limited C API to un-register
+  custom error handlers.
+  (Contributed by Bénédikt Tran in :gh:`124665`.)
+
 
 Porting to Python 3.14
 ----------------------

Include/codecs.h

@@ -141,6 +141,18 @@ PyAPI_FUNC(PyObject *) PyCodec_StreamWriter(
    Return 0 on success, -1 on error */
 PyAPI_FUNC(int) PyCodec_RegisterError(const char *name, PyObject *error);
 
+#if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030e0000
+/* Un-register the error handling callback function error under the given
+   name. Only non-native error handlers can be un-registered.
+
+   - Return -1 and set an exception if 'name' is a native error policy, or
+     if an error occurred.
+   - Return 0 if no error handler is associated with the given error policy.
+   - Return 1 if the error handler was successfully removed.
+*/
+PyAPI_FUNC(int) PyCodec_UnregisterError(const char *name);
+#endif
+
 /* Lookup the error handling callback function registered under the given
    name. As a special case NULL can be passed, in which case
    the error handling callback for "strict" will be returned. */

Lib/test/test_codeccallbacks.py

@@ -1235,6 +1235,31 @@ class FakeUnicodeError(Exception):
                     with self.assertRaises((TypeError, FakeUnicodeError)):
                         handler(FakeUnicodeError())
 
+    def test_reject_unregister_native_error_policy(self):
+        for policy in [
+            'strict', 'ignore', 'replace', 'backslashreplace', 'namereplace',
+            'xmlcharrefreplace', 'surrogateescape', 'surrogatepass',
+        ]:
+            with self.subTest(f'reject native {policy!r} un-registration'):
+                self.assertRaises(ValueError, codecs.unregister_error, policy)
+
+    def test_unregister_custom_error_policy(self):
+        def custom_handler(exc):
+            raise exc
+
+        custom_name = f'test.test_unregister_error.custom.{id(self)}'
+        self.assertRaises(LookupError, codecs.lookup_error, custom_name)
+        codecs.register_error(custom_name, custom_handler)
+        self.assertIs(codecs.lookup_error(custom_name), custom_handler)
+        self.assertTrue(codecs.unregister_error(custom_name))
+        self.assertRaises(LookupError, codecs.lookup_error, custom_name)
+
+    def test_unregister_custom_unknown_error_policy(self):
+        unknown_name = f'test.test_unregister_error.custom.{id(self)}.unknown'
+        self.assertRaises(LookupError, codecs.lookup_error, unknown_name)
+        self.assertFalse(codecs.unregister_error(unknown_name))
+        self.assertRaises(LookupError, codecs.lookup_error, unknown_name)
+
 
 if __name__ == "__main__":
     unittest.main()

Misc/NEWS.d/next/C_API/2024-09-27-17-09-49.gh-issue-124665.KW2F8D.rst

@@ -0,0 +1,2 @@
+Add :c:func:`PyCodec_UnregisterError` to the limited C API to un-register
+custom error handlers. Patch by Bénédikt Tran.

Misc/NEWS.d/next/Library/2024-09-27-17-09-25.gh-issue-124665.qiMUai.rst

@@ -0,0 +1,2 @@
+Added :func:`codecs.unregister_error` to un-register custom error handlers.
+Patch by Bénédikt Tran.

Misc/stable_abi.toml

@@ -2510,6 +2510,8 @@
     added = '3.14'
 [function.Py_REFCNT]
     added = '3.14'
+[function.PyCodec_UnregisterError]
+    added = '3.14'
 [function.PyIter_NextItem]
     added = '3.14'
 [function.PyLong_FromInt32]

Modules/_codecsmodule.c

@@ -979,6 +979,26 @@ _codecs_register_error_impl(PyObject *module, const char *errors,
     Py_RETURN_NONE;
 }
 
+/*[clinic input]
+_codecs.unregister_error -> bool
+    errors: str
+    /
+
+Un-register the specified error handler under the name errors.
+
+Only custom handlers can be un-registered. Returns True if the
+handler has been successfully un-registered, and False if the
+errors policy is not recognized. An exception is raised when
+the errors policy is not allowed.
+[clinic start generated code]*/
+
+static int
+_codecs_unregister_error_impl(PyObject *module, const char *errors)
+/*[clinic end generated code: output=d8c1418e402aecdf input=103c9dae16f32e08]*/
+{
+    return PyCodec_UnregisterError(errors);
+}
+
 /*[clinic input]
 _codecs.lookup_error
     name: str
@@ -1044,6 +1064,7 @@ static PyMethodDef _codecs_functions[] = {
     _CODECS_CODE_PAGE_ENCODE_METHODDEF
     _CODECS_CODE_PAGE_DECODE_METHODDEF
     _CODECS_REGISTER_ERROR_METHODDEF
+    _CODECS_UNREGISTER_ERROR_METHODDEF
     _CODECS_LOOKUP_ERROR_METHODDEF
     {NULL, NULL}                /* sentinel */
 };