Metadata-Version: 2.1
Name: vien
Version: 4.0.0
Summary: Command-line tool for managing Python virtual environments
Home-page: https://github.com/rtmigo/vien_py
Author: Artëm IG
Author-email: ortemeo@gmail.com
License: BSD-3-Clause
Description: #  [vien](https://github.com/rtmigo/vien_py#readme)
        
        **VIEN** is a command-line tool for
        managing [Python Virtual Environments](https://docs.python.org/3/library/venv.html)
        .
        
        It provides one-line shortcuts for:
        
        - creating and deleting environments
        - running commands inside environments
        - switching between environments in bash shell
        
        -----
        
        Switching between projects should be simple. Creating environments for the
        projects should be simple too.
        
        Ideally it's a short command that I would type even half asleep.
        
        Something like
        
        ``` bash
        $ vien create 
        $ vien shell
        ```
        
        Not like
        
        ``` bash
        $ python3 -m venv ./where/to/put/this/.venv
        $ source /i/lost/that/.venv/bin/activate
        ```
        
        <details>
          <summary>Ready-made solutions did not help.</summary><br/>
        
        - [pipenv](https://pipenv.pypa.io/) kind of solved the problem, but brought new
          challenges unrelated to virtual environments
        - [virtualenvwrapper](https://virtualenvwrapper.readthedocs.io/) name is easier
          to copy-paste than to type. And its commands are too
        
        </details>
        
        So there is the `vien`. A tool for a half asleep developer.
        
        # Install
        
        <details>
          <summary>Get a working Python ≥3.7, pip3 and venv.</summary><br/>
        
        @ Ubuntu
        
        ``` bash
        $ sudo apt install -y python3 python3-pip python3-venv
        ```
        
        @ macOS
        
        ``` bash
        $ brew install python3
        ```
        
        Check it works
        
        ``` bash
        $ python3 --version             # python shows its version
        $ python3 -m venv --help        # venv shows help message
        $ pip3 install --upgrade pip    # pip upgrades itself
        ```
        
        ----
        </details>
        
        Then:
        
        ``` bash
        $ pip3 install vien
        ```
        
        Make sure it installed:
        
        ``` bash
        $ vien      # shows help
        ```
        
        Upgrade it later:
        
        ``` bash
        $ pip3 install vien --upgrade
        ```
        
        # Use
        
        ## Create a virtual environment
        
        ``` bash
        $ cd /path/to/myProject
        $ vien create 
        ```
        
        By default `vien` will try to use `python3` as the interpreter for the virtual
        environment.
        
        <details>
          <summary>If you have 
        more than one Python version, provide one more argument.</summary><br/>
        Point to the proper interpreter the way you execute it.
        
        If you execute scripts like that
        
        ``` bash
        $ python3.8 /path/to/script.py
        ```
        
        Create virtual environment like that:
        
        ``` bash
        $ vien create python3.8
        ```
        
        Or provide full path to the interpreter:
        
        ``` bash
        $ vien create /usr/local/opt/python@3.8/bin/python3
        ```
        
        </details>
        
        ## Dive into interactive bash
        
        ```bash	
        $ cd /path/to/myProject
        $ vien shell
        
        (myProject)$ _
        ```
        
        Now you are inside the virtual environment.
        
        ```bash	
        (myProject)$ which python3             # now we are using separate copy of Python
        (myProject)$ echo $PATH                # everything is slightly different
        
        (myProject)$ pip3 install requests     # installs packages into virtual environment
        (myProject)$ python3 use_requests.py   # runs inside the virtual environment
        ```
        
        Get out of the virtual environment:
        
        ```bash
        (myProject)$ exit
        
        $ _
        ```
        
        Now you're back.
        
        ## Run a script inside the virtual environment
        
        It is `vien run <any bash command>`
        
        ```bash 		
        $ cd /path/to/myProject
        $ vien run python3 use_requests.py arg1 arg2  # runs in virtual environment
        $ vien run pip3 install requests              # installs packages into virtual environment
        ```
        
        <details>
          <summary>is an equivalent to</summary><br/>
        
        ```bash 		
        $ cd /path/to/myProject
        
        $ source /path/to/the/venv/bin/activate
        $ python3 use_requests.py arg1 arg2
        $ /path/to/the/venv/bin/deactivate
        
        $ source /path/to/the/venv/bin/activate
        $ pip3 install requests
        $ /path/to/the/venv/bin/deactivate
        ```
        
        </details>
        
        # Where are those virtual environments
        
        `vien` offers a simple rule of where to keep the environments.
        
        |project dir|virtual environment dir|
        |-----|----|
        |`/abc/thisProject`|`$HOME/.vien/thisProject_venv`|
        |`/abc/otherProject`|`$HOME/.vien/otherProject_venv`|
        |`/moved/to/otherProject`|`$HOME/.vien/otherProject_venv`|
        
        So only the local name of the project directory matters. And all the virtual
        environments are in `$HOME/.vien`.
        
        If you're not happy with the default, you can set the environment
        variable `VIENDIR`:
        
        ``` bash
        $ export VIENDIR="/x/y/z"
        ```
        
        So for the project `aaa` the virtual environment will be located
        in `/x/y/z/aaa_venv`.
        
        The `_venv` suffix tells the utility that this directory can be safely removed.
        
        # Other commands
        
        ### Delete virtual environment
        
        ``` bash
        $ cd /path/to/myProject
        $ vien delete 
        ```
        
        ### Delete old and create new virtual environment
        
        Useful, when you want to start from scratch.
        
        ``` bash
        $ cd /path/to/myProject
        $ vien recreate 
        ```
        
        Or upgrade it from an old Python to a new one:
        
        ``` bash
        $ cd /path/to/myProject
        $ vien recreate /usr/local/opt/python@3.10/bin/python3
        ```
        
        # Shell prompt
        
        By default the `vien shell` adds a prefix to
        the [`$PS1`](https://wiki.archlinux.org/index.php/Bash/Prompt_customization)
        bash prompt.
        
        ``` bash
        user@host$ cd /abc/myProject
        user@host$ vien shell
        
        (myProject)user@host$ _
        ```
        
        So you can see, which virtual environment you're using.
        
        If you customized your `PS1`, it may not work as expected.
        
        ``` bash
        personalized:prompt> cd /abc/myProject
        personalized:prompt> vien shell
        
        (myProject)user@host$ _
        ```
        
        It can be fixed by providing `PS1` variable to `vien` like that:
        
        ``` bash
        personalized:prompt> cd /abc/myProject
        personalized:prompt> PS1=$PS1 vien shell
        
        (myProject)personalized:prompt> _
        ```
        
        To avoid doing this each time, `export` your `PS1` to make it available for
        subprocesses.
        
        # Shebang
        
        Insert the shebang line to the top of the file you want to run. The value of the
        shebang depends on the location of the file relative to the project directory.
        
        File                            | Shebang line
        --------------------------------|--------------------------------
        `myProject/runme.py`            | `#!/usr/bin/env vien call -p .`
        `myProject/pkg/runme.py`        | `#!/usr/bin/env vien call -p ..`
        `myProject/pkg/subpkg/runme.py` | `#!/usr/bin/env vien call -p ../..`
        
        After inserting the shebang, make the file executable:
        
        ``` bash
        $ chmod +x runme.py  
        ```
        
        Now you can run the `runme.py` directly from command line.
        
        With this shebang, the file can be run from any working directory. Thanks to
        the `-p` parameter the project directory is not the working directory, but a
        directory relative to `runme.py`.
        
        ``` bash
        # runs the runme.py in virtual environment for myProject
        
        $ cd anywhere/somewhere
        $ /abc/myProject/pkg/main.py   
        ```
        
        Of course, the virtual environment must be initialized if it is not already done
        
        ``` bash
        $ cd /abc/myProject
        $ vien create
        $ vien shell
        $ pip install ...
        ```
Keywords: virtual-environment,venv,virtualenv,python,command-line,shell,terminal,bash,run,create,delete,execute
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Environment :: Console
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Build Tools
Classifier: Operating System :: POSIX
Requires-Python: >=3.7
Description-Content-Type: text/markdown
