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.

Metadata

Release files for pyvss 2026.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyvss 2026.4.0
File	Size	Uploaded	Provenance
pyvss-2026.4.0.tar.gz	379.5 kB	Apr 12, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for pyvss 2026.4.0
File	Interpreter	ABI	Platform	Reset
pyvss-2026.4.0-py3-none-any.whl 55.0 kB Apr 12, 2026 Without provenance	Python 3	none	any	Details

Total release size: 434.5 kB

Release files / pyvss-2026.4.0.tar.gz

Download URL	pyvss-2026.4.0.tar.gz
Size	379.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`cf7dc63f6ef562820594e0358306ee24890cce19b2ff6c3382cb7db95097fdb7`
BLAKE2b-256 checksum How to use checksums	`e91a5cd6edf959aefbc1f441289fd96b440ed618e1dd2a9a6d8b6e98e5bc73f8`
Upload date	Apr 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.4`

Release files / pyvss-2026.4.0-py3-none-any.whl

Download URL	pyvss-2026.4.0-py3-none-any.whl
Size	55.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`ede460b3d97152e087e056b256d26fdd88debf000df07d7bee326eb68b30de35`
BLAKE2b-256 checksum How to use checksums	`b98ddac9b0f51ee1759b1125da588dfcf79a7e1b634078de2b3aa4923cefb7be`
Upload date	Apr 12, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.4`

Security for pyvss 2026.4.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.