Skip to content
Python list.extend: stage a fallible iterator before mutation

Python list.extend: stage a fallible iterator before mutation

November 20, 2026

An iterator can yield several values and then fail. On the tested CPython version, passing it directly to list.extend leaves the values already appended in the destination.

Set up

Tested on Linux with CPython 3.12.14. Use Python 3.12 or later, Bash, a text editor, mktemp, rm and rmdir. The example needs no network access. Run the steps in the same terminal and stop if setup fails. Run Python without -O so the assertions stay enabled.

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save this as stage_before_extend.py:

def incoming():
    yield "new-1"
    yield "new-2"
    raise ValueError("invalid remaining input")

direct = ["existing"]
try:
    direct.extend(incoming())
except ValueError as exc:
    print("direct error:", exc)
print("direct result:", direct)

staged = ["existing"]
try:
    pending = list(incoming())
except ValueError as exc:
    print("staging error:", exc)
else:
    staged.extend(pending)
print("staged result:", staged)
assert direct == ["existing", "new-1", "new-2"]
assert staged == ["existing"]

Run:

python3 -B stage_before_extend.py

Observed output:

direct error: invalid remaining input
direct result: ['existing', 'new-1', 'new-2']
staging error: invalid remaining input
staged result: ['existing']

Finish input production before updating the destination

The mutable sequence documentation describes extend as appending items from an iterable. It does not promise rollback when producing those items fails. The direct example records the partial result observed on CPython 3.12.14.

In the second example, list(incoming()) fails before execution reaches staged.extend. The destination therefore retains its original contents. The else suite is reached only if staging completes; keeping the mutation there makes that dependency explicit.

Limits

Staging consumes memory for the whole input and is unsuitable for an unbounded iterator. It does not undo source-side effects, consumption, or changes made by the iterator itself. Nor does it turn the final list update into a general transaction with a rollback guarantee for every possible failure. Use this pattern for bounded, fallible input when keeping that input failure from partially extending the destination is the requirement.

Clean up

Remove the example file and the temporary directory:

rm -- stage_before_extend.py
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

Acknowledgements

This post was created with assistance from AI.

Last updated on