/
Contribute to the vss-cli

Contribute to the vss-cli

Owned by JM Lopez
Last updated: Feb 13, 2025
2 min read

First time setup

  1. Download and install the Latest version of git.

  2. 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'

  1. Fork the vss-cli repository by clicking the Fork button.

  2. Clone your fork locally:

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

  1. 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

  1. 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

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

  2. Follow PEP8.

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

  1. Push your commits to GitLab and create a merge request.

git push origin issue-999

  1. Celebrate 🎉

Build docs

  1. Install requirements:

pip install .[dev]

  1. Build the html and man pages with distutils:

python setup.py build_sphinx

  1. 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.

Related content

University of Toronto - Since 1827