#3516 refactor: Formalize our exception hierarchy
Pull request opened by
edgarrmondragon
SSIA
Summary by Sourcery
Introduce a formal, centralized exception hierarchy for the Singer SDK and document its design and usage.
New Features:
• Add a common SingerSDKError root base class and structured intermediate exception types for configuration, discovery, mapping, sync, and lifecycle control-flow.
• Expose a curated
all export list for all public SDK exceptions.
• Add detailed implementation and design documentation for the exception hierarchy, including guidance on choosing exception types.
Enhancements:
• Refactor existing exceptions to inherit from the new hierarchy rather than directly from Exception, preserving existing names for backward compatibility.
• Introduce IgnorableSyncError, DataError, SyncLifecycleSignal, and other semantic groupings to encode recovery behavior in exception types.
• Clarify lifecycle-related abort and pause exceptions by grouping them under a dedicated SyncLifecycleSignal base class.
• Add project contributor guidance in CLAUDE.md on where and how to define new exceptions and how to extend the hierarchy.
Documentation:
• Add an implementation reference section for errors, documenting the full exception hierarchy and design rationale, and link it into the implementation index.
meltano/sdk