Add list.discard() method

Author: StanFromIreland

Doc/builtins/stdtypes.rst

@@ -1683,7 +1683,14 @@ application).
 
    Lists implement all of the :ref:`common <typesseq-common>` and
    :ref:`mutable <typesseq-mutable>` sequence operations. Lists also provide the
-   following additional method:
+   following additional methods:
+
+   .. method:: list.discard(value, /)
+
+      Remove the first item from the list where ``list[i] == value``
+      if such an item is present.
+
+      .. versionadded:: next
 
    .. method:: list.sort(*, key=None, reverse=False)
 

Doc/builtins/threadsafety.rst

@@ -165,9 +165,9 @@ intermediate states since they modify multiple elements in place:
    lst.pop(idx)           # idx not at the end of the list, shifts elements
    lst *= x               # copies elements in place
 
-The :meth:`~list.remove` method may allow concurrent modifications since
-element comparison may execute arbitrary Python code (via
-:meth:`~object.__eq__`).
+The :meth:`~list.remove` and :meth:`~list.discard` methods may allow
+concurrent modifications since element comparison may execute arbitrary
+Python code (via :meth:`~object.__eq__`).
 
 :meth:`~list.extend` is safe to call from multiple threads.  However, its
 guarantees depend on the iterable passed to it. If it is a :class:`list`, a

Doc/builtins/time-complexity.rst

@@ -47,6 +47,8 @@ If you need to add or remove at both ends, consider using a
      - *O*\ (1)
    * - Delete item (``del l[k]``) [2]_
      - *O*\ (*n* - *k*)
+   * - Discard (``l.discard(x)``, ``l.remove(x)``)
+     - *O*\ (*n*)
    * - Iteration
      - *O*\ (*n*)
    * - Get slice (``l[i:j]``)

Doc/tutorial/datastructures.rst

@@ -43,6 +43,13 @@ of the methods of list objects:
    :exc:`ValueError` if there is no such item.
 
 
+.. method:: list.discard(value, /)
+   :noindex:
+
+   Remove the first item from the list whose value is equal to *value*, if there
+   is such an item.
+
+
 .. method:: list.pop(index=-1, /)
    :noindex:
 

Doc/whatsnew/3.16.rst

@@ -107,6 +107,10 @@ Other language changes
   :func:`asyncio.print_call_graph` can see through them into the awaited code.
   (Contributed by Kumar Aditya in :gh:`157361`.)
 
+* Added :meth:`list.discard`, which removes the first occurrence of a value
+  from a list if it is present, like :meth:`set.discard`.
+  (Contributed by Stan Ulbrych in :gh:`160724`.)
+
 
 Default interactive shell
 =========================

Lib/test/test_list.py

@@ -2,7 +2,7 @@
 import sys
 import textwrap
 from test import list_tests, support
-from test.support import cpython_only
+from test.support import ALWAYS_EQ, NEVER_EQ, cpython_only
 from test.support.script_helper import assert_python_failure, assert_python_ok
 import pickle
 import unittest
@@ -331,6 +331,66 @@ def test_preallocation(self):
         self.assertEqual(iter_size, sys.getsizeof(list([0] * 10)))
         self.assertEqual(iter_size, sys.getsizeof(list(range(10))))
 
+    def test_discard(self):
+        a = [0, 0, 1]
+        a.discard(1)
+        self.assertEqual(a, [0, 0])
+        a.discard(0)
+        self.assertEqual(a, [0])
+        a.discard(0)
+        self.assertEqual(a, [])
+        a.discard(0)
+        self.assertEqual(a, [])
+
+        self.assertRaises(TypeError, a.discard)
+
+        a = [1, 2]
+        a.discard(NEVER_EQ)
+        self.assertEqual(a, [1, 2])
+        a.discard(ALWAYS_EQ)
+        self.assertEqual(a, [2])
+        a = [ALWAYS_EQ]
+        a.discard(1)
+        self.assertEqual(a, [])
+        a = [ALWAYS_EQ]
+        a.discard(NEVER_EQ)
+        self.assertEqual(a, [])
+        a = [NEVER_EQ]
+        a.discard(ALWAYS_EQ)
+        self.assertEqual(a, [NEVER_EQ])
+
+        class BadExc(Exception):
+            pass
+
+        class BadCmp:
+            def __eq__(self, other):
+                if other == 2:
+                    raise BadExc()
+                return False
+
+        a = [0, 1, 2, 3]
+        self.assertRaises(BadExc, a.discard, BadCmp())
+
+        class BadCmp2:
+            def __eq__(self, other):
+                raise BadExc()
+
+        d = list('abcdefghcij')
+        d.discard('c')
+        self.assertEqual(d, list('abdefghcij'))
+        d.discard('c')
+        self.assertEqual(d, list('abdefghij'))
+        d.discard('c')
+        self.assertEqual(d, list('abdefghij'))
+
+        # Handle comparison errors
+        d = ['a', 'b', BadCmp2(), 'c']
+        e = list(d)
+        self.assertRaises(BadExc, d.discard, 'c')
+        for x, y in zip(d, e):
+            # verify that original order and values are retained.
+            self.assertIs(x, y)
+
     def test_count_index_remove_crashes(self):
         # bpo-38610: The count(), index(), and remove() methods were not
         # holding strong references to list elements while calling
@@ -356,6 +416,9 @@ def __eq__(self, other):
         with self.assertRaises(ValueError):
             lst.remove(lst)
 
+        lst = L([X()])
+        lst.discard(lst)
+
         # bpo-39453: list.__contains__ was not holding strong references
         # to list elements while calling PyObject_RichCompareBool().
         lst = [X(), X()]

Misc/NEWS.d/next/Core_and_Builtins/2026-10-26-17-16-29.gh-issue-160724.23hdnD.rst

@@ -0,0 +1,2 @@
+Add :meth:`list.discard`, which removes the first occurrence of a value from
+a list if it is present.

Objects/clinic/listobject.c.h

@@ -3462,6 +3462,29 @@ list_count_impl(PyListObject *self, PyObject *value)
     return PyLong_FromSsize_t(count);
 }
 
+static int
+list_remove_lock_held(PyListObject *self, PyObject *value)
+{
+    Py_ssize_t i;
+
+    for (i = 0; i < Py_SIZE(self); i++) {
+        PyObject *obj = self->ob_item[i];
+        Py_INCREF(obj);
+        int cmp = PyObject_RichCompareBool(obj, value, Py_EQ);
+        Py_DECREF(obj);
+        if (cmp > 0) {
+            if (list_ass_slice_lock_held(self, i, i+1, NULL) < 0) {
+                return -1;
+            }
+            return 1;
+        }
+        else if (cmp < 0) {
+            return -1;
+        }
+    }
+    return 0;
+}
+
 /*[clinic input]
 @critical_section
 list.remove
@@ -3478,23 +3501,35 @@ static PyObject *
 list_remove_impl(PyListObject *self, PyObject *value)
 /*[clinic end generated code: output=b9b76a6633b18778 input=26c813dbb95aa93b]*/
 {
-    Py_ssize_t i;
+    int res = list_remove_lock_held(self, value);
+    if (res < 0) {
+        return NULL;
+    }
+    if (res == 0) {
+        PyErr_SetString(PyExc_ValueError, "list.remove(x): x not in list");
+        return NULL;
+    }
+    Py_RETURN_NONE;
+}
 
-    for (i = 0; i < Py_SIZE(self); i++) {
-        PyObject *obj = self->ob_item[i];
-        Py_INCREF(obj);
-        int cmp = PyObject_RichCompareBool(obj, value, Py_EQ);
-        Py_DECREF(obj);
-        if (cmp > 0) {
-            if (list_ass_slice_lock_held(self, i, i+1, NULL) == 0)
-                Py_RETURN_NONE;
-            return NULL;
-        }
-        else if (cmp < 0)
-            return NULL;
+/*[clinic input]
+@critical_section
+list.discard
+
+     value: object
+     /
+
+Remove first occurrence of value if it is present.
+[clinic start generated code]*/
+
+static PyObject *
+list_discard_impl(PyListObject *self, PyObject *value)
+/*[clinic end generated code: output=4d8c1aee9a101f8c input=e1abe80fdc97f48e]*/
+{
+    if (list_remove_lock_held(self, value) < 0) {
+        return NULL;
     }
-    PyErr_SetString(PyExc_ValueError, "list.remove(x): x not in list");
-    return NULL;
+    Py_RETURN_NONE;
 }
 
 static int
@@ -3685,6 +3720,7 @@ static PyMethodDef list_methods[] = {
     LIST_EXTEND_METHODDEF
     LIST_POP_METHODDEF
     LIST_REMOVE_METHODDEF
+    LIST_DISCARD_METHODDEF
     LIST_INDEX_METHODDEF
     LIST_COUNT_METHODDEF
     LIST_REVERSE_METHODDEF