<commit_before>
.. index:: Venv
.. _venv:   

Venv
======


Features
----------

* Configures :ref:`Python` ``site`` for a given :ref:`virtualenv`
* Configures :ref:`Python` ``sys.path`` with :ref:`IPython` extension paths
* Configures :ref:`IPython` command aliases (``%alias``, or just ``alias``)
* Generates :ref:`Bash` environments from :ref:`virtualenv` paths
* Configures :ref:`Bash` variables starting with ``$_`` (``$_APP``, ``$_WRD``)
* Run commands within a :ref:`virtualenv` (``venv dotfiles -x bash``)

There are two parts to "``venv``":

* `dotfiles.venv.ipython_config.py`_
* `10-bashrc.venv.sh`_  
  
`dotfiles.venv.ipython_config.py`_ generates shell and IPython configuration
with aliases that, for shells, are expanded to functions
if they contain a ``%l``
(which IPython ``%alias`` replaces with any passed arguments).

`dotfiles.venv.ipython_config.py`_ is symlinked to
``etc/ipython/ipython_config.py``.

`10-bashrc.venv.sh`_ configures a number of useful variables and
functions for use with :ref:`virtualenvwrapper`.


.. _10-bashrc.venv.sh: https://github.com/westurner/dotfiles/blob/master/etc/bash/10-bashrc.venv.sh
.. _dotfiles.venv.ipython_config.py: https://github.com/westurner/dotfiles/blob/master/src/dotfiles/venv/ipython/ipython_config.py


Quickstart
-----------

.. code-block:: bash


    # print shell configuration for a (hypothetical) dotfiles virtualenv
    venv dotfiles --bash

    # print shell configuration for the current ${VIRTUAL_ENV} [and ${_WRD}]
    venv -E --bash

    # run a command within a virtualenv
    venv dotfiles -x bash

    # workon a virtualenvwrapper virtualenv (we) (source <(venv -E --bash))
    we dotfiles

    # workon ${WORKON_HOME}/dotfiles/src/otherproject (echo $_APP $_WRD)
    we dotfiles otherproject



Python API
~~~~~~~~~~~~
A Venv object builds a :py:mod:`dotfiles.venv.ipython_config.Env`
with ``$VIRTUAL_ENV``-relative paths
in a common filesystem hierarchy and an ordered dictionary of
command aliases, which can be serialized to
a bash script (``venv --bash``) or to JSON (``venv --print``)
by a :py:mod:`dotfiles.venv.ipython_config:Venv`.

.. code-block:: python

    import Venv, json
    venv = Venv(from_environ=True)
    venv.print()
    venv.bash_env()

    venv.configure_sys()
    venv.configure_ipython()

    assert venv.virtualenv  == venv.env['VIRTUAL_ENV']
    assert venv.appname     == venv.env['_APP']

    print(venv.env['_WRD'])     # working directory
    #> ~/.virtualenvs/dotfiles

    print(venv.aliases['_edit'])
    #> gvim --servername dotfiles --remote-tab

    print(venv.env['_EDIT_'])
    #> gvim --servername dotfiles --remote-tab


Command Aliases
-----------------
.. note:: The aliases generated by `dotfiles.venv.ipython_config.py`
   should also be defined in `10-bashrc.venv.sh`_;
   but the variables they reference are set by
   `dotfiles.venv.ipython_config.py`_.


Example Venv Configuration
----------------------------

Shell Configuration
~~~~~~~~~~~~~~~~~~~~
``venv dotfiles --bash``:

.. command-output:: python ../src/dotfiles/venv/ipython_config.py dotfiles --bash \
   | sed "s,${HOME},/home/user,g"
   :shell:


JSON Configuration
~~~~~~~~~~~~~~~~~~~
``venv dotfiles --print``:

.. command-output:: python ../src/dotfiles/venv/ipython_config.py dotfiles --print \
   | sed "s,${HOME},/home/user,g"
   :shell:

<commit_msg>DOC: tools.rst<commit_after>
.. index:: Venv
.. _venv:   

Venv
======


Features
----------

* Configures :ref:`Python` ``site`` for a given :ref:`virtualenv`
* Configures :ref:`Python` ``sys.path`` with :ref:`IPython` extension paths
* Configures :ref:`IPython` command aliases (``%alias``, or just ``alias``)
* Generates :ref:`Bash` environments from :ref:`virtualenv` paths
* Configures :ref:`Bash` variables starting with ``$_`` (``$_APP``, ``$_WRD``)
* Run commands within a :ref:`virtualenv` (``venv dotfiles -x bash``)

There are two parts to "``venv``":

* `dotfiles.venv.ipython_config.py`_
* `10-bashrc.venv.sh`_  
  
`dotfiles.venv.ipython_config.py`_ generates shell and IPython configuration
with aliases that, for shells, are expanded to functions
if they contain a ``%l``
(which IPython ``%alias`` replaces with any passed arguments).

`dotfiles.venv.ipython_config.py`_ is symlinked to
``etc/ipython/ipython_config.py``.

`10-bashrc.venv.sh`_ configures a number of useful variables and
functions for use with :ref:`virtualenvwrapper`.


.. _10-bashrc.venv.sh: https://github.com/westurner/dotfiles/blob/master/etc/bash/10-bashrc.venv.sh
.. _dotfiles.venv.ipython_config.py: https://github.com/westurner/dotfiles/blob/master/src/dotfiles/venv/ipython/ipython_config.py


Quickstart
-----------

.. code-block:: bash


    # print shell configuration for a (hypothetical) dotfiles virtualenv
    venv dotfiles --bash

    # print shell configuration for the current ${VIRTUAL_ENV} [and ${_WRD}]
    venv -E --bash

    # run a command within a virtualenv
    venv dotfiles -x bash

    # workon a virtualenvwrapper virtualenv (we) (source <(venv -E --bash))
    we dotfiles

    # workon ${WORKON_HOME}/dotfiles/src/otherproject (echo $_APP $_WRD)
    we dotfiles otherproject



Python API
~~~~~~~~~~~~
A Venv object builds a :py:mod:`dotfiles.venv.ipython_config.Env`
with ``$VIRTUAL_ENV``-relative paths
in a common filesystem hierarchy and an ordered dictionary of
command aliases, which can be serialized to
a bash script (``venv --bash``) or to JSON (``venv --print``)
by a :py:mod:`dotfiles.venv.ipython_config:Venv`.

.. code-block:: python

    import Venv, json
    venv = Venv(from_environ=True)
    venv.print()
    venv.bash_env()

    venv.configure_sys()
    venv.configure_ipython()

    assert venv.virtualenv  == venv.env['VIRTUAL_ENV']
    assert venv.appname     == venv.env['_APP']

    print(venv.env['_WRD'])     # working directory
    #> ~/.virtualenvs/dotfiles

    print(venv.aliases['_edit'])
    #> gvim --servername dotfiles --remote-tab

    print(venv.env['_EDIT_'])
    #> gvim --servername dotfiles --remote-tab


Command Aliases
-----------------
.. note:: The aliases generated by `dotfiles.venv.ipython_config.py`
   should also be defined in `10-bashrc.venv.sh`_;
   but the variables they reference are set by
   `dotfiles.venv.ipython_config.py`_.


Example Venv Configuration
----------------------------

Shell Configuration
~~~~~~~~~~~~~~~~~~~~
``venv dotfiles --bash``:

.. command-output:: python ../src/dotfiles/venv/ipython_config.py dotfiles --bash \
   | sed "s,${HOME},~,g"
   :shell:


JSON Configuration
~~~~~~~~~~~~~~~~~~~
``venv dotfiles --print``:

.. command-output:: python ../src/dotfiles/venv/ipython_config.py dotfiles --print \
   | sed "s,${HOME},~,g"
   :shell:


{'fraction_non_alphanumeric': 0.1731084912699597, 'fraction_numerical': 0.0029846291598268917, 'mean_word_length': 3.5935572309801236, 'pattern_counts': {'":': 2, '<': 5, '<?xml version=': 0, '>': 9, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5724119', 'n_tokens_mistral': 2389, 'n_tokens_neox': 2265, 'n_words': 575}