Commands execution
==================

Wox executes commands through the subprocessor, a module built on top of Python’s standard subprocess library.


| The subprocessor runs commands exactly as they would be executed in your terminal: any CLI program can be run (python, pytest, docker, npm, etc...) and commands requiring interactive input, such as a sudo password prompt, will work because the subprocess is attached to the terminal.
| Additionally, it provides essential features for reliable automation: command sanitization, error detection, and logging of everything that occurs during the subprocess execution.

Command sanitization
--------------------

Since the commands declared in the wox.toml file are provided as plain strings, it is necessary to sanitize them, that is, convert them into a validated and executable form.

Once sanitized, the command is guaranteed to be safe, valid, and bound to the Python virtual environment in which it will be executed.

Error detection
---------------

Raw subprocess failures do not naturally propagate meaningful exceptions. Most errors surface only as text written to stderr or as a non-zero return code, neither of which is structured or informative enough for automation.

| To improve readability and ease troubleshooting, Wox includes a custom error-detection layer that interprets subprocess output and raises specific exceptions instead of opaque failures.
| The goal is not to detect every possible error, but to identify the most common issues encountered during task execution, such as:

- dependency installation conflicts;
- unstable Python builds;
- system-related conditions that prevent a command from completing;

If no known error matches but the command still fails, Wox falls back to raising the standard subprocess exception.

Logging during subprocess
-------------------------

| To provide a complete trace of the session, Wox logs everything produced by the subprocess.
| The subprocessor behaves as a neutral observer: it forwards the program’s output unchanged and records it at the INFO level.
| This includes stdout and stderr exactly as emitted.

.. important::
    Wox’s logging does not interfere with the logging of the program being executed.
    Both systems remain fully independent: your application logs exactly as usual while Wox captures the output for session inspection.
