pyvss 2026.4.0

ITS Private Cloud Python Client

ITS Private Cloud Python Client pyvss

Documentation

Package documentation is available at docs.

Requirements

• Python 3.7.5 or higher (as specified by python_requires='>=3.7.5' in setup.py)

Installation

Install PyVSS using pip:

pip install pyvss

To interact with vskey-stor, install pyvss with the storage extras:

pip install pyvss[stor]

To upgrade to the latest version:

pip install --upgrade pyvss

Platform-Specific Notes

macOS / Linux: If pip is not available, install Python 3.7.5+ from python.org or your package manager, then install pip:

curl -O https://bootstrap.pypa.io/get-pip.py
python3 get-pip.py --user

Windows: Download Python 3.7.5+ from Python Releases for Windows and ensure pip is included during installation.

Installing from Source

You can also install directly from the source tarball:

pip install https://gitlab-ee.eis.utoronto.ca/vss/py-vss/-/archive/master/py-vss-master.zip

Or clone and install locally:

git clone https://gitlab-ee.eis.utoronto.ca/vss/py-vss.git
cd py-vss
pip install .

Docker

For containerized usage, see the Docker documentation.

Quick start:

docker run -it -e VSS_API_TOKEN=your_token uofteis/pyvss

Usage

Create an instance of VssManager with your ITS Private Cloud API access token:

from pyvss.manager import VssManager

vss = VssManager(tk='your_api_token')

Basic Operations

# Get current user info
user = vss.whoami()

# List virtual machines
vms = vss.get_vms()

# List folders
folders = vss.get_folders()

# List networks
networks = vss.get_networks()

# List domains
domains = vss.get_domains()

Virtual Machine Management

# Get VM details
vm = vss.get_vm(uuid='5012abcb-a9f3-e112-c1ea-de2fa9dab90a')

# Power operations
vss.power_on_vm(uuid='<uuid>')
vss.power_off_vm(uuid='<uuid>')
vss.power_cycle_vm(uuid='<uuid>')
vss.reboot_guest_vm(uuid='<uuid>')
vss.shutdown_guest_vm(uuid='<uuid>')

# Create a single VM
request = vss.create_vm(
    os='ubuntu64Guest',
    built='os_install',
    description='Testing python wrapper',
    folder='group-v6736',
    bill_dept='EIS',
    disks=[100, 100]
)
uuid = vss.wait_for_request(request['_links']['request'], 'vm_uuid', 'Processed')

# Create multiple VMs
requests = vss.create_vms(
    count=3,
    name='python',
    os='ubuntu64Guest',
    bill_dept='EIS',
    description='Testing multiple deployment from python wrapper',
    folder='group-v6736',
    built='os_install'
)
uuids = [vss.wait_for_request(r['_links']['request'], 'vm_uuid', 'Processed') for r in requests]

# Power on multiple VMs
for uuid in uuids:
    vss.power_on_vm(uuid)

Snapshot Management

# Create a snapshot
request = vss.create_vm_snapshot(
    uuid='5012abcb-a9f3-e112-c1ea-de2fa9dab90a',
    desc='Snapshot description',
    date_time='2024-08-04 15:30',
    valid=1
)
snap_id = vss.wait_for_request(request['_links']['request'], 'snap_id', 'Processed')

# Revert to snapshot
request = vss.revert_vm_snapshot(uuid, snap_id)

# List snapshots
snapshots = vss.get_vm_snapshots(uuid='<uuid>')

# Delete a snapshot
vss.delete_vm_snapshot(uuid='<uuid>', snapshot=snap_id)

Request Tracking

from pyvss.enums import RequestStatus

# Get all requests
requests = vss.get_requests()

# Get request status
request = vss.get_request(request_id=123)

# Wait for a request to complete
result = vss.wait_for_request(
    request['_links']['request'],
    attribute='status',
    required_status='Processed'
)

Error Handling

from pyvss.manager import VssManager
from pyvss.exceptions import VssError

vss = VssManager(tk='your_api_token')

try:
    vm = vss.get_vm(uuid='invalid-uuid')
except VssError as e:
    print(f"API Error: {e}")

Authentication via Environment Variables

Instead of passing a token directly, you can set environment variables for authentication:

export VSS_API_USER='username'
export VSS_API_USER_PASS='password'

Then generate a token:

from pyvss.manager import VssManager

vss = VssManager()
vss.get_token()

Common Environment Variables

Variable	Description
VSS_API_TOKEN	API access token for authentication
VSS_API_USER	Username for token generation
VSS_API_USER_PASS	Password for token generation
VSS_API_USER_OTP	One-time password for TOTP
VSS_API_TIMEOUT	Request timeout in seconds (default: 60)
VSS_API_DEBUG	Enable debug mode

Getting Help

We use GitLab issues for tracking bugs, enhancements, and feature requests. If you may have found a bug, please open a new issue.

Versioning

This project uses Calendar Versioning (e.g., 2025.2.1). Versions are available in the tags section or PyPI.

Contributing

Refer to the Contributing Guide for details on our code of conduct and the process of submitting code to the repository.