Implement first class exception support

Fixes #368

.pre-commit-config.yaml

@@ -9,7 +9,7 @@ repos:
         types: []
 
   - repo: https://gitlab.com/pycqa/flake8
-    rev: '3.7.3'
+    rev: 3.7.5
     hooks:
     - id: flake8
       language_version: python3.7

changelog.d/500.change.rst

@@ -0,0 +1,3 @@
+``attrs`` now has first class support for defining exception classes.
+
+If you define a class using ``@attr.s(auto_exc=True)`` and subclass an exception, the class will behave like a well-behaved exception class including an appropriate ``__str__`` method, and all attributes additionally available in an ``args`` attribute.

docs/api.rst

@@ -18,7 +18,7 @@ What follows is the API explanation, if you'd like a more hands-on introduction,
 Core
 ----
 
-.. autofunction:: attr.s(these=None, repr_ns=None, repr=True, cmp=True, hash=None, init=True, slots=False, frozen=False, weakref_slot=True, str=False, auto_attribs=False, kw_only=False, cache_hash=False)
+.. autofunction:: attr.s(these=None, repr_ns=None, repr=True, cmp=True, hash=None, init=True, slots=False, frozen=False, weakref_slot=True, str=False, auto_attribs=False, kw_only=False, cache_hash=False, auto_exc=False)
 
    .. note::
 
@@ -42,6 +42,20 @@ Core
       >>> D = attr.s(these={"x": attr.ib()}, init=False)(D)
       >>> D(1)
       D(x=1)
+      >>> @attr.s(auto_exc=True)
+      ... class Error(Exception):
+      ...     x = attr.ib()
+      ...     y = attr.ib(default=42, init=False)
+      >>> Error("foo")
+      Error(x='foo', y=42)
+      >>> raise Error("foo")
+      Traceback (most recent call last):
+         ...
+      Error: ('foo', 42)
+      >>> raise ValueError("foo", 42)   # for comparison
+      Traceback (most recent call last):
+         ...
+      ValueError: ('foo', 42)
 
 
 .. autofunction:: attr.ib

src/attr/__init__.pyi

@@ -167,6 +167,7 @@ def attrs(
     auto_attribs: bool = ...,
     kw_only: bool = ...,
     cache_hash: bool = ...,
+    auto_exc: bool = ...,
 ) -> _C: ...
 @overload
 def attrs(
@@ -184,6 +185,7 @@ def attrs(
     auto_attribs: bool = ...,
     kw_only: bool = ...,
     cache_hash: bool = ...,
+    auto_exc: bool = ...,
 ) -> Callable[[_C], _C]: ...
 
 # TODO: add support for returning NamedTuple from the mypy plugin
@@ -212,6 +214,7 @@ def make_class(
     auto_attribs: bool = ...,
     kw_only: bool = ...,
     cache_hash: bool = ...,
+    auto_exc: bool = ...,
 ) -> type: ...
 
 # _funcs --

src/attr/_make.py

@@ -453,6 +453,7 @@ class _ClassBuilder(object):
         "_has_post_init",
         "_delete_attribs",
         "_base_attr_map",
+        "_is_exc",
     )
 
     def __init__(
@@ -465,6 +466,7 @@ def __init__(
         auto_attribs,
         kw_only,
         cache_hash,
+        is_exc,
     ):
         attrs, base_attrs, base_map = _transform_attrs(
             cls, these, auto_attribs, kw_only
@@ -482,6 +484,7 @@ def __init__(
         self._cache_hash = cache_hash
         self._has_post_init = bool(getattr(cls, "__attrs_post_init__", False))
         self._delete_attribs = not bool(these)
+        self._is_exc = is_exc
 
         self._cls_dict["__attrs_attrs__"] = self._attrs
 
@@ -660,8 +663,15 @@ def add_str(self):
                 "__str__ can only be generated if a __repr__ exists."
             )
 
-        def __str__(self):
-            return self.__repr__()
+        if self._is_exc:
+
+            def __str__(self):
+                return BaseException.__str__(self)
+
+        else:
+
+            def __str__(self):
+                return self.__repr__()
 
         self._cls_dict["__str__"] = self._add_method_dunders(__str__)
         return self
@@ -688,6 +698,7 @@ def add_init(self):
                 self._slots,
                 self._cache_hash,
                 self._base_attr_map,
+                self._is_exc,
             )
         )
 
@@ -738,6 +749,7 @@ def attrs(
     auto_attribs=False,
     kw_only=False,
     cache_hash=False,
+    auto_exc=False,
 ):
     r"""
     A class decorator that adds `dunder
@@ -846,7 +858,21 @@ def attrs(
         class.  If the hash code is cached, then no attributes of this
         class which participate in hash code computation may be mutated
         after object creation.
-
+    :param bool auto_exc: If the class subclasses :class:`BaseException`
+        (which implicitly includes any subclass of any exception), the
+        following happens to behave like a well-behaved Python exceptions
+        class:
+
+        - the values for *cmp* and *hash* are ignored and the instances compare
+          and hash by the instance's ids (N.B. ``attrs`` will *not* remove
+          existing implementations of ``__hash__`` or the equality methods. It
+          just won't add own ones.),
+        - all attributes that are either passed into ``__init__`` or have a
+          default value are additionally available as a tuple in the ``args``
+          attribute,
+        - the value of *str* is ignored and a ``__str__`` method is added that
+          returns a str of the ``args`` tuple (this differs from passing
+          ``str=True`` which returns the same string as ``repr()``).
 
     .. versionadded:: 16.0.0 *slots*
     .. versionadded:: 16.1.0 *frozen*
@@ -866,12 +892,16 @@ class which participate in hash code computation may be mutated
        to each other.
     .. versionadded:: 18.2.0 *kw_only*
     .. versionadded:: 18.2.0 *cache_hash*
+    .. versionadded:: 19.1.0 *auto_exc*
     """
 
     def wrap(cls):
+
         if getattr(cls, "__class__", None) is None:
             raise TypeError("attrs only works with new-style classes.")
 
+        is_exc = auto_exc is True and issubclass(cls, BaseException)
+
         builder = _ClassBuilder(
             cls,
             these,
@@ -881,13 +911,14 @@ def wrap(cls):
             auto_attribs,
             kw_only,
             cache_hash,
+            is_exc,
         )
 
         if repr is True:
             builder.add_repr(repr_ns)
-        if str is True:
+        if str is True or is_exc:
             builder.add_str()
-        if cmp is True:
+        if cmp is True and not is_exc:
             builder.add_cmp()
 
         if hash is not True and hash is not False and hash is not None:
@@ -902,7 +933,11 @@ def wrap(cls):
                     " hashing must be either explicitly or implicitly "
                     "enabled."
                 )
-        elif hash is True or (hash is None and cmp is True and frozen is True):
+        elif (
+            hash is True
+            or (hash is None and cmp is True and frozen is True)
+            and is_exc is False
+        ):
             builder.add_hash()
         else:
             if cache_hash:
@@ -1241,7 +1276,9 @@ def _add_repr(cls, ns=None, attrs=None):
     return cls
 
 
-def _make_init(attrs, post_init, frozen, slots, cache_hash, base_attr_map):
+def _make_init(
+    attrs, post_init, frozen, slots, cache_hash, base_attr_map, is_exc
+):
     attrs = [a for a in attrs if a.init or a.default is not NOTHING]
 
     # We cache the generated init methods for the same kinds of attributes.
@@ -1250,16 +1287,18 @@ def _make_init(attrs, post_init, frozen, slots, cache_hash, base_attr_map):
     unique_filename = "<attrs generated init {0}>".format(sha1.hexdigest())
 
     script, globs, annotations = _attrs_to_init_script(
-        attrs, frozen, slots, post_init, cache_hash, base_attr_map
+        attrs, frozen, slots, post_init, cache_hash, base_attr_map, is_exc
     )
     locs = {}
     bytecode = compile(script, unique_filename, "exec")
     attr_dict = dict((a.name, a) for a in attrs)
     globs.update({"NOTHING": NOTHING, "attr_dict": attr_dict})
+
     if frozen is True:
         # Save the lookup overhead in __init__ if we need to circumvent
         # immutability.
         globs["_cached_setattr"] = _obj_setattr
+
     eval(bytecode, globs, locs)
 
     # In order of debuggers like PDB being able to step through the code,
@@ -1273,6 +1312,7 @@ def _make_init(attrs, post_init, frozen, slots, cache_hash, base_attr_map):
 
     __init__ = locs["__init__"]
     __init__.__annotations__ = annotations
+
     return __init__
 
 
@@ -1287,6 +1327,7 @@ def _add_init(cls, frozen):
         _is_slot_cls(cls),
         cache_hash=False,
         base_attr_map={},
+        is_exc=False,
     )
     return cls
 
@@ -1376,7 +1417,7 @@ def _is_slot_attr(a_name, base_attr_map):
 
 
 def _attrs_to_init_script(
-    attrs, frozen, slots, post_init, cache_hash, base_attr_map
+    attrs, frozen, slots, post_init, cache_hash, base_attr_map, is_exc
 ):
     """
     Return a script of an initializer for *attrs* and a dict of globals.
@@ -1625,6 +1666,19 @@ def fmt_setter_with_converter(attr_name, value_var):
             init_hash_cache = "self.%s = %s"
         lines.append(init_hash_cache % (_hash_cache_field, "None"))
 
+    # On Python 2, it's necessary to set self.args for exceptions. We do it on
+    # *all* versions to keep around defaults.
+    if is_exc:
+        vals = "".join(("(self.", ", self.".join(a.name for a in attrs), ")"))
+
+        if frozen:
+            if slots:
+                lines.append("_setattr('args', %s)" % (vals,))
+            else:
+                lines.append("object.__setattr__(self, 'args', %s)" % (vals,))
+        else:
+            lines.append("self.args = " + vals)
+
     args = ", ".join(args)
     if kw_only_args:
         if PY2:

tests/test_dark_magic.py

@@ -508,3 +508,51 @@ class C(object):
         assert "property" == attr.fields(C).property.name
         assert "itemgetter" == attr.fields(C).itemgetter.name
         assert "x" == attr.fields(C).x.name
+
+    @pytest.mark.parametrize("slots", [True, False])
+    @pytest.mark.parametrize("frozen", [True, False])
+    def test_auto_exc(self, slots, frozen):
+        """
+        Classes with auto_exc=True have a Exception-style __str__, are neither
+        comparable nor hashable, and store the fields additionally in
+        self.args.
+        """
+
+        @attr.s(auto_exc=True, slots=slots, frozen=frozen)
+        class FooError(Exception):
+            x = attr.ib()
+            y = attr.ib(init=False, default=42)
+            z = attr.ib(init=False)
+            a = attr.ib()
+
+        FooErrorMade = attr.make_class(
+            "FooErrorMade",
+            bases=(Exception,),
+            attrs={
+                "x": attr.ib(),
+                "y": attr.ib(init=False, default=42),
+                "z": attr.ib(init=False),
+                "a": attr.ib(),
+            },
+            auto_exc=True,
+            slots=slots,
+            frozen=frozen,
+        )
+
+        assert FooError(1, "foo") != FooError(1, "foo")
+        assert FooErrorMade(1, "foo") != FooErrorMade(1, "foo")
+
+        for cls in (FooError, FooErrorMade):
+            with pytest.raises(cls) as ei:
+                raise cls(1, "foo")
+
+            e = ei.value
+
+            assert e is e
+            assert e == e
+            assert "(1, 42, 'foo')" == str(e)
+            # N.B. the default value 42 is preserved by setting args ourselves.
+            assert (1, 42, "foo") == e.args
+
+            with pytest.raises(TypeError):
+                hash(e)

tests/test_make.py

@@ -1425,7 +1425,9 @@ def test_repr(self):
         class C(object):
             pass
 
-        b = _ClassBuilder(C, None, True, True, False, False, False, False)
+        b = _ClassBuilder(
+            C, None, True, True, False, False, False, False, False
+        )
 
         assert "<_ClassBuilder(cls=C)>" == repr(b)
 
@@ -1437,7 +1439,9 @@ def test_returns_self(self):
         class C(object):
             x = attr.ib()
 
-        b = _ClassBuilder(C, None, True, True, False, False, False, False)
+        b = _ClassBuilder(
+            C, None, True, True, False, False, False, False, False
+        )
 
         cls = (
             b.add_cmp()
@@ -1500,6 +1504,7 @@ class C(object):
             frozen=False,
             weakref_slot=True,
             auto_attribs=False,
+            is_exc=False,
             kw_only=False,
             cache_hash=False,
         )

tests/typing_example.py

@@ -80,6 +80,20 @@ class HH(DD, EE):
 c == cc
 
 
+# Exceptions
+@attr.s(auto_exc=True)
+class Error(Exception):
+    x = attr.ib()
+
+
+try:
+    raise Error(1)
+except Error as e:
+    e.x
+    e.args
+    str(e)
+
+
 # Converters
 # XXX: Currently converters can only be functions so none of this works
 # although the stubs should be correct.