TypeError should be raised for tuple unpacking size mismatch instead of ValueError

[peturingi]

Bug report

Bug description:

When unpacking a tuple into a different number of variables than the tuple contains, Python raises ValueError. This violates fundamental type-theoretic principles and contradicts Python's own error hierarchy documentation.

Current Behaviour

def process_quadruple(data: tuple[int, int, int, int]):
    a, b, c, d = data  # Raises ValueError if len(data) != 4.
    return a + b + c + d

process_quadruple((1, 2, 3))  # "ValueError: not enough values to unpack (expected 4, got 3)".

Expected Behaviour

process_quadruple((1, 2, 3)) should raise TypeError, not ValueError.

Arguments

Type-Theory

In type theory, a tuple is a product type. For a type $T$, the n-tuple type is formally defined as: $$\text{n-tuple}[T] = \underbrace{T \times T \times \ldots \times T}_{n \text{ times}}$$
where the cardinality of the product type is $$|\text{n-tuple}[T]| = |T|^n$$

For distinct values of $n$ and $m$ where $n \neq m$, we have $$\text{n-tuple}[T] \cap \text{m-tuple}[T] = \emptyset$$

which makes it evident that the types of a 3-tuple and a 4-tuple are disjoint.

To further support this argument, we can formally define the typing judgement for tuple membership as:

$$\frac{v_1 : T \quad v_2 : T \quad v_3 : T}{(v_1, v_2, v_3) : T^3}$$

$$\frac{v_1 : T \quad v_2 : T \quad v_3 : T \quad v_4 : T}{(v_1, v_2, v_3, v_4) : T^4}$$

There is no derivation rule which allow for $$\nvdash (v_1, v_2, v_3) : T^4$$

This is to say that the value $(v_1, v_2, v_3)$ of type $T^3$ cannot inhabit type $T^4$, not because the value is wrong, but because tuples of different arities are fundamentally different types.

Subtyping Relations of Tuples in Python

In structural type systems, tuple types have restricted subtyping relations.
That is also the case in Python:

# Python supports T⁴ <: T³ using explicit type narrowing via extended iterable unpacking:
a, b, c, *_ = (1, 2, 3, 4)  # Valid: 4-tuple satisfies 3-element unpacking.

This demonstrates that Python recognises the width subtyping relation to the point
that it allows a 4-tuple to be unpacked into 3 variables by ignoring the extra elements, thereby satisfying the subtyping relation $$T^4 <: T^3$$

while explicitly disallowing the reverse:

$$T^3 \not<: T^4$$

a, b, c, d = (1, 2, 3)  # Invalid: 3-tuple cannot satisfy 4-element unpacking.

Type Annotations

Python's own annotation syntax allows for explicit distinction between tuples of different arities:

from typing import get_type_hints

def f(x: tuple[int, int, int]): pass
def g(x: tuple[int, int, int, int]): pass

print(get_type_hints(f)['x'] == get_type_hints(g)['x'])  # False

Static type checkers like mypy correctly identify this as a type error:

def process(x: tuple[int, int, int, int]):
    return sum(x)

process((1, 2, 3))  # mypy: Argument 1 has incompatible type "tuple[int, int, int]"
                    #        expected "tuple[int, int, int, int]"

Formal Semantics of the Error

We can characterise the two assignment-unpacking operational rules (ignoring starred-assignment in literals) as:

Fixed-Length Unpacking

$$ E \Downarrow (v_1,\dots,v_n);\Rightarrow; \begin{cases} (\text{let } x_1,\dots,x_m = E \text{ in } E') \Downarrow E'[v_1/x_1,\dots,v_m/x_m], & \text{if } n = m,\\ \text{raise Error}, & \text{if } n \neq m. \end{cases} $$

Extended Iterable Unpacking (PEP 3132)

$$ \frac{E \Downarrow (v_1,\dots,v_n) \quad n \ge m-1} {(\text{let } x_1,\dots,x_{m-1},,\ast x_m = E \text{ in } E') \Downarrow E'[v_1/x_1,\dots,v_{m-1}/x_{m-1},(v_m,\dots,v_n)/x_m]} $$

Under Fixed-Length Unpacking rule, failure of the side condition $n \neq m$ was is interpreted in CPython as a ValueError.
However, once extended iterable unpacking was introduced, this justification becomes less coherent: tuples of differing arities can be valid inputs under the language semantics.

The error in the fixed-length case is therefore not due to a "malformed value", but to a mismatch between the tuple's arity and the expected type of the left-hand side, which makes it more naturally classified as a TypeError.

Comparison with Other Languages

Haskell

-- Type error at compile time
let (a, b, c, d) = (1, 2, 3)  -- Couldn't match expected type '(a, b, c, d)'
                               -- with actual type '(Integer, Integer, Integer)'

Rust

let (a, b, c, d) = (1, 2, 3);  // Error: mismatched types
                               // expected tuple of 4 elements, found tuple of 3 elements

OCaml

let (a, b, c, d) = (1, 2, 3);;  (* Error: This expression has type int * int * int
                                   but an expression was expected of type 'a * 'b * 'c * 'd *)

All these languages correctly identify this as a type error.

Proposed Fix

--- a/Python/ceval.c
+++ b/Python/ceval.c
@@ -1082,14 +1082,14 @@ _PyEval_UnpackIterableStackRef(PyThreadState *tstate, PyObject *v,
         w = PyIter_Next(it);
         if (w == NULL) {
             /* Iterator done, via error or exhaustion. */
             if (!_PyErr_Occurred(tstate)) {
                 if (argcntafter == -1) {
-                    _PyErr_Format(tstate, PyExc_ValueError,
+                    _PyErr_Format(tstate, PyExc_TypeError, // +
                                   "not enough values to unpack "
                                   "(expected %d, got %d)",
                                   argcnt, i);
                 }
                 else {
                     _PyErr_Format(tstate, PyExc_ValueError,
                                   "not enough values to unpack "
                                   "(expected at least %d, got %d)",
                                   argcnt + argcntafter, i);
                 }
             }
             goto Error;
         }
@@ -1110,20 +1110,20 @@ _PyEval_UnpackIterableStackRef(PyThreadState *tstate, PyObject *v,
         if (w == NULL) {
             if (_PyErr_Occurred(tstate))
                 goto Error;
             Py_DECREF(it);
             return 1;
         }
         Py_DECREF(w);
 
         if (PyList_CheckExact(v) || PyTuple_CheckExact(v)
               || PyDict_CheckExact(v)) {
             ll = PyDict_CheckExact(v) ? PyDict_Size(v) : Py_SIZE(v);
             if (ll > argcnt) {
-                _PyErr_Format(tstate, PyExc_ValueError,
+                _PyErr_Format(tstate, PyExc_TypeError, // +
                               "too many values to unpack (expected %d, got %zd)",
                               argcnt, ll);
                 goto Error;
             }
         }
-        _PyErr_Format(tstate, PyExc_ValueError,
+        _PyErr_Format(tstate, PyExc_TypeError, // +
                       "too many values to unpack (expected %d)",
                       argcnt);
         goto Error;
     }
 
@@ -1137,7 +1137,7 @@ _PyEval_UnpackIterableStackRef(PyThreadState *tstate, PyObject *v,
     ll = PyList_GET_SIZE(l);
     if (ll < argcntafter) {
-        _PyErr_Format(tstate, PyExc_ValueError,
+        _PyErr_Format(tstate, PyExc_ValueError, // (unchanged – extended unpacking remains ValueError)
             "not enough values to unpack (expected at least %d, got %zd)",
             argcnt + argcntafter, argcnt + ll);
         goto Error;
     }

CPython versions tested on:

3.13

Operating systems tested on:

macOS

[skirpichev]

Arguments do make sense for me from the theoretical point of view, but I'm not sure this warrants a compatibility break.

[picnixz]

Changes to builtins require a PEP, so please first open a discussion in https://discuss.python.org/c/ideas/6 and see if there is support in the community so that this could warrant a breakage. I'm -1 on this one because this is a real breakage and this should have probably decided at the beginning, not now.

I understand the basis of the theory (it's as if we were to expect a pair but got a triplet, or vice-versa) but I don't think this is enough to change the semantics now that's been decided.

that it allows a 4-tuple to be unpacked into 3 variables by ignoring the extra elements

It's not entirely accurate, there are 4 variables here, where the last one is a sequence of what remains. I would consider *_ as a syntactic sugar to indicate "the rest is re-packed in this variable".

---

I'm going to close this one until a discussion has been opened.

[terryjreedy]

In Python, there is 1 and only 1 tuple type.

>>> type(()) is type((0,)) is type((0,1)) is type((0,1,2))  # etc.
True

The subtyping in the relatively recent and OPTIONAL add-on typing module does not change this. Remember that the parameter call typing has NO runtime effect. In multiple assignments like a,b,c,d = data, the required 'type' is 'iterable'. The required value here is 'iterable of 4 items', not just 4 tuples.

>>> a,b = 1,2
>>> a,b = [1,2]
>>> a,b = range(1,3)
>>> a,b = {1:None, 2:None}

all result in a ==1 and b==2. a,b = {1,2} could result in a == 2 and b == 1 instead. ValueError is correct for any iterable yielding other than 4 items. A TypeError results when one passes a non-iterable. Python is fundamentally a duck-typed language. Typing declarations were accepted with the promise that duck-typing would remain. The breakage of typing enforcement was already rejected. This is precisely why static checkers like mypy are separate from the main runtime. (This also allows for different enforcement policies and other behaviors.)

[peturingi]

@terryjreedy
Your argument that "there is 1 and only 1 tuple type" is reductio ad absurdum.

>>> type((1,2,3)) is type((1,2,3,4))
True
>>> type(5) is type(999999)
True

Do you think 999999 can be a "wrong value* of int? Python says yes for some operations:

>>> chr(999999)
# ValueError: chr() arg not in range(0x110000)

But when you pass the wrong type entirely:

>>> chr("5")
TypeError: an integer is required

Python already distinguishes: wrong type → TypeError, wrong value of correct type → ValueError-

"The required value here is 'iterable of 4 items'"

Exactly my point. A 3-item iterable isn't a wrong value of a 4-item iterable. It's a different thing entirely. Different things categorise different types.

Your own example proves this:

"A TypeError results when one passes a non-iterable"

So:

• Pass non-iterable → TypeError (not an iterable)
• Pass 3-item iterable where 4 required → ValueError???

Both are the wrong type of thing. The inconsistency is obvious.

[peturingi]

@skirpichev , @picnixz As worried while understood. Thank you for your feedback.