Python discovery
================

Wox is able to automatically discover Python interpreters, which is essential for tasks that must run on several Python versions.


| Unlike tools that rely on filesystem lookups (``which python3.11`` on Linux, ``py -0p`` on Windows, PATH scanning, or symlink resolution), wox takes a more reliable and empirical approach: it actually executes candidate Python commands in a subprocess and observes the result.
| If the command runs successfully, wox considers the interpreter valid.

This strategy has several practical advantages:

- **no dependency on PATH:** Wox does not rely on environment variables to discover Python installations. Even interpreters that are *not* registered globally can be detected as long as they can be executed.

- **no dependency on symlinks:** Wox does not search through ``/usr/bin/python*`` or follow symlink chains. Python installations that live in arbitrary directories are fully supported.

- **no dependency on the Windows Python Launcher:** Wox does not require ``py.exe`` to be installed. It works equally well with embedded builds, custom CPython builds, or Python installations that do not register themselves with ``py``.

.. note::

   Wox reserves environment names of the form ``py3x`` (e.g. ``py310``,
   ``py314``) exclusively for interpreter discovery by version.  
   These names instruct Wox to look for a Python interpreter matching the
   corresponding major.minor version.

   For such environments, Wox attempts the following commands depending on the
   platform:

   - on Windows: ``py -<major.minor version>`` (if the Python Launcher is available);
   - on Linux/macOS: ``python<major.minor version>``;

   If no executable matching the requested version can be found or executed,
   Wox raises ``PythonInterpreterNotFoundError``.


Because of this execution-based discovery method, wox is compatible with a wide
range of Python distributions, including custom builds compiled from source,
embedded distributions, portable bundles, and other interpreters that may not
appear in conventional system lookup mechanisms.
