Add Failure base class with spec-compliant metadata/details #45
+495
−114
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- 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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
- 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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
VegetarianOrc
commented
Feb 2, 2026
Comment on lines
+73
to
+77
| def __repr__(self) -> str: | ||
| return ( | ||
| f"Failure(message={self.message!r}, metadata={self.metadata!r}, " | ||
| f"details={self.details!r}, cause={self.__cause__!r})" | ||
| ) |
Collaborator
Author
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? |
Collaborator
Author
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. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Failurebase class for protocol-level failures withmessage,stack_trace,metadata,details, andcausefieldsHandlerErrorandOperationErrorto inherit fromFailureand set spec-compliant metadata/details automaticallyHandlerErrornow accepts string error types and preserves the raw value when unknown types are receivedFailure.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