Skip to content
Python dict.pop: distinguish a missing key from a stored None

Python dict.pop: distinguish a missing key from a stored None

November 20, 2026

An optional field may deliberately contain None. Using pop(key, None) then makes that stored value indistinguishable from a missing field after the call.

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 pop_optional_value.py:

missing = object()

def consume_timeout(settings):
    value = settings.pop("timeout", missing)
    if value is missing:
        return "missing"
    if value is None:
        return "explicit None"
    return f"value {value!r}"

for settings in [{}, {"timeout": None}, {"timeout": 0}, {"timeout": 5}]:
    print(consume_timeout(settings), "remaining:", settings)

settings = {"timeout": None}
print("ambiguous:", settings.pop("timeout", None), settings.pop("timeout", None))
assert consume_timeout({"timeout": 0}) == "value 0"

Run:

python3 -B pop_optional_value.py

Observed output:

missing remaining: {}
explicit None remaining: {}
value 0 remaining: {}
value 5 remaining: {}
ambiguous: None None

Check the sentinel by identity

The dict.pop documentation specifies that an existing key is removed and its value returned. For a missing key, the supplied default is returned; without a default, the call raises KeyError.

A private object() gives the missing case a distinct identity. The is comparison avoids confusing it with None, zero, or another false value. Keep that sentinel out of legitimate input values. In the last printed line, the first call removes a real None; the second encounters a missing key, yet both return None.

Limits

pop changes the dictionary immediately. If you need to validate a value before deciding whether to remove it, read and validate first, then perform the intended mutation. That sequence is not a transaction against concurrent writers. Also avoid using a truthiness check such as if value when zero or an empty value is valid input.

Clean up

Remove the example file and the temporary directory:

rm -- pop_optional_value.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