No traceback policy
===================

For end users, Python tracebacks provide little value: they are noisy, intimidating, and rarely actionable.
Wox follows a strict no-traceback policy to ensure that errors are communicated clearly, consistently, and without overwhelming technical output.

Instead of exposing raw tracebacks, Wox relies on a structured exception-handling system designed to report meaningful failures while keeping output clean.

Principles
----------

To achieve this, the following principles guide the design of the error-handling system:

- **A Wox session must always terminate gracefully**, regardless of what happens during execution.

- **Any error originating from Wox must correspond to a dedicated ``WoxException``**, ensuring consistent and predictable error reporting.

- **Raised ``WoxException`` errors must be logged** at the appropriate severity (usually ERROR).

- **If logging is unavailable**, the error message must be printed directly to the terminal to avoid silent failures.

- **Unhandled exceptions must be allowed to propagate to the entrypoint**, ensuring that unexpected failures are never silently swallowed.

Exit codes
----------

Wox returns **structured exit codes**, allowing external tools, CI pipelines, or shell scripts to determine whether the session completed successfully or failed.

This ensures that Wox remains both user-friendly and automation-friendly: clean output for humans, robust signaling for machines.

Exceptions handling
-------------------

| An application with multiple layers of try / except blocks are hard to follow. To not fall into this design flaw, I decided to create :doc:`wox exceptions </references/wox_exceptions>`.
| Those exceptions catch errors that might occur during the execution of wox. They are raised at specific locations where I expect those errors to be raised.


Then, I added try / except blocks on key features of wox. They catch any exceptions, log them as error and update the exit code.


By doing this, wox features are free of codes handling exceptions - because it is not their responsibilities, creating precise locations to look at when trying to handle exceptions - mostly main.py and subprocessor.py.
