Quickstart
==========

Let's begin with a complete example of a wox task that will create a Python virtual environment, install a dependency in that environment, and then run a command using the activated environment.

To create this task, declare it in the wox.toml or pyproject.toml like so:

.. tab-set::

    .. tab-item:: wox.toml

        .. code-block:: toml

            [wox_configuration]

            [showcase]
            envlist = ['default']
            deps = ['cowsay==6.1']
            commands = ['cowsay -t "Hello Wox!" -c "tux"']
    
    .. tab-item:: pyproject.toml
        
        .. code-block:: toml

            [tool.wox.wox_configuration]

            [tool.wox.showcase]
            envlist = ['default']
            deps = ['cowsay==6.1']
            commands = ['cowsay -t "Hello Wox!" -c "tux"']

The task is run during a wox session. The wox session starts with the command 'wox' on the terminal.

.. figure:: ../_static/screenshots/hello-wox.png
    :alt: hello wox
    :align: center
    :class: zoomable-image

    Output of task "showcase"

In spite of the apparent simplicity of this task, wox performs several operations behind the scenes:

- :doc:`initializing the .wox workspace </references/wox_workspace>`;
- :doc:`discovering the Python interpreter to use </references/python_discovery>`;
- :doc:`creating the virtual environment </references/virtual_environment>`;
- :doc:`installing the declared dependencies </references/dependencies_installation>`;
- :doc:`executing the commands using the declared environment </references/commands_execution>`;
- :ref:`logging all actions performed during the session <wox_logging>`;
- :doc:`rendering a summary of the session in the console </references/wox_summary>`.

What kind of task can wox run?
------------------------------

Testing
^^^^^^^

| Testing an application across multiple Python versions is one of the most common use cases for wox.
| It can automatically create separate virtual environments for each interpreter, install the required dependencies, and run your test suite in each environment.

.. note::

    Wox provides an alternative workflow to existing test automation tools by focusing on simplicity, explicit configuration, and direct alignment with standard Python mechanisms such as ``venv``. 

As an example, here is how wox ensures its own compatibility across Python versions:

.. code-block:: toml

    [wox_configuration]

    recreate_envs = false

    [testing]
    envlist = ['py310', 'py311', 'py312', 'py313', 'py314']
    deps = ['-r requirements.txt', '-e .']
    commands = ['python -B -m pytest']

.. _build_comparison:

Builds comparison
^^^^^^^^^^^^^^^^^

Wox also makes it possible to compare how your application behaves across multiple Python builds, including custom builds created by tweaking various `configuration options <https://docs.python.org/3.13/using/configure.html>`_.


This is particularly useful because an incorrectly configured build can produce what we may call a “corrupted” Python - one that appears to work normally, but will eventually fail when executing specific code paths. Wox helps guard against such issues by allowing you to declare a comparison task like this:

.. tab-set::

    .. tab-item:: Python dev vs Python prod

        .. code-block:: toml

            [wox_configuration]

            recreate_envs = false

            [comparing]
            envlist = ['python-dev', 'python-prod', 'python-control']
            deps = ['-r requirements.txt', '-e .']
            commands = ['python -B -m pytest']

            python_build = '<path/to/regular-python/binary>'

            [comparing.python-dev]
            python_build = '<path/to/python-dev/binary>'

            [comparing.python-prod]
            python_build = '<path/to/python-prod/binary>'

    .. tab-item:: Python GIL vs Python no-GIL

        .. code-block:: toml

            [wox_configuration]

            recreate_envs = false

            [comparing]
            envlist = ['python-gil', 'python-no-gil']
            deps = ['-r requirements.txt', '-e .']
            commands = ['python -B -m pytest']

            [comparing.python-gil]
            python_build = '<path/to/python-gil/binary>'

            [comparing.python-no-gil]
            python_build = '<path/to/python-no-gil/binary>'

With the arrival of Python 3.14, this becomes the most straightforward way to ensure your application behaves consistently - or even more efficiently - when migrating to a no-GIL (Global Interpreter Lock) Python build.

Onboarding
^^^^^^^^^^

The onboarding of a new developer is a technical challenge every team faces. Thanks to its core design, wox simplifies onboarding for any team working with Python by automating environment setup and dependency installation.

.. code-block::  toml

    [wox_configuration]

    [onboarding]
    envlist = ['.venv']
    deps = ['-r requirements.txt']
    commands = [
        # equivalent to git clone into an empty directory
        'git init',
        'git remote add origin <url/to/remote/repo/.git>',
        'git fetch origin',
        'git checkout -t origin/main'
        'pip install -e <path/to/package/>',
        'etc...'
    ]

Actually, any task you have in mind!
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

| A wox task can perform any operation that benefits from an isolated Python environment: running linters, formatters, tests, documentation tools, custom scripts, or any shell command.
| It can even invoke entry points from non-Python tooling — such as Java, C, JavaScript, or any other executable available on the system.
| In other words, a wox task automates the exact commands you would have executed yourself in your terminal. This makes it a flexible tool suitable for anything from simple utilities to complex multi-step development workflows.


The only limitation to wox's possibility are your imagination.

.. seealso::

    If you are unsure wox may fit your needs, check the :doc:`edge wox practices </edge_wox/index>`.
