Metadata-Version: 2.4
Name: pyvss
Version: 2026.4.0
Summary: ITS Private Cloud Python Client
Project-URL: Homepage, https://gitlab-ee.eis.utoronto.ca/vss/py-vss
Project-URL: Documentation, https://eis.utorotno.ca/~vss/py-vss/
Project-URL: Repository, https://gitlab-ee.eis.utoronto.ca/vss/py-vss
Project-URL: Bug Reports, https://gitlab-ee.eis.utoronto.ca/vss/py-vss/issues
Project-URL: PyPI, https://pypi.python.org/pypi/pyvss
Author-email: University of Toronto <vss-apps@eis.utoronto.ca>
Maintainer-email: vss-py@eis.utoronto.ca
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Requires-Dist: pyjwt>=2.12.1
Requires-Dist: requests>=2.32.5
Provides-Extra: dev
Requires-Dist: bump2version==1.0.1; extra == 'dev'
Requires-Dist: coverage==7.10.7; extra == 'dev'
Requires-Dist: flake8==7.3.0; extra == 'dev'
Requires-Dist: minio==7.2.20; extra == 'dev'
Requires-Dist: nose==1.3.7; extra == 'dev'
Requires-Dist: pytz==2026.1; extra == 'dev'
Requires-Dist: sphinx-rtd-theme==3.1.0; extra == 'dev'
Requires-Dist: sphinx==7.4.7; extra == 'dev'
Requires-Dist: sphinxcontrib-confluencebuilder==2.15.0; extra == 'dev'
Requires-Dist: sphinxcontrib-jquery==4.1; extra == 'dev'
Requires-Dist: wheel==0.46.3; extra == 'dev'
Provides-Extra: stor
Requires-Dist: minio==7.2.20; extra == 'stor'
Provides-Extra: test
Requires-Dist: coverage==7.10.7; extra == 'test'
Requires-Dist: flake8==7.3.0; extra == 'test'
Requires-Dist: minio==7.2.20; extra == 'test'
Requires-Dist: nose==1.3.7; extra == 'test'
Requires-Dist: pytz==2026.1; extra == 'test'
Requires-Dist: wheel==0.46.3; extra == 'test'
Description-Content-Type: text/markdown

# ITS Private Cloud Python Client ``pyvss``

[![CI][build-img]](https://gitlab-ee.eis.utoronto.ca/vss/py-vss/commits/master)
[![PyPI][pypi-img]](https://pypi.python.org/pypi/pyvss)
[![PyPI version][pyver-img]](https://pypi.python.org/pypi/pyvss)
[![Docker Image Pulls][docker-pulls-img]][docker-image]

## Documentation

Package documentation is available at [docs][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]:

```bash
pip install pyvss
```

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

```bash
pip install pyvss[stor]
```

To upgrade to the latest version:

```bash
pip install --upgrade pyvss
```

### Platform-Specific Notes

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

```bash
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][Python Releases for Windows] and ensure pip is included during installation.

### Installing from Source

You can also install directly from the source tarball:

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

Or clone and install locally:

```bash
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](docker/README.md).

Quick start:

```bash
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**:

```python
from pyvss.manager import VssManager

vss = VssManager(tk='your_api_token')
```

### Basic Operations

```python
# 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

```python
# 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

```python
# 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

```python
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

```python
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:

```bash
export VSS_API_USER='username'
export VSS_API_USER_PASS='password'
```

Then generate a token:

```python
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][open a new issue].

## Versioning

This project uses [Calendar Versioning](https://calver.org/) (e.g., 2025.2.1).
Versions are available in the [tags section](https://gitlab-ee.eis.utoronto.ca/vss/py-vss/tags) or
[PyPI](https://pypi.org/project/pyvss/#history).

## Contributing

Refer to the [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process of
submitting code to the repository.

[docs]: https://eis.utoronto.ca/~vss/pyvss/
[download the tarball]: https://pypi.python.org/pypi/pyvss
[Click]: http://click.pocoo.org/6/
[Python Downloads]: https://www.python.org/downloads/
[Python Releases for Windows]: https://www.python.org/downloads/windows/
[pip]: http://www.pip-installer.org/en/latest/
[open a new issue]: https://gitlab-ee.eis.utoronto.ca/vss/py-vss/issues/new
[Alpine Linux]: https://hub.docker.com/_/alpine/
[PyVSS]: https://pypi.python.org/pypi/pyvss
[build-img]: https://gitlab-ee.eis.utoronto.ca/vss/py-vss/badges/master/pipeline.svg
[coverage-img]: https://gitlab-ee.eis.utoronto.ca/vss/py-vss/badges/master/coverage.svg
[pypi-img]: https://img.shields.io/pypi/v/pyvss.svg
[pyver-img]: https://img.shields.io/pypi/pyversions/pyvss.svg
[docker-pulls-img]:  https://img.shields.io/docker/pulls/uofteis/pyvss.svg
[docker-image]: https://hub.docker.com/r/uofteis/pyvss/
