Add generic exception handlers

Shortcake-Parent: main

Author: patrick91

CONTRIBUTING.md

@@ -161,10 +161,10 @@ release type: patch
 social_messages:
   x: >-
     {project_name} {version} is out! This release fixes schema printing for
-    nullable input defaults. https://strawberry.rocks/release/{version}
+    nullable input defaults. 🍓 https://strawberry.rocks/release/{version}
   linkedin: >-
     {project_name} {version} is out. This release fixes schema printing for
-    nullable input defaults so generated SDL now keeps explicit null values.
+    nullable input defaults, so generated SDL now keeps explicit null values.
 ---
 
 This release fixes schema printing for nullable input defaults.
@@ -180,5 +180,7 @@ doubt feel free to ask.
 Release notes should start with `This release adds ...` or
 `This release fixes ...` and should explain the user-visible behavior first.
 Include social messages for X and LinkedIn so the release announcement reads
-well on each platform. X messages must include the website release URL template:
+well on each platform. They should read like natural release announcements,
+start with `{project_name} {version} is out`, and explain what changed and who
+benefits. X messages must include the website release URL template:
 `https://strawberry.rocks/release/{version}`.

RELEASE.md

@@ -0,0 +1,68 @@
+---
+release type: minor
+social_messages:
+  x: >-
+    {project_name} {version} is out! This release adds exception handlers, a building block for integrations that want to turn expected Python errors into typed GraphQL results. 🍓 https://strawberry.rocks/release/{version}
+  linkedin: >-
+    {project_name} {version} is out. This release adds exception handlers, a schema-level hook for integrations that need to turn framework validation errors, such as Pydantic errors, into typed GraphQL union results. Most applications will not need to use this directly, but it gives framework integrations a cleaner path without adding try/except blocks to every resolver.
+---
+
+This release adds configurable exception handlers that map Python exceptions to
+typed GraphQL union results.
+
+Most applications do not need to adopt this directly. It is primarily useful for
+integrations and framework-level helpers: for example, catching validation
+exceptions from a library such as Pydantic and exposing them as an explicit
+GraphQL error type, without requiring every resolver to catch and convert those
+exceptions manually.
+
+Handlers are passed to `strawberry.Schema` (and `strawberry.federation.Schema`):
+
+```python
+import strawberry
+from strawberry.types.field import StrawberryField
+
+
+class ValidationProblem(Exception):
+    pass
+
+
+@strawberry.type
+class ValidationError:
+    message: str
+
+
+class ValidationErrorHandler(
+    strawberry.ExceptionHandler[ValidationProblem, ValidationError]
+):
+    def handle(
+        self,
+        exception: ValidationProblem,
+        *,
+        field: StrawberryField,
+        info: strawberry.Info,
+    ) -> ValidationError:
+        return ValidationError(message=str(exception))
+
+
+schema = strawberry.Schema(
+    query=Query,
+    mutation=Mutation,
+    exception_handlers=[ValidationErrorHandler()],
+)
+```
+
+Handlers can alternatively declare `exception_type` and `error_type` class
+attributes instead of type parameters, which also covers types that are only
+known at runtime. Declaring both a type parameter and a conflicting attribute
+for the same slot raises an error at schema creation.
+
+Strawberry only converts the exception when the field return type includes the
+handler's GraphQL error type. Other fields continue to raise normal GraphQL
+errors, so applications can opt in one field at a time. Exceptions raised by
+the resolver, during argument conversion, or by field extensions are all
+covered.
+
+Exception handlers apply to query and mutation fields. Subscriptions are not
+covered: exceptions raised while establishing a subscription are not converted
+into union results.

docs/guides/errors.md

@@ -311,6 +311,152 @@ This approach allows you to express the possible error states in the schema and
 so provide a robust interface for your client to account for all the potential
 outcomes from a mutation.
 
+### Mapping expected exceptions to union results
+
+If your application or integration already raises a specific exception for an
+expected failure, you can map that exception to one of the GraphQL error types
+in the field's return union by passing `exception_handlers` to
+`strawberry.Schema`.
+
+```python
+import strawberry
+from strawberry.types import Info
+from strawberry.types.field import StrawberryField
+
+
+class UsernameAlreadyExists(Exception):
+    def __init__(self, username: str):
+        self.username = username
+
+
+@strawberry.type
+class RegisterUserSuccess:
+    user: User
+
+
+@strawberry.type
+class UsernameAlreadyExistsError:
+    username: str
+
+
+class UsernameAlreadyExistsHandler(
+    strawberry.ExceptionHandler[UsernameAlreadyExists, UsernameAlreadyExistsError]
+):
+    def handle(
+        self,
+        exception: UsernameAlreadyExists,
+        *,
+        field: StrawberryField,
+        info: Info,
+    ) -> UsernameAlreadyExistsError:
+        return UsernameAlreadyExistsError(username=exception.username)
+
+
+@strawberry.type
+class Mutation:
+    @strawberry.mutation
+    def register_user(
+        self, username: str, password: str
+    ) -> RegisterUserSuccess | UsernameAlreadyExistsError:
+        # create_user may raise UsernameAlreadyExists
+        user = create_user(username, password)
+        return RegisterUserSuccess(user=user)
+
+
+schema = strawberry.Schema(
+    query=Query,
+    mutation=Mutation,
+    exception_handlers=[UsernameAlreadyExistsHandler()],
+)
+```
+
+Strawberry only converts exceptions when both of these are true:
+
+- the exception is an instance of the handler's declared exception type
+- the field return type is a union, or nullable union, containing the handler's
+  declared error type
+
+The two type parameters — the exception type the handler receives and the
+GraphQL error type it returns — are the single source of truth: they drive the
+matching at runtime, and type checkers use them to verify the signature of
+`handle` against the declared types.
+
+To map several Python exception classes to the same GraphQL error type,
+parameterize the handler with their union, e.g.
+`strawberry.ExceptionHandler[ErrorA | ErrorB, MyErrorType]`.
+
+If you prefer explicit class attributes — or you are not using a type checker —
+the same handler can declare its types with `exception_type` and `error_type`
+attributes instead of type parameters:
+
+```python
+class UsernameAlreadyExistsHandler(strawberry.ExceptionHandler):
+    exception_type = UsernameAlreadyExists
+    error_type = UsernameAlreadyExistsError
+
+    def handle(self, exception, *, field, info):
+        return UsernameAlreadyExistsError(username=exception.username)
+```
+
+With this style `exception_type` accepts a single exception type or a tuple of
+them, and the attributes also cover types that are only known at runtime. You
+can mix the styles — for example parameterize the exception and supply a
+runtime-only `error_type` as an attribute — but declaring both a type parameter
+and a conflicting attribute for the same slot raises a `TypeError` at schema
+creation. Note that type checkers will not verify the signature of `handle` when
+you use attributes.
+
+Handlers cover exceptions raised by the resolver, during argument conversion,
+and by field extensions (for example a permission or validation extension
+wrapping the field). Argument conversion runs before the field-extension chain,
+so a conversion error is mapped directly and bypasses the field extensions —
+matching how conversion errors have always been raised before permissions run.
+Field extensions may catch or transform resolver exceptions before the handler
+sees the final exception leaving the extension chain.
+
+If multiple handlers match, Strawberry uses the first matching handler from the
+`exception_handlers` list. Handlers do not apply to subscription fields or to
+list fields such as `list[Success | UsernameAlreadyExistsError]`.
+
+A handler can decline an individual exception by returning `None` (or an
+awaitable resolving to `None`). Declining re-raises the original exception, so
+it propagates as a normal GraphQL error as if no handler had matched. This lets
+`handle` act as a per-instance filter — match a broad exception type, but only
+convert the instances you recognize:
+
+```python
+class ValidationErrorHandler(
+    strawberry.ExceptionHandler[ValidationProblem, ValidationError]
+):
+    def handle(
+        self,
+        exception: ValidationProblem,
+        *,
+        field: StrawberryField,
+        info: Info,
+    ) -> ValidationError | None:
+        if exception.is_user_facing:
+            return ValidationError(message=str(exception))
+        # Not one we want to expose — let it propagate as a normal error.
+        return None
+```
+
+When the error type is generic, parameterize the handler with the concrete
+instantiation that appears in the union (for example
+`strawberry.ExceptionHandler[MyError, ValidationError[int]]`), rather than the
+bare generic (`ValidationError`), so it matches the correct member of the union.
+
+Converted exceptions are treated as expected GraphQL results. They are not added
+to the response's top-level `errors` list and are not passed to
+`Schema.process_errors`, so avoid using broad exception types such as
+`Exception` unless every matching error is safe to expose as a typed result.
+
+On a synchronously executed field, `handle` must return its result
+synchronously. An `async` handler returns a coroutine, which fails the same way
+an `async` resolver does on a sync field: `execute_sync` returns an
+`ExecutionResult` whose `errors` contain a `GraphQLError` stating that execution
+could not complete synchronously.
+
 ---
 
 ## Additional resources:

docs/types/schema.md

@@ -108,6 +108,12 @@ schema = strawberry.Schema(Query, types=[Individual, Company])
 
 List of [extensions](/docs/extensions) to add to your Schema.
 
+#### `exception_handlers: Iterable[ExceptionHandler] = ()`
+
+List of handlers that convert expected Python exceptions into typed GraphQL
+union results. See
+[dealing with expected errors](/docs/guides/errors#mapping-expected-exceptions-to-union-results).
+
 #### `scalar_overrides: Optional[Dict[object, ScalarWrapper]] = None`
 
 Override the implementation of the built in scalars.

strawberry/__init__.py

@@ -9,7 +9,7 @@
 from .parent import Parent
 from .permission import BasePermission
 from .scalars import ID
-from .schema import Schema
+from .schema import ExceptionHandler, Schema
 from .schema_directive import schema_directive
 from .streamable import Streamable
 from .types.arguments import argument
@@ -31,6 +31,7 @@
     "ID",
     "UNSET",
     "BasePermission",
+    "ExceptionHandler",
     "Info",
     "LazyType",
     "Maybe",

strawberry/exceptions/handler.py

@@ -10,7 +10,10 @@
 original_threading_exception_hook = threading.excepthook
 
 
-ExceptionHandler = Callable[
+# Signature of ``sys.excepthook`` / ``threading.excepthook`` handlers. Named
+# ``ExcepthookHandler`` (not ``ExceptionHandler``) to avoid colliding with the
+# public ``strawberry.ExceptionHandler`` schema protocol.
+ExcepthookHandler = Callable[
     [type[BaseException], BaseException, TracebackType | None], None
 ]
 
@@ -21,7 +24,7 @@ def should_use_rich_exceptions() -> bool:
     return errors_disabled.lower() not in ["true", "1", "yes"]
 
 
-def _get_handler(exception_type: type[BaseException]) -> ExceptionHandler:
+def _get_handler(exception_type: type[BaseException]) -> ExcepthookHandler:
     if issubclass(exception_type, StrawberryException):
         try:
             import rich

strawberry/federation/schema.py

@@ -36,6 +36,7 @@
     from strawberry.extensions import SchemaExtension
     from strawberry.federation.schema_directives import ComposeDirective
     from strawberry.schema.config import StrawberryConfig
+    from strawberry.schema.exception_handlers import ExceptionHandler
     from strawberry.schema_directive import StrawberrySchemaDirective
     from strawberry.types.enum import StrawberryEnumDefinition
 
@@ -75,6 +76,7 @@ def __init__(
             "2.10",
             "2.11",
         ] = "2.11",
+        exception_handlers: Iterable["ExceptionHandler[Any]"] = (),
     ) -> None:
         # Convert version string (e.g., "2.5") to version tuple (e.g., (2, 5))
         self.federation_version = parse_version(federation_version)
@@ -110,6 +112,7 @@ def __init__(
             config=config,
             scalar_overrides=federation_scalar_overrides,
             schema_directives=schema_directives,
+            exception_handlers=exception_handlers,
         )
 
         self.schema_directives = list(schema_directives)

strawberry/schema/__init__.py

@@ -1,4 +1,5 @@
 from .base import BaseSchema
+from .exception_handlers import ExceptionHandler
 from .schema import Schema
 
-__all__ = ["BaseSchema", "Schema"]
+__all__ = ["BaseSchema", "ExceptionHandler", "Schema"]

strawberry/schema/base.py

@@ -12,6 +12,7 @@
     from graphql import GraphQLError
 
     from strawberry.directive import StrawberryDirective
+    from strawberry.schema.exception_handlers import ExceptionHandler
     from strawberry.schema.schema import StreamResult, SubscriptionResult
     from strawberry.schema.schema_converter import GraphQLCoreConverter
     from strawberry.types import (
@@ -37,6 +38,7 @@ class BaseSchema(Protocol):
     mutation: type[WithStrawberryObjectDefinition] | None
     subscription: type[WithStrawberryObjectDefinition] | None
     schema_directives: list[object]
+    exception_handlers: tuple[ExceptionHandler[Any], ...]
 
     @abstractmethod
     async def execute(