Venv Plugin

Manages a python virtualenv

Requirements

We currently use pipenv to maintain the virtualenv, although support for other solutions like poetry are being discussed.

pip install pipenv

Additionally if you want to be able to sync your setup.py file from the Pipfile via the sync_setup setup operation you will need to install the pipenv-setup addon.

pip install pipenv-setup

Example

In the following example we want to set up a virtualenv for python3.6. For the sake of simplicity it will only install the latest version of the requests module into it.

Ctl/config.yaml

ctl:
  plugins:

    - name: venv36
      type: venv
      config:

        # this virtualenv should run on python 3.6
        # note that this needs to be a string and not a float
        python_version: "3.6"

        # you can specify a different location for your pipfile
        # pipfile: path/to/my/Pipfile


  permissions:
    - namespace: ctl
      permission: crud

By default it will be looking for a pipenv Pipfile in your ctl home

Ctl/Pipfile

Use a symlink

While it is possible for ctl to work with a Pipfile that is not at your project root having it at root seems to be the accepted standard at this point. We suggest you maintain the Pipfile at ./Pipfile and symlink it in $CTL_HOME/Pipfile

Alternatively you can also just setup your pipfile plugin config attribute accordingly.

[[source]]
name = "pypi"
url = "https://pypi.org/simple"
verify_ssl = true

[dev-packages]

[packages]
requests = "*"

[requires]
python_version = "3.6"

Run the command

The command will be exposed as an operation to the ctl cli by it's name and also provide three sub operations: build, sync and copy

Build / Sync

build is used to initially build the virtualenv sync will build the virtualenv if it does not exist and otherwise update that it with the latest requirements

ctl venv36 sync output/venv36

Copy

Copies an existing virtualenv to a new location

ctl venv36 copy output/venv36 output/venv36_copy

Usage

Plugin name

This usage documentation assumes that the plugin instance name is venv

usage: ctl venv [-h] [--pipfile PIPFILE] [--python-version PYTHON_VERSION]
                {build,sync,copy,sync_setup} ...

optional arguments:
  -h, --help            show this help message and exit
  --pipfile PIPFILE     path to Pipfile ({{ctx.home}}/Pipfile)
  --python-version PYTHON_VERSION
                        (3.6)

Operation:
  {build,sync,copy,sync_setup}
    build               build virtualenv
    sync                sync virtualenv using pipenv, will build venv first if
                        it does not exist
    copy                copy virtualenv
    sync_setup          sync setup.py from Pipfile

Build

usage: ctl venv build [-h] [output]

positional arguments:
  output      venv location

optional arguments:
  -h, --help  show this help message and exit

Sync

usage: ctl venv sync [-h] [output]

positional arguments:
  output      venv location

optional arguments:
  -h, --help  show this help message and exit

Sync Setup

usage: ctl venv sync_setup [-h] [--freeze] [--dry] [setup_file]

positional arguments:
  setup_file  location of the setup.py file you want to sync

optional arguments:
  -h, --help  show this help message and exit
  --freeze    Do a frozen sync with pinned versions from Pipfile.lock
  --dry       Do a dry run

Copy

usage: ctl venv copy [-h] [source] [output]

positional arguments:
  source      venv source location
  output      venv output location

optional arguments:
  -h, --help  show this help message and exit