Use cases
=========

Wox and non-Python tool (like npm)
------------------------------------

| Wox never assumes an environment must be Python-based.
| Any directory listed in envlist is treated as an execution root and used as-is, which makes it compatible with Node, Go, Rust, or any custom binary.

Example with a node_env environment with node and npm inside:

.. code-block::  toml

    [wox_configuration]

    [task]
    envlist = ['nodeenv']
    commands = ['npm install', 'npm run build']

Use of portable or embedded Python
----------------------------------

Wox only expects the Python interpreter to run regardless of the installation method.

The following all work:

- Windows embeddable Python;

- Portable Python (copied from another location);

- Custom-compiled builds;

- Python extracted from a zip archive.

If it runs, wox runs it.

Dependencies installation that are not actual dependencies
----------------------------------------------------------

Wox uses the deps setting as a raw argument injector for pip / uv pip, which allows to go in "insaneo style":

.. code-block::  toml

    deps = [
        '--upgrade pip',
        '--no-cache-dir',
        '-r requirements-dev.txt',
        'git+https://github.com/whatever',
        '-e ~/workspace/myproject'
    ]

Wox does not validate the meaning — the underlying installer does.

Use a single task as a modular shell-script
-------------------------------------------

Tasks execute commands sequentially, which makes them usable as lightweight, portable build scripts.

.. code-block::  toml

    commands = [
        'echo step1',
        'mkdir -p build',
        'python -c "print(\"inline python!\")"',
        'echo finished'
    ]

All executables run correctly (echo, mkdir, git, docker, etc...).

But Unix shell syntax is not interpreted (because wox uses subprocess with shell=False):

- echo foo > file

- python script.py | grep x

- echo a && echo b

- FOO=bar cmd

- mkdir {a,b}

Create an immutable environment
-------------------------------

An environment located inside .wox can be set to read-only and still be used by wox.


| Wox only writes inside .wox/<env>/ during venv creation or dependency installation.
| If an environment is already present and marked read-only, wox simply executes commands inside it and does not attempt to modify it.
