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.
3 maintainers
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)
| File | Size | Uploaded | |
|---|---|---|---|
| pyvss-2026.4.0.tar.gz | 379.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pyvss-2026.4.0-py3-none-any.whl | 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 | |
|
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 | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.4
|
