Relevant source files

The following files were used as context for generating this wiki page: - [src/my\_unicorn/exceptions.py](https://github.com/Cyber-Syntax/my-unicorn/blob/main/src/my_unicorn/exceptions.py) - [AGENTS.md](https://github.com/Cyber-Syntax/my-unicorn/blob/main/AGENTS.md) - [tests/test\_exceptions.py](https://github.com/Cyber-Syntax/my-unicorn/blob/main/tests/test_exceptions.py) - [src/my\_unicorn/core/update/manager.py](https://github.com/Cyber-Syntax/my-unicorn/blob/main/src/my_unicorn/core/update/manager.py) - [tests/core/update/test\_manager\_errors.py](https://github.com/Cyber-Syntax/my-unicorn/blob/main/tests/core/update/test_manager_errors.py) - [tests/core/verification/test\_verification\_errors.py](https://github.com/Cyber-Syntax/my-unicorn/blob/main/tests/core/verification/test_verification_errors.py)

# Exception Hierarchy & Error Handling The Exception Hierarchy and Error Handling system in My Unicorn is designed to provide robust, traceable, and user-friendly error reporting across the application's CLI and core services. By utilizing a structured hierarchy of custom exceptions, the system distinguishes between recoverable network issues, configuration errors, and critical workflow failures. The architecture emphasizes "Async Safe" operations and strict guidelines against leaking sensitive data or unnecessary stack traces during expected failure modes. It integrates closely with the logging system to provide context-rich error messages that include specific app names, target files, and metadata such as retry intervals. Sources: [AGENTS.md](), [tests/test_exceptions.py:27-104]() ## Core Exception Hierarchy All custom exceptions in the project derive from a single base class, `MyUnicornError`. This hierarchy allows the application to catch specific errors at the granular level (e.g., a hash mismatch) or handle broad categories of failures (e.g., any verification error) through inheritance. ### Class Diagram: Exception Structure The following diagram illustrates the relationship between the base error class and its specialized descendants. ```mermaid classDiagram class MyUnicornError { +str message +str target +dict context +bool is_retryable +int retry_after } class VerificationError { +str error_prefix } class NetworkError { +str url +int status_code } class WorkflowError { +str error_prefix } class ConfigurationError { +str config_path +str field } MyUnicornError <|-- VerificationError MyUnicornError <|-- NetworkError MyUnicornError <|-- WorkflowError MyUnicornError <|-- ConfigurationError MyUnicornError <|-- ValidationError MyUnicornError <|-- LockError VerificationError <|-- HashMismatchError VerificationError <|-- HashUnavailableError VerificationError <|-- HashComputationError NetworkError <|-- DownloadError NetworkError <|-- GitHubAPIError WorkflowError <|-- InstallError WorkflowError <|-- UpdateError WorkflowError <|-- PostProcessingError ``` Sources: [tests/test_exceptions.py:271-315]() ### Base Error Components The `MyUnicornError` class and its variants support several key metadata fields to assist in error resolution: | Field | Description | Source | | :--- | :--- | :--- | | `message` | A descriptive string explaining the failure. | [tests/test_exceptions.py:31]() | | `target` | The specific application or file associated with the error (e.g., "qownnotes"). | [tests/test_exceptions.py:39]() | | `context` | A dictionary containing technical metadata (e.g., `expected_hash`, `actual_hash`). | [tests/test_exceptions.py:153]() | | `is_retryable` | A boolean indicating if the operation can be safely attempted again. | [tests/test_exceptions.py:56]() | | `retry_after` | An integer specifying the wait time (in seconds) before a retry. | [tests/test_exceptions.py:57]() | ## Specialized Error Modules ### Verification & Security Errors Verification errors occur during the integrity check of downloaded AppImages. The system supports multiple verification methods simultaneously, where a failure in one method (like a checksum file download timeout) does not necessarily block other methods (like a direct digest check). * **HashMismatchError**: Raised when the computed hash of a file does not match the expected value from the provider. * **HashUnavailableError**: Triggered when no checksums are provided by the developer, often resulting in a user warning rather than a hard failure if configured. * **HashComputationError**: Occurs if the system fails to read the file or compute the hash locally (e.g., `OSError`). Sources: [tests/core/verification/test_verification_errors.py:64-110](), [tests/test_exceptions.py:143-176]() ### Network & API Errors These exceptions handle I/O operations with the GitHub API and asset servers. They are typically marked as `is_retryable=True` with a default `retry_after` of 5 seconds. * **GitHubAPIError**: Specific to GitHub interactions, handling cases like 401 Unauthorized (Authentication required) or 429 Rate Limit Exceeded. * **DownloadError**: Specifically for file download failures, including 404 Not Found or connection timeouts. Sources: [src/my_unicorn/core/update/manager.py:335-350](), [tests/test_exceptions.py:214-233]() ## Error Handling Logic & Data Flow The application follows a structured flow for catching and reporting errors, particularly within the `UpdateManager`. When a single app update fails, the system captures the specific exception and converts it into a standardized `UpdateInfo` error object to prevent one failed app from crashing a batch update process. ### Sequence Diagram: Update Error Handling This diagram shows how the `UpdateManager` processes an exception during an update check. ```mermaid sequenceDiagram participant UM as UpdateManager participant GH as GitHub API participant Log as Logger participant UI as UpdateInfo UM->>GH: Fetch Release Data alt HTTP 401 Error GH--xUM: ClientResponseError(401) UM->>Log: exception("Unauthorized (401)") UM->>UI: create_error("Authentication required") else Generic Exception GH--xUM: RuntimeError UM->>Log: exception("Unexpected error") UM->>UI: create_error("Unexpected error...") end UM-->>UM: Return Error Object ``` Sources: [src/my_unicorn/core/update/manager.py:335-361](), [tests/core/update/test_manager_errors.py:44-80]() ### Best Practices for Developers According to the project guidelines, error handling must adhere to the following standards: 1. **Use Custom Exceptions**: Always use exceptions from `my_unicorn.exceptions` rather than generic `Exception` or `ValueError`. 2. **Graceful Handling**: Use `logger.warning` or `logger.info` for expected failures (like a missing optional config). 3. **Avoid Stack Traces**: Do not use `logger.exception()` for expected errors as it leaks unnecessary stack traces into the logs. 4. **No Sensitive Data**: Never log tokens, passwords, or sensitive keys in error messages or context dictionaries. Sources: [AGENTS.md: "Error Handling Guidelines"]() ## Summary The Exception Hierarchy and Error Handling system provides a standardized way to manage failures. By categorizing errors into Verification, Network, Workflow, and Configuration domains, My Unicorn ensures that users receive actionable feedback while the core engine maintains stability during complex, concurrent operations. Integrated retry logic and context-rich metadata further enhance the resilience of the AppImage management workflow.