For forbid_extra_keys raise custom ForbiddenExtraKeyError instead of generic Exception.

Author: raabf

HISTORY.rst

@@ -11,10 +11,10 @@ History
   (`#218 <https://github.com/python-attrs/cattrs/issues/218>`_)
 * Fix structuring bare ``typing.Tuple`` on Pythons lower than 3.9.
   (`#218 <https://github.com/python-attrs/cattrs/issues/218>`_)
-
 * Fix a wrong ``AttributeError`` of an missing ``__parameters__`` attribute. This could happen 
   when inheriting certain generic classes – for example ``typing.*`` classes are affected. 
   (`#217 <https://github.com/python-attrs/cattrs/issues/217>`_)
+* For ``forbid_extra_keys`` raise custom ``ForbiddenExtraKeyError`` instead of generic ``Exception``.
 
 1.10.0 (2022-01-04)
 -------------------

docs/customizing.rst

@@ -108,7 +108,7 @@ creating structure hooks with ``make_dict_structure_fn``.
     >>> c.structure({"nummber": 2}, TestClass)
     Traceback (most recent call last):
     ...
-    Exception: Extra fields in constructor for TestClass: nummber
+    ForbiddenExtraKeyError: Extra fields in constructor for TestClass: nummber
     >>> hook = make_dict_structure_fn(TestClass, c, _cattrs_forbid_extra_keys=False)
     >>> c.register_structure_hook(TestClass, hook)
     >>> c.structure({"nummber": 2}, TestClass)

docs/structuring.rst

@@ -473,7 +473,7 @@ Here's a small example showing how to use factory hooks to apply the `forbid_ext
     >>> c.structure({"an_int": 1, "else": 2}, E)
     Traceback (most recent call last):
     ...
-    Exception: Extra fields in constructor for E: else
+    ForbiddenExtraKeyError: Extra fields in constructor for E: else
 
 
 A complex use case for hook factories is described over at :ref:`Using factory hooks`.

src/cattr/errors.py

@@ -7,3 +7,7 @@ class StructureHandlerNotFoundError(Exception):
     def __init__(self, message: str, type_: Type) -> None:
         super().__init__(message)
         self.type_ = type_
+
+
+class ForbiddenExtraKeyError(Exception):
+    """Raised when `forbid_extra_keys` is activated and such an extra key is detected during structuring."""

src/cattrs/errors.py

@@ -1,3 +1,3 @@
-from cattr.errors import StructureHandlerNotFoundError
+from cattr.errors import ForbiddenExtraKeyError, StructureHandlerNotFoundError
 
-__all__ = ["StructureHandlerNotFoundError"]
+__all__ = ["ForbiddenExtraKeyError", "StructureHandlerNotFoundError"]

src/cattrs/gen.py

@@ -26,6 +26,7 @@
     is_generic,
 )
 from cattr._generics import deep_copy_with
+from cattr.errors import ForbiddenExtraKeyError
 
 if TYPE_CHECKING:  # pragma: no cover
     from cattr.converters import Converter
@@ -383,10 +384,11 @@ def make_dict_structure_fn(
 
     if _cattrs_forbid_extra_keys:
         globs["__c_a"] = allowed_fields
+        globs["ForbiddenExtraKeyError"] = ForbiddenExtraKeyError
         post_lines += [
             "  unknown_fields = set(o.keys()) - __c_a",
             "  if unknown_fields:",
-            "    raise Exception(",
+            "    raise ForbiddenExtraKeyError(",
             f"      'Extra fields in constructor for {cl_name}: ' + ', '.join(unknown_fields)"
             "    )",
         ]

tests/metadata/test_genconverter.py

@@ -19,6 +19,7 @@
 from cattr import GenConverter as Converter
 from cattr import UnstructureStrategy
 from cattr._compat import is_py39_plus, is_py310_plus
+from cattr.errors import ForbiddenExtraKeyError
 from cattr.gen import make_dict_structure_fn, override
 
 from . import (
@@ -85,7 +86,7 @@ def test_forbid_extra_keys(cls_and_vals):
     while bad_key in unstructured:
         bad_key += "A"
     unstructured[bad_key] = 1
-    with pytest.raises(Exception):
+    with pytest.raises(ForbiddenExtraKeyError):
         converter.structure(unstructured, cl)
 
 
@@ -100,7 +101,7 @@ def test_forbid_extra_keys_defaults(attr_and_vals):
     inst = cl()
     unstructured = converter.unstructure(inst)
     unstructured["aa"] = unstructured.pop("a")
-    with pytest.raises(Exception):
+    with pytest.raises(ForbiddenExtraKeyError):
         converter.structure(unstructured, cl)
 
 
@@ -120,7 +121,7 @@ class A:
     converter.structure(unstructured, A)
     # if we break it in the subclass, we need it to raise
     unstructured["c"]["aa"] = 5
-    with pytest.raises(Exception):
+    with pytest.raises(ForbiddenExtraKeyError):
         converter.structure(unstructured, A)
     # we can "fix" that by disabling forbid_extra_keys on the subclass
     hook = make_dict_structure_fn(
@@ -130,7 +131,7 @@ class A:
     converter.structure(unstructured, A)
     # but we should still raise at the top level
     unstructured["b"] = 6
-    with pytest.raises(Exception):
+    with pytest.raises(ForbiddenExtraKeyError):
         converter.structure(unstructured, A)