pyvenstar
A small, stateless Python client for the Venstar ColorTouch T8900 Local (LAN) REST API. Built for managing a fleet of thermostats across multiple sites (e.g. from a central scheduler reaching devices over a site-to-site VPN), not as a general Venstar SDK.
Reference: developer.venstar.com (Local API v5+).
Why stateless?
Each VenstarClient call round-trips to the device rather than caching
setpoints/mode on the instance. That costs a little extra HTTP overhead
(negligible on a LAN/VPN, these devices are polled/commanded on the order
of minutes, not milliseconds) but means a process managing dozens of
thermostats can freely construct/discard clients per operation without
worrying about stale cached state from a previous call.
Usage
from pyvenstar import VenstarClient, ThermostatMode, FanMode
with VenstarClient("10.0.1.42", timeout=5.0) as client:
info = client.get_info()
print(info.name, info.mode, info.space_temp)
client.set_setpoints(heat_temp=70, cool_temp=76)
client.set_mode(ThermostatMode.AUTO)
client.set_fan(FanMode.AUTO)
for sensor in client.get_sensors():
print(sensor.name, sensor.temp, sensor.humidity)
Setpoint writes are validated locally (against the device's reported
min/max range and, in AUTO mode, its setpointdelta) before any
network call is made — bad values from a scheduler never reach the
hardware. Validation failures raise VenstarValidationError; device/API
problems raise VenstarAPIError; unreachable devices raise
VenstarConnectionError. All three derive from VenstarError.
Security — read this before deploying
The T8900 Local API is unauthenticated, plaintext HTTP by default.
This library optionally supports a PIN (pin=) or HTTP Digest auth
(user=/password=) if configured on the device, but neither is
encrypted in transit. Treat network isolation as the primary control,
not this library:
- Put thermostats on an isolated VLAN/SSID per site with no general LAN/WiFi access.
- Firewall rules so only the control host's VPN-routed IP can reach port 80 on these devices — nothing else in or out.
- Use DHCP reservations so device IPs stay fixed (this library takes a host/IP directly; it does not implement Venstar's SSDP discovery).
- Enable the device PIN or Digest auth as defense-in-depth, not a substitute for network isolation.
Development
python -m venv .venv
.\.venv\Scripts\python -m pip install -e ".[tests]"
.\.venv\Scripts\python -m pytest -q
.\.venv\Scripts\python -m ruff check src tests
.\.venv\Scripts\python -m mypy src
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pyvenstar-0.1.1.tar.gz.
File metadata
- Download URL: pyvenstar-0.1.1.tar.gz
- Upload date:
- Size: 12.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1032d2766d69e6043a5c2f6923521979a84605e5d296ebf1e80e17e0ba393240
|
|
| MD5 |
55a59b79d1c9af001b122d63133b9625
|
|
| BLAKE2b-256 |
6cf424fc52a1df0df873331b434a26aed814b50467e387396e9e4c9e2c7fd151
|
Provenance
The following attestation bundles were made for pyvenstar-0.1.1.tar.gz:
Publisher:
release.yml on sslivins/pyvenstar
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pyvenstar-0.1.1.tar.gz -
Subject digest:
1032d2766d69e6043a5c2f6923521979a84605e5d296ebf1e80e17e0ba393240 - Sigstore transparency entry: 2578659274
- Sigstore integration time:
-
Permalink:
sslivins/pyvenstar@41fcec860100ec038bea342a3c0a995166441b32 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/sslivins
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@41fcec860100ec038bea342a3c0a995166441b32 -
Trigger Event:
push
-
Statement type:
File details
Details for the file pyvenstar-0.1.1-py3-none-any.whl.
File metadata
- Download URL: pyvenstar-0.1.1-py3-none-any.whl
- Upload date:
- Size: 10.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
7b30664beb5d45a272a27bc1ac7418baea8f36e4fe90a1998e78c35b497c3dc4
|
|
| MD5 |
03fb6c4a1b595a916c71ad2f5b0f19d6
|
|
| BLAKE2b-256 |
14df0c22d1ca86e5421cd04393f09c19fc49c3273e49244adf47a5aa7d4f99f9
|
Provenance
The following attestation bundles were made for pyvenstar-0.1.1-py3-none-any.whl:
Publisher:
release.yml on sslivins/pyvenstar
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pyvenstar-0.1.1-py3-none-any.whl -
Subject digest:
7b30664beb5d45a272a27bc1ac7418baea8f36e4fe90a1998e78c35b497c3dc4 - Sigstore transparency entry: 2578659303
- Sigstore integration time:
-
Permalink:
sslivins/pyvenstar@41fcec860100ec038bea342a3c0a995166441b32 -
Branch / Tag:
refs/heads/main - Owner: https://github.com/sslivins
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@41fcec860100ec038bea342a3c0a995166441b32 -
Trigger Event:
push
-
Statement type:
