Venver
######

Automatically activate, and deactivate virutal environments when entering or
leaving directories.

Installation
############

bash
====

#. Install the venver package. This can be in a virtual environment.

    .. code-block:: shell

        mkdir -p "${HOME}/.local/bin/venver"
        cd "${HOME}/.local/bin/venver"
        python -m venv .venv
        pip --python ./.venv/bin/python install venver

#. Add this to the bottom of your ``.bashrc``.

    .. code-block:: shell

        venver() {
           eval "$("${HOME}/.local/bin/venver/.venv/bin/venver")"
        }

        PROMPT_COMMAND="venver;${PROMPT_COMMAND}"

Usage
#####

Let's assume you have a python project with a virtual environment like this:

.. code-block::

    ~/
    ├─ myapp/
    │  ├─ .venv/
    │  │   ...
    │  ├─ src/
    │  │   ...
    │  ├─ .gitignore
    │  ├─ pyproject.toml
    │  ├─ README.rst

Add a ``.venver`` file to the project root.

.. code-block:: shell

    cd ~/myapp
    echo './.venv' > .venver

.. code-block::

    ~/
    ├─ myapp/
    │  ├─ .venv/
    │  │   ...
    │  ├─ src/
    │  │   ...
    │  ├─ .gitignore
    │  ├─ .venver
    │  ├─ pyproject.toml
    │  ├─ README.rst

Navigating anywhere inside the ``myapp`` directory will result in the
environment at ``myapp/.venv`` being activated. And navigating outside of
``myapp`` will deactivate the environment.

.. code-block:: console

    ~ $ cd myapp
    ~/myapp (.venv) $ cd src
    ~/myapp/src (.venv) $ cd ~
    ~ $ cd myapp/src
    ~/myapp/src (.venv) $

If you manually deactivate the environment, it won't be automatically activated
again until you navigate outside of ``myapp``, then reenter it.

.. code-block:: console

    ~ $ cd myapp
    ~/myapp (.venv) $ deactivate
    ~/myapp $ cd src
    ~/myapp/src $ cd ~
    ~ $ cd myapp
    ~/myapp (.venv) $

You may specify an environment that isn't in the project directory. This is
useful if you have environments you want to reuse. The activation, and
deactivation will still be relative to the ``.venver`` directory, and not the
environment directory.

.. code-block::

    ~/
    ├─ venvs/
    │  ├─ web-venv/
    │  │   ...
    │  ├─ console-venv/
    │  │   ...

.. code-block:: shell

    cd ~/myapp
    echo '~/venvs/web-venv' > .venver

.. code-block:: console

    ~ $ cd myapp
    ~/myapp (web-venv) $ cd src
    ~/myapp/src (web-venv) $ cd ~
    ~ $ cd myapp/src
    ~/myapp/src (web-venv) $
