Add Failure base class with spec-compliant metadata/details #45
Conversation
- Make raw_error_type optional in constructor, defaults to error_type.value - Preserve raw_error_type separately to handle unknown types from the wire - Remove unnecessary retryable_override property wrapper - Update docstring examples to show from_error_type() as primary API - Update usages to use from_error_type() - Enhance tests with explicit assertions for error_type and raw_error_type
…rType or a str to simplify the API surface
…inaccurate mypy linting error
…match statement rather than the classvar frozensets.
Add Failure as a base class for HandlerError and OperationError, representing protocol-level failures with message, stack_trace, metadata, details, and cause fields. Update HandlerError and OperationError to set their inherited Failure metadata and details properties according to the spec representation: - HandlerError: metadata["type"] = "nexus.HandlerError", details contains "type" (error type) and optionally "retryableOverride" - OperationError: metadata["type"] = "nexus.OperationError", details contains "state" (failed/canceled) User-provided metadata/details are merged but spec-required keys cannot be overridden. Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Change stack_trace from a simple attribute to a property - Return explicit stack_trace if provided, otherwise format __traceback__ - Return None when no stack trace is available (instead of empty string) - Add docstring explaining the property behavior - Add test verifying traceback capture for Failure, HandlerError, and OperationError Co-Authored-By: Claude Opus 4.5 <[email protected]>
- Add __repr__ to Failure, HandlerError, and OperationError for debugging - Make metadata and details immutable using MappingProxyType - Change Failure.details type from Any to Mapping[str, Any] | None - Add tests for explicit stack_trace precedence and immutability Co-Authored-By: Claude Opus 4.5 <[email protected]>
Replace custom `cause` attribute with Python's built-in exception chaining mechanism. This allows users to use standard Python syntax: `raise Failure(...) from other_exception` Co-Authored-By: Claude Opus 4.5 <[email protected]>
This allows consumers to distinguish between explicit stack traces (from deserialization/remote sources) and local tracebacks (via Python's native __traceback__). Co-Authored-By: Claude Opus 4.5 <[email protected]>
The docstring examples and :param documentation incorrectly referenced 'error_type' but the actual parameter is named 'type'. Updated docs and __repr__ output to be consistent with the parameter name. Co-Authored-By: Claude Opus 4.5 <[email protected]>
src/nexusrpc/_common.py
Outdated
| def __repr__(self) -> str: | ||
| return ( | ||
| f"Failure(message={self.message!r}, metadata={self.metadata!r}, " | ||
| f"details={self.details!r}, cause={self.__cause__!r})" | ||
| ) |
There was a problem hiding this comment.
Not sure this repr and those for the subclasses should be included or not. Open to opinions here!
|
I think this looks good, do we have the associated Python SDK changes ready? |
I have some changes that depend on this, but am reworking a bit to reflect the most recent API and our sync. Should have updated changes soon. |
src/nexusrpc/_common.py
Outdated
|
|
||
|
|
||
| class HandlerError(Exception): | ||
| class Failure(Exception): |
There was a problem hiding this comment.
Is this meant to map to the Failure concept in the Go SDK? If so I don't think it should inherit from exception
There was a problem hiding this comment.
Essentially yes. It's meant to map to the concept of Failure in the nexus-rpc spec which is also what Failure is in the Go SDK. I structured it this way b/c the spec talks about OperationError and HandlerError as predefined Failure types.
Is your suggestion to change it to just a plain dataclass and have the others inherit from exception?
There was a problem hiding this comment.
Hm so in the Go SDK Failure isn't an error so not sure in Python if this should be an exception. Also in the Go SDK Handler error and operation error have a original failure field that is the type Failure but that isn't the cause it represents the failure before it was deserialized.
There was a problem hiding this comment.
I've taken a pass at mirroring the behavior of the Go SDK, LMK what you think! I removed a lot of the details around how metadata/details of the failure get set for HandlerError and OperationError since that behavior was moved out of the Go SDK.
…out of HandlerError and OperationError in favor of having the transport layer handle that as necessary.
2 participants
Summary
Failuredataclass for protocol-level failures withmessage,stack_trace,metadata,details, andcausefieldsHandlerErrornow accepts string error types and preserves the raw value when unknown types are receivedHandlerError.stack_traceis an optional attribute for explicit stack trace strings (e.g., from deserialization or remote sources); for local tracebacks, consumers should use Python's native__traceback__attributeTest plan
uv run pytestto verify all tests passpoe lintto verify type checking and linting passtype: nexus.HandlerError/type: nexus.OperationError) and details fields🤖 Generated with Claude Code