.wox workspace
==============

Wox may create several virtual environments and log files. To avoid cluttering your project directory, wox sets up its own dedicated workspace inside the ``.wox`` directory.

Virtual environments
--------------------

Virtual environments created by wox are located at the root of ``.wox``, which is the only location where wox is able to detect, reuse, or manage virtual environments.

.. important::
    | Fortunately, the ``.wox`` directory is not reserved exclusively for wox. The workspace is intentionally designed so **you** can use it as well.
    | You may add anything relevant to your workflow, even manually create your own virtual environments using any method you prefer.

    .. seealso::
        :ref:`How to declare manually creates virtual environment in wox. <manually_created_venv>`

.. _wox_logging:

Logging of wox sessions
-----------------------

To keep a trace of what happens during a session, wox generates a log file stored at ``.wox/.logs/wox-session``.  
Each log includes contextual information, such as the task name and the virtual environment name, formatted at the beginning of the logs like so: ``task:venv``.

When no task is running yet, the wox session uses ``wox:host`` as contextual information.  
The ``host`` refers to the environment in which wox itself is running:

- a virtual environment, if wox was installed with ``pip``;
- the system interpreter, if wox was installed with ``pipx``;

.. warning::

   Wox manages its own logging internally. Because the Python ``logging`` module
   creates the log file as soon as the file handler is initialized, a
   ``.wox/.logs/wox-session`` file is created as soon as wox starts — even before
   wox has confirmed that the current directory is a valid wox workspace.

   This leads to a special edge case: if wox is run in a directory that is *not*
   configured for wox (no ``wox.toml`` and no ``[tool.wox]`` section in
   ``pyproject.toml``), wox will raise a configuration error *but the mere act
   of starting* will have already created an empty ``.wox`` directory.

   To avoid leaving behind these accidental ``.wox`` folders, wox includes an
   automatic cleanup mechanism that deletes ``.wox`` **when**:

   - the current directory does **not** contain any wox configuration  
     (neither ``wox.toml`` nor ``pyproject.toml`` with a ``[tool.wox]`` table), **and**
   - the ``.wox/.logs/wox-session`` file contains no logs.

   In normal usage, this cleanup is safe and prevents clutter.  
   However, if you manually remove your wox configuration files **before** wox has
   written anything to the session logs, wox may interpret the workspace as
   invalid and delete the ``.wox`` directory entirely.

   In short: this can only happen in very specific circumstances and never
   during regular wox usage, but it is important to be aware of it.

