diff --git a/peps/pep-0851.rst b/peps/pep-0851.rst index b5c411f07a4..e2b0c2bd7f1 100644 --- a/peps/pep-0851.rst +++ b/peps/pep-0851.rst @@ -15,8 +15,9 @@ Abstract Add ``list.discard(x)``, which removes the first item equal to *x* if one is present and does nothing otherwise, returning whether an item was -removed. It is the non-raising counterpart to :meth:`list.remove`, as -:meth:`set.discard` is to :meth:`set.remove`. +removed. It is the non-raising counterpart to :meth:`list.remove`, which +currently has none. The name is taken from :meth:`set.discard`, which +already means "remove if present" in Python. Motivation @@ -79,16 +80,15 @@ method for consistency. Rationale ========= -The name follows the ``remove()`` / ``discard()`` distinction already -made by ``set``, where ``discard()`` is the variant that tolerates a -missing item. It has been raised that after ``s.discard(x)`` the test -``x not in s`` holds, while after ``lst.discard(x)`` it need not if *x* -appears more than once. This is a real difference. ``discard()`` -deliberately shares the search and removal semantics of :meth:`list.remove` -rather than those of :meth:`set.discard`, and the documentation for -``list.discard()`` in the reference implementation states this explicitly. -The name remains the least surprising choice as users who know -sets can apply that knowledge directly. +Symmetry with :class:`set` is not the goal. The motivation is the missing +non-raising form of :meth:`list.remove`. :class:`set` only supplies the name, +since :meth:`set.discard` already means "remove if present" in Python. + +It has been raised that after ``s.discard(x)`` the test ``x not in s`` +holds, while after ``lst.discard(x)`` it need not if *x* appears more than +once. That is a property of sets, not of ``discard()``, and +:meth:`list.remove` has the same behaviour today. ``discard()`` follows +``remove()`` here, and its will documentation clearly say so. Unlike :meth:`set.discard`, which returns ``None``, a bool is returned. This costs nothing, since the implementation already knows the outcome, and lets