deque extend / extendleft

extend is a loop of append; extendleft is a loop of appendleft — so the items land on the left in REVERSE order. With maxlen, items pushed out along the way are gone.

deque methodsPython 2.4+Live demo
Common call
d.extend([4, 5]) · d.extendleft('ab')
Returns
None
Replaces
for x in items: d.append(x)
Watch out
extendleft('ab') puts b before a
deque.extend(iterableiterable — Items to add, consumed left to right. A str adds one item per character.type: iterable · required)
→ None

Demo

Live evaluation
Items are appended in order on the right.
Try:
Inputs
itemslist[str]starting items
morelist[str]items to add
Code
from collections import deque
d = deque(['a', 'b'])
d.extend(['c', 'd'])
d
Result
deque(['a', 'b', 'c', 'd'])

extendleft(["1", "2", "3"]) on x, y gives 3, 2, 1, x, y: "1" goes to the front first, then "2" in front of it, then "3". In the maxlen tab only the last three of a, b, c, d, e remain.

Parameters

NameTypeRequiredDescription
iterableiterableyesItems to add, consumed left to right. A str adds one item per character.

Return value

None — The deque is changed in place.

Common patterns

Prepend a run in its original order
Reverse it first, because extendleft reverses again.
from collections import deque
d.extendleft(reversed(prefix))
Keep the last N of a stream
One call does the whole job.
from collections import deque
last = deque(maxlen=5)
last.extend(stream)
Consume an iterator for its side effects
The itertools docs recipe: a zero-length deque stores nothing.
from collections import deque
deque(iterator, maxlen=0)

Examples

1. extend adds on the right
from collections import deque d = deque([1, 2]) d.extend([3, 4]) d
Returns
deque([1, 2, 3, 4])
2. extendleft reverses
from collections import deque d = deque([3]) d.extendleft([2, 1, 0]) d
Returns
deque([0, 1, 2, 3])
3. A string adds characters
from collections import deque d = deque() d.extend('hi') d
Returns
deque(['h', 'i'])
4. Prepend in original order
from collections import deque d = deque(['c']) d.extendleft(reversed(['a', 'b'])) d
Returns
deque(['a', 'b', 'c'])
5. Bounded extend keeps the newest
from collections import deque d = deque(maxlen=2) d.extend(range(5)) d
Returns
deque([3, 4], maxlen=2)
6. Extending with itself works
from collections import deque d = deque([1, 2]) d.extend(d) d
Returns
deque([1, 2, 1, 2])

Pitfalls

1. Expecting extendleft to keep order
It appends to the left one item at a time.
extendleft('ab')
from collections import deque
d = deque('c')
d.extendleft('ab')
''.join(d)
'bac'
extendleft(reversed('ab'))
from collections import deque
d = deque('c')
d.extendleft(reversed('ab'))
''.join(d)
'abc'
2. append when you meant extend
append adds the whole list as ONE item.
append([...])
from collections import deque
d = deque([1])
d.append([2, 3])
d
deque([1, [2, 3]])
extend([...])
from collections import deque
d = deque([1])
d.extend([2, 3])
d
deque([1, 2, 3])

When to use

Use it
  • Adding a batch of items to either end
  • Filling a bounded deque from a stream
Reach for something else
  • A new combined deque, leaving the original alone → d1 + d2 (supported since 3.5)

Notes

CPython impl
deque_extend / deque_extendleft in Modules/_collectionsmodule.c; extending a deque with itself iterates over a copy
Order
extendleft(iterable) leaves the items in reverse order on the left

FAQ

It is defined as repeated appendleft: the first item goes to the front, then the second goes in front of it, and so on. Pass reversed(items) to keep the original order.