gh-139482: Add posix.clearenv() function

Author: vstinner

Lib/os.py

@@ -768,6 +768,12 @@ def __ror__(self, other):
         new.update(self)
         return new
 
+    if _exists("clearenv"):
+        def clear(self):
+            clearenv()
+            self._data.clear()
+
+
 def _create_environ_mapping():
     if name == 'nt':
         # Where Env Var Names Must Be UPPERCASE

Lib/test/test_os/test_os.py

@@ -1494,6 +1494,14 @@ def test_reload_environ(self):
             self.assertNotIn(b'test_env', os.environb)
             self.assertNotIn('test_env', os.environ)
 
+    def test_clearenv(self):
+        os.environ['REMOVEME'] = '1'
+        os.environ.clear()
+        self.assertEqual(os.environ, {})
+
+        self.assertRaises(TypeError, os.environ.clear, None)
+
+
 class WalkTests(unittest.TestCase):
     """Tests for os.walk()."""
     is_fwalk = False

Misc/NEWS.d/next/Library/2025-10-11-20-03-13.gh-issue-139482.du2Stg.rst

@@ -0,0 +1,2 @@
+Optimize :data:`os.environ.clear() <os.environ>` by calling ``clearenv()``
+when this function is available. Patch by Victor Stinner.

Modules/clinic/posixmodule.c.h

@@ -13201,6 +13201,25 @@ os_unsetenv_impl(PyObject *module, PyObject *name)
 #endif /* !MS_WINDOWS */
 
 
+#ifdef HAVE_CLEARENV
+/*[clinic input]
+os.clearenv
+[clinic start generated code]*/
+
+static PyObject *
+os_clearenv_impl(PyObject *module)
+/*[clinic end generated code: output=417e500890b2b9cf input=04ce6a2cb66ec46e]*/
+{
+    errno = 0;
+    int err = clearenv();
+    if (err) {
+        return posix_error();
+    }
+    Py_RETURN_NONE;
+}
+#endif
+
+
 /*[clinic input]
 os.strerror
 
@@ -17167,6 +17186,7 @@ static PyMethodDef posix_methods[] = {
     OS_POSIX_FADVISE_METHODDEF
     OS_PUTENV_METHODDEF
     OS_UNSETENV_METHODDEF
+    OS_CLEARENV_METHODDEF
     OS_STRERROR_METHODDEF
     OS_FCHDIR_METHODDEF
     OS_FSYNC_METHODDEF

Modules/posixmodule.c

@@ -5226,7 +5226,8 @@ fi
 
 # checks for library functions
 AC_CHECK_FUNCS([ \
-  accept4 alarm bind_textdomain_codeset chmod chown clock closefrom close_range confstr \
+  accept4 alarm bind_textdomain_codeset chmod chown clearenv \
+  clock closefrom close_range confstr \
   copy_file_range ctermid dladdr dup dup3 execv explicit_bzero explicit_memset \
   faccessat fchmod fchmodat fchown fchownat fdopendir fdwalk fexecve \
   fork fork1 fpathconf fstatat ftime ftruncate futimens futimes futimesat \
@@ -8173,7 +8174,7 @@ PY_STDLIB_MOD([xxlimited_35], [test "$TEST_MODULES" = yes], [test "$ac_cv_func_d
 
 # Determine JIT stencils header files based on target platform
 JIT_STENCILS_H=""
-AS_VAR_IF([enable_experimental_jit], [no], 
+AS_VAR_IF([enable_experimental_jit], [no],
   [],
   [case "$host" in
     aarch64-apple-darwin*)

configure

@@ -141,6 +141,9 @@
 /* Define if you have the 'chroot' function. */
 #undef HAVE_CHROOT
 
+/* Define to 1 if you have the 'clearenv' function. */
+#undef HAVE_CLEARENV
+
 /* Define to 1 if you have the 'clock' function. */
 #undef HAVE_CLOCK