First time setup

Download and install the Latest version of git.
Configure git with your username and email matching your GitLab account:

git config --global user.name 'your name'
git config --global user.email 'your email'

Fork the vss-cli repository by clicking the Fork button.
Clone your fork locally:

git clone git@gitlab-ee.eis.utoronto.ca:{username}/vss-cli.git
cd vss-cli

Add the main repository as a remote to update later:

git remote add vss git@gitlab-ee.eis.utoronto.ca:vss/vss-cli.git
git fetch vss

Create virtual environment:

python3 -m venv vss-cli
source vss-cli/bin/activate

Start Coding

1. Create a branch to identify the issue you would like to work on (e.g. issue-999):

cd vss-cli
git checkout -b issue-999

Using your favorite editor, make your changes, committing as you go.
Follow PEP8.

pip install .[test]
flake8 --ignore F401,E402, vss_cli

Push your commits to GitLab and create a merge request.

git push origin issue-999

Celebrate 🎉

Build docs

Install requirements:

pip install .[dev]

Build the html and man pages with distutils:

python setup.py build_sphinx

Or to the docs folder and run make to start the build:

cd docs
make html man

In any case, the resulting files are located in docs/_build.

Developing Plugins

Plugin developers need to register their sub-commands or sub-groups to either of the following entry-points in their setup.py that is loaded by the vss-cli core package:

vss_cli.contrib.plugins: scope at vss-cli plugins command group.
vss_cli.contrib.compute: scope at vss-cli compute command group.
vss_cli.contrib.compute.vm: scope at vss-cli compute vm command group.

For example, if someone wanted to make a plugin package called new_plugin which adds a sub-command at vss-cli compute report and another one at vss-cli compute vm report, they would create their custom python package with the vss-cli as a dependency, and add the following to their package’s setuptools entry-points in setup.py:

#!/usr/bin/env python


"""
Setup script for `new-plugin`
"""


from setuptools import setup


setup(
    name='new-plugin',
    version='0.1dev0',
    packages=['new_plugin'],
    install_requires=['vss-cli>=0.1.0']
    entry_points='''

    [vss_cli.contrib.compute]
    report=new_plugin.core:report

    [vss_cli.contrib.compute.vm]
    report=new_plugin.core:report
    '''
)

Now, the plugin package new_plugin contains __init__.py and core.py:

"""
Add custom report to `vss-cli`
"""

import click
import logging
from vss_cli.helper import format_output
from vss_cli.cli import pass_context

_LOGGING = logging.getLogger(__name__)


@click.command(
    'report'
)
@pass_context
def report(ctx):
    """+Custom report plugin"""
    _LOGGING.debug(f'Running report')
    vms = ctx.get_vms(summary=1)
    click.echo(
        format_output(
            ctx,
            vms,
            columns=[
               ('uuid',), ('name',),
               ('ip_address',)
            ],
        )
    )

After installing the plugin, the vss-cli will load the plugin in the defined scope:

vss-cli compute --help

Usage: vss-cli compute [OPTIONS] COMMAND [ARGS]...

  Compute related resources such as virtual machines, networks supported
  operating systems, logical folders, OVA/OVF images, floppy images, ISO
  images and more.

Options:
  --help  Show this message and exit.

Commands:
  domain     List compute domains.
  floppy     Manage floppy images.
  folder     Manage logical folders
  image      Manage personal and list public VM images.
  inventory  Manage inventory reports
  iso        Manage ISO images.
  net        List available virtual networks
  os         Supported OS.
  report     +Custom report plugin
  template   List virtual machine templates
  vm         Manage virtual machines


vss-cli compute vm report --help

Usage: vss-cli compute vm report [OPTIONS]

  +Custom report plugin

Options:
  --help  Show this message and exit.