{"title":"List Methods","description":"","content":"Lists ship with a built-in toolkit of methods for adding items, removing them, finding them, and emptying the whole thing out. This lesson covers the methods you'll reach for daily: `append`, `extend`, `insert`, `remove`, `pop`, `index`, `count`, `clear`, and `reverse`. Each one has a behavior quirk worth knowing (some mutate in place, some raise, some look cheap but aren't) and we'll work through each in an e-commerce setting: a shopping cart that fills up, loses unavailable items, and gets searched.\n\n---\n\n# append: Adding One Item to the End\n\n`append(x)` adds a single item to the end of the list. It mutates the list in place and returns `None`.\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\"]\ncart.append(\"HDMI Cable\")\n\nprint(cart)\n```\n\n\nThe cart now has three items, in the order they were added. `append` takes exactly one argument, and that argument becomes one new element. If you pass a list, the whole list becomes a single element:\n\n\n```python\ncart = [\"Wireless Mouse\"]\ncart.append([\"USB Cable\", \"HDMI Cable\"])\n\nprint(cart)\n```\n\n\nThe cart now has two elements: a string and a nested list. If you wanted to add two cables as separate items, `append` is the wrong tool. Reach for `extend` instead.\n\n\n> **INFO**\n>\n> **Cost:** `append` is O(1) amortized. Python lists keep some spare capacity at the end, so most appends are constant-time. Every so often the list grows its underlying storage, which is O(n), but spread across many calls the average per-append cost stays constant.\n\n\nA common bug worth flagging now. Because `append` returns `None`, code like this looks reasonable but breaks:\n\n**What's wrong with this code?**\n\n\n```python\ncart = [\"Wireless Mouse\"].append(\"USB Cable\")\nprint(cart)\n```\n\n\n`append` mutates the list and returns `None`. The expression `[\"Wireless Mouse\"].append(\"USB Cable\")` evaluates to `None`, which is then bound to `cart`. The list itself was modified, but no one kept a reference to it. The fix is to call `append` as a separate statement after the list exists.\n\n**Fix:**\n\n\n```python\ncart = [\"Wireless Mouse\"]\ncart.append(\"USB Cable\")\nprint(cart)\n```\n\n\nThis \"returns None\" pattern repeats across most list methods. It applies to `sort`, `reverse`, `insert`, and others. Anything that mutates the list in place returns `None`, by design.\n\n---\n\n# extend: Adding Many Items at Once\n\n`extend(iterable)` adds every item from an iterable onto the end of the list, one at a time. It mutates in place and returns `None`.\n\n\n```python\ncart = [\"Wireless Mouse\"]\ncart.extend([\"USB Cable\", \"HDMI Cable\"])\n\nprint(cart)\n```\n\n\nCompare this with `append([\"USB Cable\", \"HDMI Cable\"])`, which would produce a nested list. `extend` unpacks the iterable: each element becomes its own list entry.\n\nThe argument can be any iterable, not just a list. Tuples, sets, strings, generators, even another list's slice all work:\n\n\n```python\ncart = [\"Wireless Mouse\"]\ncart.extend((\"USB Cable\", \"HDMI Cable\"))\ncart.extend(\"AB\")\n\nprint(cart)\n```\n\n\nThe tuple gets unpacked into two strings. The string `\"AB\"` gets unpacked into individual characters because a string is iterable too. That last one is usually a bug if you didn't mean it. Be careful when extending with strings; if you wanted the string as a single element, use `append`.\n\n### extend vs the + Operator\n\nYou can also concatenate lists with `+`:\n\n\n```python\ncart = [\"Wireless Mouse\"]\nnew_cart = cart + [\"USB Cable\", \"HDMI Cable\"]\n\nprint(new_cart)\nprint(cart)\n```\n\n\n`+` builds a **new** list and leaves the original alone. `extend` modifies the list in place. The difference shows up when something else holds a reference to your list:\n\n\n```python\ncart = [\"Wireless Mouse\"]\nsaved_reference = cart\n\ncart.extend([\"USB Cable\"])\nprint(saved_reference)\n\ncart = cart + [\"HDMI Cable\"]\nprint(saved_reference)\n```\n\n\nAfter `extend`, the saved reference reflects the change because there's only one list. After the `+` reassignment, `cart` points to a new list, but `saved_reference` still points to the old one, which is now stale.\n\nA quick reference for picking between them:\n\n\n| Operation | Returns | Mutates Original? | Accepts |\n| --- | --- | --- | --- |\n| `cart.append(x)` | `None` | Yes | One item |\n| `cart.extend(it)` | `None` | Yes | Any iterable |\n| `cart + other` | New list | No | Another list only |\n| `cart += other` | (rebinds) | Yes (same as extend) | Any iterable |\n\n\nThe `+=` operator is interesting: on a list it behaves like `extend`, mutating in place. Mixing `+` and `+=` mentally is one of the easier ways to write a bug, so be deliberate about which one you mean.\n\n---\n\n# insert: Adding at a Specific Position\n\n`insert(i, x)` puts `x` at position `i`, shifting every existing element from index `i` onward one position to the right.\n\n\n```python\ncart = [\"Wireless Mouse\", \"HDMI Cable\"]\ncart.insert(1, \"USB Cable\")\n\nprint(cart)\n```\n\n\n`USB Cable` slots in at index `1`, and the original `HDMI Cable` moves from index `1` to index `2`. `insert` returns `None`, like the other mutating methods.\n\nIndex `0` inserts at the front:\n\n\n```python\ncart = [\"USB Cable\", \"HDMI Cable\"]\ncart.insert(0, \"Wireless Mouse\")\n\nprint(cart)\n```\n\n\nAn index equal to or larger than the list length just appends:\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\"]\ncart.insert(99, \"HDMI Cable\")\n\nprint(cart)\n```\n\n\nThis is forgiving but easy to misread. If you mean \"add to the end\", use `append`; it's clearer and faster. Negative indices work too: `insert(-1, x)` puts the item before the last element.\n\n\n> **INFO**\n>\n> **Cost:** `insert(i, x)` is O(n) because every element from index `i` to the end shifts one position to the right. `insert(0, x)` in particular has to move the whole list each call. If you need cheap left-inserts, reach for `collections.deque`, which supports O(1) `appendleft`.\n\n\nA concrete demonstration of why `insert(0, ...)` hurts at scale. The pattern below is fine for a small cart, but if you're building a queue of thousands of orders this way, it's quadratic:\n\n\n```python\nfrom collections import deque\n\ncart = []\nfor product in [\"A\", \"B\", \"C\", \"D\"]:\n cart.insert(0, product)\nprint(cart)\n\nqueue = deque()\nfor product in [\"A\", \"B\", \"C\", \"D\"]:\n queue.appendleft(product)\nprint(list(queue))\n```\n\n\nSame result, but the `deque` version stays O(1) per insert. For now, remember: front-insert lots of items, use `deque`.\n\n---\n\n# remove: Deleting the First Match by Value\n\n`remove(value)` finds the first occurrence of `value` in the list and deletes it. It mutates in place, returns `None`, and raises `ValueError` if the value isn't there.\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"]\ncart.remove(\"USB Cable\")\n\nprint(cart)\n```\n\n\nIf the value appears more than once, only the first one goes:\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\", \"USB Cable\", \"HDMI Cable\"]\ncart.remove(\"USB Cable\")\n\nprint(cart)\n```\n\n\nOne of the two `USB Cable` entries is gone; the other remains. To remove every occurrence, you'd loop or use a list comprehension.\n\nNow the error case. If the value isn't in the list, `remove` raises:\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\"]\ncart.remove(\"Webcam\")\n```\n\n\nYou have two defensive options. Either check first with `in`, or wrap the call in `try`/`except`:\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\"]\n\nif \"Webcam\" in cart:\n cart.remove(\"Webcam\")\n\nprint(cart)\n```\n\n\nThat works, but it walks the list twice: once for `in`, once for `remove`. For a small cart, fine. For a list of millions, watch out.\n\n\n> **INFO**\n>\n> **Cost:** Both `in` and `remove(value)` are O(n): they scan from the front until they find the value. The \"check then remove\" pattern is two scans. If the value is usually present, `try`/`except` is cheaper because the success path scans once. If the value is usually absent, `in` first is fine.\n\n\nFor frequent membership checks, the right move is usually to use a `set` instead of a `list`. Sets do membership in O(1).\n\n---\n\n# pop: Removing by Index and Getting the Item Back\n\n`pop(i=-1)` removes the item at index `i` and returns it. With no argument it removes the last item, which is its most common use.\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"]\nlast = cart.pop()\n\nprint(last)\nprint(cart)\n```\n\n\n`pop` is unusual among the mutating methods: it returns something useful. That makes it the right tool when you want both the removed item and the list-without-it. The classic use is implementing a stack:\n\n\n```python\nundo_stack = []\nundo_stack.append(\"add_mouse\")\nundo_stack.append(\"add_cable\")\nundo_stack.append(\"apply_discount\")\n\nlast_action = undo_stack.pop()\nprint(f\"Undoing: {last_action}\")\nprint(undo_stack)\n```\n\n\nPass an index to pop from a specific position:\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"]\nremoved = cart.pop(0)\n\nprint(removed)\nprint(cart)\n```\n\n\nNegative indices count from the end, the same as elsewhere in Python. `pop(-1)` is the same as `pop()` with no argument.\n\nIf the index is out of range, `pop` raises `IndexError`:\n\n\n```python\ncart = []\ncart.pop()\n```\n\n\n\n> **INFO**\n>\n> **Cost:** `pop()` from the end is O(1). `pop(0)` and any non-tail `pop(i)` are O(n), because every element after index `i` shifts down by one. If you need O(1) `popleft`, use `collections.deque`.\n\n\nSo `pop()` and `pop(-1)` are cheap. `pop(0)` is the expensive twin of `insert(0, ...)`, and the same advice applies: use `deque` if you're doing this in a loop.\n\n---\n\n# index: Finding the Position of a Value\n\n`index(value, start=0, stop=len)` returns the position of the first occurrence of `value`. Like `remove`, it raises `ValueError` if the value isn't in the list.\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"]\nposition = cart.index(\"USB Cable\")\n\nprint(position)\n```\n\n\nThe optional `start` and `stop` arguments restrict the search to a slice of the list (the slice is interpreted using the original list's indices, not the slice's):\n\n\n```python\nproducts = [\"Mouse\", \"Cable\", \"Mouse\", \"Speaker\", \"Mouse\"]\nfirst_after_two = products.index(\"Mouse\", 2)\n\nprint(first_after_two)\n```\n\n\nSearching for `\"Mouse\"` starting from index `2` finds the one at index `2` itself, since `start` is inclusive. To skip past it:\n\n\n```python\nproducts = [\"Mouse\", \"Cable\", \"Mouse\", \"Speaker\", \"Mouse\"]\nnext_mouse = products.index(\"Mouse\", 3)\n\nprint(next_mouse)\n```\n\n\nMissing values raise:\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\"]\ncart.index(\"Webcam\")\n```\n\n\nSame defensive options as `remove`: check with `in` first, or wrap in `try`/`except`. The same O(n) caveat applies: `index` scans linearly. If you're doing this often on the same large list, a `dict` from value to index will turn the operation into O(1).\n\n---\n\n# count: How Many Times Does It Appear?\n\n`count(value)` returns the number of times `value` appears in the list. It doesn't raise on missing values; it just returns `0`.\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\", \"USB Cable\", \"HDMI Cable\", \"USB Cable\"]\ncables = cart.count(\"USB Cable\")\n\nprint(cables)\n```\n\n\nA practical e-commerce use: counting quantities in a cart that allows duplicates instead of a `(product, quantity)` tuple.\n\n\n```python\ncart = [\"Mouse\", \"Cable\", \"Mouse\", \"Charger\", \"Mouse\", \"Cable\"]\n\nfor product in set(cart):\n print(f\"{product}: {cart.count(product)}\")\n```\n\n\nThat works, but notice: this loop calls `count` once per unique product, and each call scans the whole list. For three uniques in a six-item cart, that's three scans of six items. For a thousand uniques in a million-item cart, that's a thousand scans of a million items.\n\n\n> **INFO**\n>\n> **Cost:** `count(value)` is O(n), and looping `count` over multiple values is O(n x k) where k is the number of distinct values. For counting many values at once, `collections.Counter` walks the list once and returns a dict of counts.\n\n\n`Counter` is the right tool the moment you're counting more than one or two values.\n\n---\n\n# clear: Emptying the List\n\n`clear()` removes every element from the list, leaving it empty. It mutates in place and returns `None`.\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"]\ncart.clear()\n\nprint(cart)\n```\n\n\nThere are three common ways to empty a list, and they're not all the same. This matters when other variables (or other parts of your program) hold a reference to the list:\n\n\n```python\ncart_a = [\"Mouse\", \"Cable\"]\nsaved = cart_a\n\ncart_a.clear()\nprint(saved)\n```\n\n\n`clear` mutates the underlying list. `saved` and `cart_a` are two names for the same list, so both see it empty.\n\nThe slice-deletion form does the same thing:\n\n\n```python\ncart_a = [\"Mouse\", \"Cable\"]\nsaved = cart_a\n\ndel cart_a[:]\nprint(saved)\n```\n\n\n`del cart_a[:]` deletes every element in the list via a full-list slice. The underlying object is the same one `saved` points to, so `saved` sees the change.\n\nThe reassignment form is different:\n\n\n```python\ncart_a = [\"Mouse\", \"Cable\"]\nsaved = cart_a\n\ncart_a = []\nprint(saved)\nprint(cart_a)\n```\n\n\n`cart_a = []` doesn't empty the existing list. It builds a fresh empty list and rebinds the name `cart_a` to it. The original list is unchanged, and `saved` still points to it. This is the source of a lot of confusion.\n\nA reference for the three forms:\n\n\n| Form | Mutates the existing list? | Other references see the change? |\n| --- | --- | --- |\n| `cart.clear()` | Yes | Yes |\n| `del cart[:]` | Yes | Yes |\n| `cart = []` | No (creates a new list) | No |\n\n\nIf you only have one name pointing to the list, all three look the same. The moment something else holds a reference, the choice matters.\n\n---\n\n# reverse: Flipping the List In Place\n\n`reverse()` reverses the list in place. It mutates and returns `None`.\n\n\n```python\nrecent_orders = [\"ORD-001\", \"ORD-002\", \"ORD-003\"]\nrecent_orders.reverse()\n\nprint(recent_orders)\n```\n\n\nThat's the whole behavior. It's the in-place sibling of `reversed(list)`, which returns a new iterator without touching the original. `reverse` mutates, returns `None`, and is O(n).\n\n---\n\n# A Cart's Life: Append, Remove, Pop in Action\n\nMost of the methods on this page show up in the same cart's lifetime. The diagram below traces a typical sequence: the customer starts with an empty cart, adds items, removes one that turns out to be unavailable, and finally pops the last item before checkout.\n\n\n```mermaid\nflowchart LR\n EMPTY[\"cart = []\"]:::cyan --> ADD1[append
Wireless Mouse]:::orange\n ADD1 --> ADD2[append
USB Cable]:::orange\n ADD2 --> ADD3[extend
HDMI Cable, Webcam]:::teal\n ADD3 --> CHECK{Webcam
in stock?}:::orange\n CHECK -->|No| REMOVE[remove
Webcam]:::red\n REMOVE --> POP[pop
returns HDMI Cable]:::green\n POP --> FINAL[cart = Mouse, Cable]:::cyan\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe cart grows with `append` and `extend`, shrinks with `remove` (by value, when a product turns out to be unavailable), and the final pre-checkout step uses `pop` to peel off the last item and look at it. Each operation mutates the same list; no copies are made. Code that matches the diagram:\n\n\n```python\ncart = []\ncart.append(\"Wireless Mouse\")\ncart.append(\"USB Cable\")\ncart.extend([\"HDMI Cable\", \"Webcam\"])\n\nin_stock = {\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"}\nif \"Webcam\" not in in_stock:\n cart.remove(\"Webcam\")\n\nlast_added = cart.pop()\nprint(f\"Set aside: {last_added}\")\nprint(f\"Final cart: {cart}\")\n```\n\n\nThat one snippet uses five of the methods in this lesson, all on the same cart.\n\n---\n\n# Method Reference\n\nA consolidated table of everything covered in this lesson. Use it as a cheat sheet when you're deciding which method to reach for.\n\n\n| Method | Returns | Mutates? | Raises | Complexity |\n| --- | --- | --- | --- | --- |\n| `cart.append(x)` | `None` | Yes | None | O(1) amortized |\n| `cart.extend(iterable)` | `None` | Yes | None | O(k) where k is iterable length |\n| `cart.insert(i, x)` | `None` | Yes | None | O(n), O(n) even for `insert(0, ...)` |\n| `cart.remove(value)` | `None` | Yes | `ValueError` if missing | O(n) |\n| `cart.pop()` | Removed item | Yes | `IndexError` if empty | O(1) at end |\n| `cart.pop(i)` | Removed item | Yes | `IndexError` if out of range | O(n) for non-tail |\n| `cart.index(value)` | Position | No | `ValueError` if missing | O(n) |\n| `cart.count(value)` | Count | No | None (returns `0`) | O(n) |\n| `cart.clear()` | `None` | Yes | None | O(n) |\n| `cart.reverse()` | `None` | Yes | None | O(n) |\n\n\nTwo patterns to notice in the table. First, every method that mutates returns `None`. The one exception is `pop`, which returns the removed item, which is why it's the method you'll see used in expressions more than the others. Second, only `index` and `count` are non-mutating; everything else changes the list.","pageType":"python"}

List Methods

Get Premium