Documentation fixes

Author: tusharsadhwani

Doc/c-api/exceptions.rst

@@ -1020,6 +1020,7 @@ the variables:
    single: PyExc_UnicodeEncodeError (C var)
    single: PyExc_UnicodeError (C var)
    single: PyExc_UnicodeTranslateError (C var)
+   single: PyExc_UnpackError (C var)
    single: PyExc_ValueError (C var)
    single: PyExc_ZeroDivisionError (C var)
 
@@ -1128,6 +1129,8 @@ the variables:
 +-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_UnicodeTranslateError`   | :exc:`UnicodeTranslateError`    |          |
 +-----------------------------------------+---------------------------------+----------+
+| :c:data:`PyExc_UnpackError`             | :exc:`UnpackError`              |          |
++-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ValueError`              | :exc:`ValueError`               |          |
 +-----------------------------------------+---------------------------------+----------+
 | :c:data:`PyExc_ZeroDivisionError`       | :exc:`ZeroDivisionError`        |          |

Doc/library/exceptions.rst

@@ -666,6 +666,24 @@ The following exceptions are the exceptions that are usually raised.
    Raised when a Unicode-related error occurs during translating.  It is a subclass
    of :exc:`UnicodeError`.
 
+.. exception:: UnpackError
+
+   Raised when unpacking an iterable fails due to a mismatch in the number of items in
+   the iterable and the number of targets.  It is a subclass of :exc:`ValueError`.
+
+   .. attribute:: msg
+
+       The error message generated by the compiler. Can be :attr:`None`.
+
+   .. attribute:: iterable
+
+       The iterable that was being unpacked that caused the error to be raised.
+
+   .. attribute:: expected_count
+
+       The number of targets that the iterable was expected to be unpacked into.
+
+   .. versionadded:: 3.14
 
 .. exception:: ValueError
 

Include/cpython/pyerrors.h

@@ -82,13 +82,6 @@ typedef struct {
     PyObject *name;
 } PyAttributeErrorObject;
 
-typedef struct {
-    PyException_HEAD
-    PyObject *msg;
-    PyObject *iterable;
-    PyObject *expected_count;
-} PyUnpackErrorObject;
-
 /* Compatibility typedefs */
 typedef PyOSErrorObject PyEnvironmentErrorObject;
 #ifdef MS_WINDOWS

Include/internal/pycore_exceptions.h

@@ -30,6 +30,12 @@ struct _Py_exc_state {
 
 extern void _PyExc_ClearExceptionGroupType(PyInterpreterState *);
 
+typedef struct {
+    PyException_HEAD
+    PyObject *msg;
+    PyObject *iterable;
+    PyObject *expected_count;
+} PyUnpackErrorObject;
 
 #ifdef __cplusplus
 }

Lib/test/test_unpack.py

@@ -1,5 +1,4 @@
 import doctest
-import textwrap
 import traceback
 import unittest
 
@@ -151,8 +150,8 @@
       ...
     UnpackError: too many values to unpack (expected 0, got 1)
 
-Unpacking to an empty iterable should raise UnpackError, but it won't consume the
-iterable if it doesn't have a pre-determined length
+Unpacking a larger iterable should raise UnpackError, but it shouldn't consume the
+iterable entirely
 
     >>> it = iter(range(100))
     >>> x, y, z = it
@@ -222,20 +221,15 @@ def test_extended_oparg_not_ignored(self):
 
     def test_exception_context_when_len_fails(self):
         """When `__len__()` raises an Exception, preserve exception context"""
-        code = textwrap.dedent(
-            """
-            class CustomSeq:
-                def __len__(self):
-                    raise RuntimeError
 
-                def __getitem__(self, i):
-                    return i*2
+        class LenRaisesException:
+            def __len__(self):
+                raise RuntimeError
+            def __getitem__(self, i):
+                return i*2
 
-            x, y, z = CustomSeq()
-            """
-        )
         with self.assertRaises(UnpackError) as cm:
-            exec(code)
+            x, y, z = LenRaisesException()
 
         traceback_text = ''.join(traceback.format_exception(cm.exception))
         self.assertIn(
@@ -247,19 +241,15 @@ def __getitem__(self, i):
 
     def test_baseexception_propagation_when_len_fails(self):
         """if `__len__()` raises a `BaseException`, propagate that as-is"""
-        code = textwrap.dedent(
-            """
-            class C:
-                def __len__(self):
-                    raise KeyboardInterrupt
-                def __getitem__(self, i):
-                    return i
-
-            x, y, z = C()
-            """
-        )
+
+        class LenRaisesBaseException:
+            def __len__(self):
+                raise KeyboardInterrupt
+            def __getitem__(self, i):
+                return i
+
         with self.assertRaises(UnpackError) as cm:
-            exec(code)
+            x, y, z = LenRaisesBaseException()
 
         with self.assertRaises(KeyboardInterrupt):
             traceback.format_exception(cm.exception)

Lib/traceback.py

@@ -1099,18 +1099,18 @@ def __init__(self, exc_type, exc_value, exc_traceback, *, limit=None,
             if exc_value.msg is not None:
                 self._str = exc_value.msg
             else:
-                lhs_length = exc_value.expected_count
-                self._str = f"too many values to unpack (expected {lhs_length})"
+                expected_count = exc_value.expected_count
+                self._str = f"too many values to unpack (expected {expected_count})"
                 try:
-                    rhs_length = len(exc_value.iterable)
-                    if rhs_length and rhs_length > lhs_length:
+                    actual_count = len(exc_value.iterable)
+                    if actual_count and actual_count > expected_count:
                         self._str = (
-                            f"too many values to unpack (expected {lhs_length},"
-                            f" got {rhs_length})"
+                            f"too many values to unpack (expected {expected_count},"
+                            f" got {actual_count})"
                         )
                 # The error can be a `TypeError` (for objects that implement
                 # `__getitem__` but do not implement `__len__`).
-                # For any other kind of `Exception`, we raise `ValueError` while
+                # For any other kind of `Exception`, we raise `UnpackError` while
                 # setting the raised exception as context.
                 # For a `BaseException`, we don't modify it at all, and let it
                 # propagate.

Objects/exceptions.c

@@ -2694,7 +2694,7 @@ UnpackError_str(PyObject *self)
     PyUnpackErrorObject *uself = (PyUnpackErrorObject *)self;
     if (!uself->msg) {
         return BaseException_str((PyBaseExceptionObject *)self);
-    };
+    }
     return Py_NewRef(uself->msg);
 }
 
@@ -2711,7 +2711,7 @@ static void
 UnpackError_dealloc(PyUnpackErrorObject *self)
 {
     _PyObject_GC_UNTRACK(self);
-    UnpackError_clear(self);
+    (void)UnpackError_clear(self);
     Py_TYPE(self)->tp_free((PyObject *)self);
 }