Issue #10516: adding list.clear() and list.copy() methods

Doc/library/stdtypes.rst

@@ -1642,6 +1642,8 @@ Note that while lists allow their items to be of any type, bytearray object
    single: append() (sequence method)
    single: extend() (sequence method)
    single: count() (sequence method)
+   single: clear() (sequence method)
+   single: copy() (sequence method)
    single: index() (sequence method)
    single: insert() (sequence method)
    single: pop() (sequence method)
@@ -1673,6 +1675,12 @@ Note that while lists allow their items to be of any type, bytearray object
 | ``s.extend(x)``              | same as ``s[len(s):len(s)] =   | \(2)                |
 |                              | x``                            |                     |
 +------------------------------+--------------------------------+---------------------+
+| ``s.clear()``                | remove all items from ``s``    | \(8)                |
+|                              |                                |                     |
++------------------------------+--------------------------------+---------------------+
+| ``s.copy()``                 | return a shallow copy of ``s`` | \(8)                |
+|                              |                                |                     |
++------------------------------+--------------------------------+---------------------+
 | ``s.count(x)``               | return number of *i*'s for     |                     |
 |                              | which ``s[i] == x``            |                     |
 +------------------------------+--------------------------------+---------------------+
@@ -1749,7 +1757,11 @@ Notes:
       detect that the list has been mutated during a sort.
 
 (8)
-   :meth:`sort` is not supported by :class:`bytearray` objects.
+   :meth:`clear`, :meth:`!copy` and :meth:`sort` are not supported by
+   :class:`bytearray` objects.
+
+    .. versionadded:: 3.3
+       :meth:`clear` and :meth:`!copy` methods.
 
 
 .. _bytes-methods:

Lib/collections/__init__.py

@@ -844,6 +844,8 @@ class UserList(MutableSequence):
     def insert(self, i, item): self.data.insert(i, item)
     def pop(self, i=-1): return self.data.pop(i)
     def remove(self, item): self.data.remove(item)
+    def clear(self): self.data.clear()
+    def copy(self): return self.data.copy()
     def count(self, item): return self.data.count(item)
     def index(self, item, *args): return self.data.index(item, *args)
     def reverse(self): self.data.reverse()

Lib/test/list_tests.py

@@ -425,6 +425,48 @@ class CommonTest(seq_tests.CommonTest):
 
         self.assertRaises(TypeError, u.reverse, 42)
 
+    def test_clear(self):
+        u = self.type2test([2, 3, 4])
+        u.clear()
+        self.assertEqual(u, [])
+
+        u = self.type2test([])
+        u.clear()
+        self.assertEqual(u, [])
+
+        u = self.type2test([])
+        u.append(1)
+        u.clear()
+        u.append(2)
+        self.assertEqual(u, [2])
+
+        self.assertRaises(TypeError, u.clear, None)
+
+    def test_copy(self):
+        u = self.type2test([1, 2, 3])
+        v = u.copy()
+        self.assertEqual(v, [1, 2, 3])
+
+        u = self.type2test([])
+        v = u.copy()
+        self.assertEqual(v, [])
+
+        # test that it's indeed a copy and not a reference
+        u = self.type2test(['a', 'b'])
+        v = u.copy()
+        v.append('i')
+        self.assertEqual(u, ['a', 'b'])
+        self.assertEqual(v, u + ['i'])
+
+        # test that it's a shallow, not a deep copy
+        u = self.type2test([1, 2, [3, 4], 5])
+        v = u.copy()
+        v[2].append(666)
+        self.assertEqual(u, [1, 2, [3, 4, 666], 5])
+        self.assertEqual(u, v)
+
+        self.assertRaises(TypeError, u.copy, None)
+
     def test_sort(self):
         u = self.type2test([1, 0])
         u.sort()

Lib/test/test_descrtut.py

@@ -199,6 +199,8 @@ You can get the information from the list type:
      '__str__',
      '__subclasshook__',
      'append',
+     'clear',
+     'copy',
      'count',
      'extend',
      'index',

Misc/NEWS

@@ -30,6 +30,8 @@ Core and Builtins
 
 - Check for NULL result in PyType_FromSpec.
 
+- Issue #10516: New copy() and clear() methods for lists.
+
 Library
 -------
 

Objects/listobject.c

@@ -746,6 +746,19 @@ listinsert(PyListObject *self, PyObject *args)
     return NULL;
 }
 
+static PyObject *
+listclear(PyListObject *self)
+{
+    list_clear(self);
+    Py_RETURN_NONE;
+}
+
+static PyObject *
+listcopy(PyListObject *self)
+{
+    return list_slice(self, 0, Py_SIZE(self));
+}
+
 static PyObject *
 listappend(PyListObject *self, PyObject *v)
 {
@@ -2322,6 +2335,10 @@ PyDoc_STRVAR(reversed_doc,
 "L.__reversed__() -- return a reverse iterator over the list");
 PyDoc_STRVAR(sizeof_doc,
 "L.__sizeof__() -- size of L in memory, in bytes");
+PyDoc_STRVAR(clear_doc,
+"L.clear() -> None -- remove all items from L");
+PyDoc_STRVAR(copy_doc,
+"L.copy() -> list -- a shallow copy of L");
 PyDoc_STRVAR(append_doc,
 "L.append(object) -- append object to end");
 PyDoc_STRVAR(extend_doc,
@@ -2350,9 +2367,11 @@ static PyMethodDef list_methods[] = {
     {"__getitem__", (PyCFunction)list_subscript, METH_O|METH_COEXIST, getitem_doc},
     {"__reversed__",(PyCFunction)list_reversed, METH_NOARGS, reversed_doc},
     {"__sizeof__",  (PyCFunction)list_sizeof, METH_NOARGS, sizeof_doc},
+    {"clear",           (PyCFunction)listclear,   METH_NOARGS, clear_doc},
+    {"copy",            (PyCFunction)listcopy,   METH_NOARGS, copy_doc},
     {"append",          (PyCFunction)listappend,  METH_O, append_doc},
     {"insert",          (PyCFunction)listinsert,  METH_VARARGS, insert_doc},
-    {"extend",      (PyCFunction)listextend,  METH_O, extend_doc},
+    {"extend",          (PyCFunction)listextend,  METH_O, extend_doc},
     {"pop",             (PyCFunction)listpop,     METH_VARARGS, pop_doc},
     {"remove",          (PyCFunction)listremove,  METH_O, remove_doc},
     {"index",           (PyCFunction)listindex,   METH_VARARGS, index_doc},