feat(errors): add DBusFastError common base class (#634)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bluetoothbot

src/dbus_fast/__init__.py

@@ -13,6 +13,7 @@
 from .errors import (
     AuthError,
     DBusError,
+    DBusFastError,
     InterfaceNotFoundError,
     InvalidAddressError,
     InvalidBusNameError,
@@ -44,6 +45,7 @@
     "AuthError",
     "BusType",
     "DBusError",
+    "DBusFastError",
     "ErrorType",
     "InterfaceNotFoundError",
     "InvalidAddressError",

src/dbus_fast/errors.py

@@ -1,51 +1,61 @@
-class SignatureBodyMismatchError(ValueError):
+class DBusFastError(Exception):
+    """Common base class for all dbus-fast exceptions.
+
+    Catch this to handle any error raised by dbus-fast regardless of which
+    Python built-in exception type the specific error also derives from.
+    Existing ``except ValueError`` / ``except TypeError`` handlers continue
+    to work because individual error classes still inherit from those.
+    """
+
+
+class SignatureBodyMismatchError(ValueError, DBusFastError):
     pass
 
 
-class InvalidSignatureError(ValueError):
+class InvalidSignatureError(ValueError, DBusFastError):
     pass
 
 
-class InvalidAddressError(ValueError):
+class InvalidAddressError(ValueError, DBusFastError):
     pass
 
 
-class AuthError(Exception):
+class AuthError(DBusFastError):
     pass
 
 
-class InvalidMessageError(ValueError):
+class InvalidMessageError(ValueError, DBusFastError):
     pass
 
 
-class InvalidIntrospectionError(ValueError):
+class InvalidIntrospectionError(ValueError, DBusFastError):
     pass
 
 
-class InterfaceNotFoundError(Exception):
+class InterfaceNotFoundError(DBusFastError):
     pass
 
 
-class SignalDisabledError(Exception):
+class SignalDisabledError(DBusFastError):
     pass
 
 
-class InvalidBusNameError(TypeError):
+class InvalidBusNameError(TypeError, DBusFastError):
     def __init__(self, name: str) -> None:
         super().__init__(f"invalid bus name: {name}")
 
 
-class InvalidObjectPathError(TypeError):
+class InvalidObjectPathError(TypeError, DBusFastError):
     def __init__(self, path: str) -> None:
         super().__init__(f"invalid object path: {path}")
 
 
-class InvalidInterfaceNameError(TypeError):
+class InvalidInterfaceNameError(TypeError, DBusFastError):
     def __init__(self, name: str) -> None:
         super().__init__(f"invalid interface name: {name}")
 
 
-class InvalidMemberNameError(TypeError):
+class InvalidMemberNameError(TypeError, DBusFastError):
     def __init__(self, member: str) -> None:
         super().__init__(f"invalid member name: {member}")
 
@@ -55,7 +65,7 @@ def __init__(self, member: str) -> None:
 from .validators import assert_interface_name_valid  # noqa: E402
 
 
-class DBusError(Exception):
+class DBusError(DBusFastError):
     def __init__(
         self, type_: ErrorType | str, text: str, reply: Message | None = None
     ) -> None:

tests/test_errors.py

@@ -0,0 +1,152 @@
+"""Tests for the exception hierarchy in ``dbus_fast.errors``.
+
+The hierarchy was introduced to let callers catch every dbus-fast error with
+``except DBusFastError`` without giving up the historical ability to catch
+specific built-in types like ``ValueError`` or ``TypeError`` for individual
+classes (see GH #507).
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from dbus_fast import (
+    AuthError,
+    DBusError,
+    DBusFastError,
+    InterfaceNotFoundError,
+    InvalidAddressError,
+    InvalidBusNameError,
+    InvalidInterfaceNameError,
+    InvalidIntrospectionError,
+    InvalidMemberNameError,
+    InvalidMessageError,
+    InvalidObjectPathError,
+    InvalidSignatureError,
+    SignalDisabledError,
+    SignatureBodyMismatchError,
+)
+
+_ALL_ERRORS = [
+    AuthError,
+    DBusError,
+    InterfaceNotFoundError,
+    InvalidAddressError,
+    InvalidBusNameError,
+    InvalidInterfaceNameError,
+    InvalidIntrospectionError,
+    InvalidMemberNameError,
+    InvalidMessageError,
+    InvalidObjectPathError,
+    InvalidSignatureError,
+    SignalDisabledError,
+    SignatureBodyMismatchError,
+]
+
+
+@pytest.mark.parametrize("err_cls", _ALL_ERRORS)
+def test_all_errors_share_dbus_fast_base(err_cls: type[BaseException]) -> None:
+    assert issubclass(err_cls, DBusFastError)
+    assert issubclass(err_cls, Exception)
+
+
+@pytest.mark.parametrize(
+    "err_cls",
+    [
+        SignatureBodyMismatchError,
+        InvalidSignatureError,
+        InvalidAddressError,
+        InvalidMessageError,
+        InvalidIntrospectionError,
+    ],
+)
+def test_value_error_subclasses_preserved(err_cls: type[BaseException]) -> None:
+    assert issubclass(err_cls, ValueError)
+
+
+@pytest.mark.parametrize(
+    "err_cls",
+    [
+        InvalidBusNameError,
+        InvalidObjectPathError,
+        InvalidInterfaceNameError,
+        InvalidMemberNameError,
+    ],
+)
+def test_type_error_subclasses_preserved(err_cls: type[BaseException]) -> None:
+    assert issubclass(err_cls, TypeError)
+
+
+def test_value_error_subclass_mro_order() -> None:
+    """Built-in ``ValueError`` must precede ``DBusFastError`` in the MRO.
+
+    This ordering ensures ``super().__init__`` routes through
+    ``ValueError.__init__`` rather than skipping straight to
+    ``Exception.__init__``, preserving the behavior of the historical
+    single-inheritance ``ValueError`` subclasses.
+    """
+    mro = InvalidSignatureError.__mro__
+    assert mro.index(ValueError) < mro.index(DBusFastError)
+
+
+def test_type_error_subclass_mro_order() -> None:
+    """Built-in ``TypeError`` must precede ``DBusFastError`` in the MRO.
+
+    Same rationale as the ``ValueError`` MRO test: keeps ``super().__init__``
+    routing through ``TypeError.__init__`` to match the original
+    single-inheritance ``TypeError`` subclasses.
+    """
+    mro = InvalidBusNameError.__mro__
+    assert mro.index(TypeError) < mro.index(DBusFastError)
+
+
+def test_dbus_fast_error_catches_value_error_subclass() -> None:
+    with pytest.raises(DBusFastError):
+        raise SignatureBodyMismatchError("body mismatch")
+
+
+def test_dbus_fast_error_catches_type_error_subclass() -> None:
+    with pytest.raises(DBusFastError):
+        raise InvalidBusNameError("not.a.valid.bus.name!")
+
+
+def test_value_error_still_catches_signature_errors() -> None:
+    with pytest.raises(ValueError):
+        raise InvalidSignatureError("bad signature")
+
+
+def test_type_error_still_catches_name_errors() -> None:
+    with pytest.raises(TypeError):
+        raise InvalidMemberNameError("1bad")
+
+
+def test_invalid_bus_name_error_message_unchanged() -> None:
+    err = InvalidBusNameError("bad")
+    assert str(err) == "invalid bus name: bad"
+
+
+def test_invalid_object_path_error_message_unchanged() -> None:
+    err = InvalidObjectPathError("nope")
+    assert str(err) == "invalid object path: nope"
+
+
+def test_invalid_interface_name_error_message_unchanged() -> None:
+    err = InvalidInterfaceNameError("bad.iface")
+    assert str(err) == "invalid interface name: bad.iface"
+
+
+def test_invalid_member_name_error_message_unchanged() -> None:
+    err = InvalidMemberNameError("1bad")
+    assert str(err) == "invalid member name: 1bad"
+
+
+def test_dbus_error_inherits_dbus_fast_error() -> None:
+    err = DBusError("org.freedesktop.DBus.Error.Failed", "boom")
+    assert isinstance(err, DBusFastError)
+    assert err.type == "org.freedesktop.DBus.Error.Failed"
+    assert err.text == "boom"
+
+
+def test_dbus_fast_error_directly_raisable() -> None:
+    with pytest.raises(DBusFastError):
+        raise DBusFastError("plain base class")