Return True if an item was removed, False otherwise.

Author: StanFromIreland

Doc/builtins/stdtypes.rst

@@ -1688,7 +1688,8 @@ application).
    .. method:: list.discard(value, /)
 
       Remove the first item from the list where ``list[i] == value``
-      if such an item is present.
+      if such an item is present.  Return ``True`` if an item was removed,
+      ``False`` otherwise.
 
       .. versionadded:: next
 

Doc/tutorial/datastructures.rst

@@ -47,7 +47,7 @@ of the methods of list objects:
    :noindex:
 
    Remove the first item from the list whose value is equal to *value*, if there
-   is such an item.
+   is such an item.  Return ``True`` if an item was removed, ``False`` otherwise.
 
 
 .. method:: list.pop(index=-1, /)

Doc/whatsnew/3.16.rst

@@ -108,7 +108,7 @@ Other language changes
   (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`.
+  from a list if it is present and returns whether an item was removed.
   (Contributed by Stan Ulbrych in :gh:`160724`.)
 
 

Lib/collections/__init__.py

@@ -1387,7 +1387,7 @@ def remove(self, item):
         self.data.remove(item)
 
     def discard(self, item):
-        self.data.discard(item)
+        return self.data.discard(item)
 
     def clear(self):
         self.data.clear()

Lib/test/list_tests.py

@@ -375,13 +375,13 @@ def __eq__(self, other):
 
     def test_discard(self):
         a = self.type2test([0, 0, 1])
-        a.discard(1)
+        self.assertIs(a.discard(1), True)
         self.assertEqual(a, self.type2test([0, 0]))
-        a.discard(0)
+        self.assertIs(a.discard(0), True)
         self.assertEqual(a, self.type2test([0]))
-        a.discard(0)
+        self.assertIs(a.discard(0), True)
         self.assertEqual(a, self.type2test([]))
-        a.discard(0)
+        self.assertIs(a.discard(0), False)
         self.assertEqual(a, self.type2test([]))
 
         self.assertRaises(TypeError, a.discard)

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

@@ -1,2 +1,2 @@
 Add :meth:`list.discard`, which removes the first occurrence of a value from
-a list if it is present.
+a list if it is present and returns whether an item was removed.

Objects/clinic/listobject.c.h

@@ -3520,16 +3520,19 @@ list.discard
      /
 
 Remove first occurrence of value if it is present.
+
+Return True if an item was removed, False otherwise.
 [clinic start generated code]*/
 
 static PyObject *
 list_discard_impl(PyListObject *self, PyObject *value)
-/*[clinic end generated code: output=4d8c1aee9a101f8c input=e1abe80fdc97f48e]*/
+/*[clinic end generated code: output=4d8c1aee9a101f8c input=6330bc648285d994]*/
 {
-    if (list_remove_lock_held(self, value) < 0) {
+    int res = list_remove_lock_held(self, value);
+    if (res < 0) {
         return NULL;
     }
-    Py_RETURN_NONE;
+    return PyBool_FromLong(res);
 }
 
 static int