Metadata-Version: 1.2
Name: vrun
Version: 0.4
Summary: Adds Python's bin/Scripts directory to PATH before executing a command. Primarily used with Python virtual environments.
Home-page: https://github.com/bertjwregeer/vrun
Author: Bert JW Regeer
Author-email: bertjw@regeer.org
License: ISC
Description: vrun
        ====
        
        Adds Python's bin/Scripts directory to ``PATH`` before executing a command.
        Primarily used with Python virtual environments.
        
        Overview
        --------
        
        A small Python helper tool that will modify the ``PATH`` in the environment
        before executing the executable provided as the first argument. This is useful
        when programs expect certain binaries to be available in ``PATH`` so they can
        execute them using ``os.popen()`` and friends or even for shell scripts that
        are executing Python tools that one would prefer to not globally install.
        
        Scripts may detect that vrun has been used by looking for the environment
        variable ``VRUN_ACTIVATED`` which is set to ``1`` when run. It is not
        recommended that script writers do this.
        
        Use
        ---
        
        On macOS/FreeBSD/Linux/Unix:
        
        .. code::
        
            $ python3 -mvenv ./env/
            $ ./env/bin/pip install vrun
            $ ./env/bin/vrun /bin/bash -c 'echo $PATH'
        
        
        On Windows:
        
        .. code::
        
            C:\> python3.exe -mvenv env
            C:\> env\Scripts\pip.exe install vrun
            C:\> env\Scripts\vrun.exe python -c "import os; print(os.environ['PATH'])"
        
        
        If for example there is a script that executes ``pip`` without explicitly
        providing a PATH that includes a virtual environment the system installed
        ``pip`` may accidentally be invoked instead. With vrun the virtual environment
        will come first in the search path and thus ``pip`` will be safely executed
        within the context of the virtual environment.
        
        Such as a shell script:
        
        .. code::
        
            $ ./env/bin/vrun ./myscript.sh
        
        Or executing a Windows batch script:
        
        .. code::
        
            C:\> env\Scripts\vrun.exe script.bat
        
        
        Command aliases
        ---------------
        
        vrun allows you to define command aliases in a configuration file, either
        ``vrun.cfg``, ``vrun.ini`` or ``setup.cfg``.
        
        These configuration files must contain at least a ``vrun`` section, then using standard ini format you may specify key/value pairs:
        
        .. code::
            
            [vrun]
            python.version = python --version
            shell = /bin/bash
            echo = /bin/bash -c 'echo ${@}' _ {posargs} echo off the bare walls
        
        Now you may run these commands using:
        
        .. code::
        
            vrun python.version
        
        Which will return something similar to:
        
        .. code::
        
            Python 3.6.2
        
        Then you can do positional argument interpolation:
        
        .. code::
        
            vrun echo the soft voices
        
        will output:
        
        .. code::
        
            the soft voices echo off the bare walls
        
        Interpolation
        ~~~~~~~~~~~~~
        
        So long as the keyword ``{posargs}`` is stand-alone, and surrounded by spaces
        (and not inside of a quoted segment) ``vrun`` will replace it with any
        positonal arguments provided on the command line. If not positional arguments
        are provided, it will remove the ``{posargs}`` placeholder and remove it as an
        argument.
        
        If there is no ``{posargs}`` provided in the command alias, all extra arguments
        provided after the initial command will be passed as positional arguments.
        
        Using the ``shell`` example from above, you may do:
        
        .. code::
        
            vrun shell -c 'echo $PATH'
        
        which will execute:
        
        .. code::
        
            /bin/bash -c 'echo $PATH'
        
        Within the virtual environment as expected. This can be useful to allow you to
        predefine certain longer commands, but still allow the user on the fly on the
        command line to add additional parameters as necessary.
        
        vrun or vexec
        -------------
        
        vrun installs itself as both ``vrun`` and ``vexec``. The later may be typed
        with the left hand only and is slightly faster to roll off the keyboard!
        
        License
        -------
        
        Please see the `LICENSE
        <https://github.com/bertjwregeer/vrun/blob/master/LICENSE>`_ file in the source
        code repository 
        
        
        0.4 (2017-09-27)
        ================
        
        - You may now create command aliases by creating a new configuration file named
          ``vrun.cfg`` or adding a section to an existing ``setup.cfg`` named ``[vrun]``.
        
          .. code::
        
              [vrun]
              python.version = python --version
              shell = /bin/bash
              echo = /bin/bash -c 'echo ${@}' _ {posargs} echo off the bare walls
        
          Which may then be used like so:
        
          .. code::
        
              vrun python.version
              vrun echo the soft voices
              vrun shell -c 'echo $PATH'
        
        - New tests have been added, and coverage is now 100%. All new features from
          now on will have to meet the same coverage requirements to verify there are
          no breaking changes.
        
        0.3 (2017-06-13)
        ================
        
        - Adds Windows support, so now you can use:
        
          .. code::
        
              Script\vrun.exe python -c "import os; print(os.environ['PATH'])"
        
          To run Windows binaries with their ``%PATH%`` modified.
        
          vrun will also automatically add the `.exe` when passing the name of a script
          that exists in the ``Scripts`` folder.
        
          So the following are the same:
        
          .. code::
        
              Script\vrun.exe python
        
          and:
        
          .. code::
        
              Script\vrun.exe python.exe
        
        0.2 (2017-06-08)
        ================
        
        - Also export the environment variable ``VIRTUAL_ENV`` pointing to the virtual
          environment.
        
        0.1 (2017-06-08)
        ================
        
        - Initial release and implementation of the vrun functionality
        
Keywords: virtualenv vexec vrun venv bin Scripts
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
