python-senz-wifi-module
Python library for interacting with the SenzWifi (Pentair Thermal WiFi) API to control thermostats.
Features
- Async-first — built on
httpxfor efficient async operations - Authentication & session management — automatic retry on session expiry
- Thermostat control — list, read, and update thermostat settings
- Convenience methods — set temperature, turn off, boost mode
- Real-time notifications — long-polling for thermostat state changes
- CLI tool — built-in command-line interface for quick operations
- Fully typed — type hints throughout with
py.typedmarker
Installation
pip install senzwifi
Or install from source:
git clone https://github.com/sockless-coding/python-senz-wifi-module.git
cd python-senz-wifi-module
pip install -e .
Quick Start
Using the Library
import asyncio
from senzwifi import AsyncSenzWifi, RegulationMode
async def main():
# Create client with credentials
async with AsyncSenzWifi("your@email.com", "your-password") as client:
# Authenticate
await client.authenticate()
# List all thermostats
response = await client.get_thermostats()
for group in response.groups:
print(f"Group: {group.group_name}")
for t in group.thermostats:
print(f" {t.room}: {t.temperature_celsius:.1f}°C (mode: {RegulationMode(t.regulation_mode).name})")
# Set a thermostat to 21°C manually
await client.set_manual_temperature("SN123456789", 21.0)
# Turn off a thermostat
await client.turn_off("SN123456789")
# Start boost mode (3 hours by default)
await client.start_boost("SN123456789")
asyncio.run(main())
Using the CLI
# List all thermostats
senzwifi --username "your@email.com" --password "your-password" list
# Get a specific thermostat
senzwifi --username "your@email.com" --password "your-password" get SN123456789
# Set temperature to 21°C
senzwifi --username "your@email.com" --password "your-password" set SN123456789 21.0
# Turn off a thermostat
senzwifi --username "your@email.com" --password "your-password" off SN123456789
# Start boost mode
senzwifi --username "your@email.com" --password "your-password" boost SN123456789
API Reference
AsyncSenzWifi
The main client class. Supports use as an async context manager.
async with AsyncSenzWifi(email, password) as client:
await client.authenticate()
# ... use the client
Constructor
| Parameter | Type | Default | Description |
|---|---|---|---|
email |
str |
— | Account email address |
password |
str |
— | Account password |
max_retries |
int |
3 |
Maximum retry attempts for failed requests |
timeout |
float |
30.0 |
Request timeout in seconds |
Methods
authenticate() -> AuthResponse
Authenticate and obtain a session ID.
auth = await client.authenticate()
if auth.is_success:
print(f"Logged in as {auth.email}")
get_thermostats() -> ThermostatsResponse
Fetch all thermostats grouped by their group.
response = await client.get_thermostats()
for group in response.groups:
print(f"{group.group_name}: {len(group.thermostats)} devices")
# Get all thermostats flat
all_thermostats = response.get_all_thermostats()
# Find a specific thermostat
t = response.get_thermostat("SN123456789")
get_thermostat(serial_number: str) -> Thermostat
Get a specific thermostat by serial number.
t = await client.get_thermostat("SN123456789")
print(f"{t.room}: {t.temperature_celsius:.1f}°C")
set_manual_temperature(serial_number: str, temperature_celsius: float) -> UpdateThermostatResponse
Set a thermostat to a specific temperature in manual mode.
result = await client.set_manual_temperature("SN123456789", 21.5)
print(f"Success: {result.success}")
turn_off(serial_number: str) -> UpdateThermostatResponse
Turn off a thermostat.
result = await client.turn_off("SN123456789")
start_boost(serial_number: str, end_time: datetime | None = None) -> UpdateThermostatResponse
Start boost (comfort) mode. Defaults to 3 hours from now if no end time is specified.
from datetime import datetime, timedelta, timezone
# Boost for 3 hours (default)
await client.start_boost("SN123456789")
# Boost until a specific time
end = datetime.now(timezone.utc) + timedelta(hours=1)
await client.start_boost("SN123456789", end_time=end)
update_thermostat(serial_number: str, thermostat: Thermostat) -> UpdateThermostatResponse
Update a thermostat with custom settings.
t = await client.get_thermostat("SN123456789")
t.regulation_mode = RegulationMode.SCHEDULE
t.manual_temperature = 2000 # 20.0°C in raw format
result = await client.update_thermostat("SN123456789", t)
wait_for_notification(timeout: float = 300.0) -> Notification | None
Long-poll for thermostat state change notifications.
notification = await client.wait_for_notification(timeout=60.0)
if notification:
print(f"Change detected: {notification.action} on {notification.thermostat.room}")
Models
RegulationMode
RegulationMode.SCHEDULE # 1 — Use the configured schedule
RegulationMode.BOOST # 2 — Boost / comfort temp mode
RegulationMode.MANUAL # 3 — Constant temp mode
RegulationMode.OFF # 5 — Off
Thermostat
Key properties (all temperatures available in both raw and Celsius):
| Property | Type | Description |
|---|---|---|
serial_number |
str |
Device serial number |
room |
str |
Room name |
group_name |
str |
Group name |
temperature_celsius |
float |
Current temperature |
regulation_mode |
int |
Current regulation mode |
online |
bool |
Whether the device is online |
heating |
bool |
Whether heating is active |
manual_temperature_celsius |
float |
Manual setpoint temperature |
comfort_temperature_celsius |
float |
Comfort/boost temperature |
min_temp_celsius |
float |
Minimum temperature |
max_temp_celsius |
float |
Maximum temperature |
schedules |
list[Schedule] |
Available schedules |
Temperature Conversion Utilities
from senzwifi import temp_to_celsius, celsius_to_temp
# Raw API value (1/100 °C) → Celsius
temp_to_celsius(2100) # 21.0
# Celsius → raw API value
celsius_to_temp(21.0) # 2100
Exceptions
| Exception | Description |
|---|---|
SenzWifiError |
Base exception for all errors |
AuthenticationError |
Authentication failed |
SessionExpiredError |
Session has expired |
DeviceNotFoundError |
Thermostat not found |
APIError |
API request failed |
Example: Monitoring Thermostats
See examples/monitor.py for a complete example that monitors thermostat changes in real time.
import asyncio
from senzwifi import AsyncSenzWifi, RegulationMode
async def monitor():
async with AsyncSenzWifi("your@email.com", "your-password") as client:
await client.authenticate()
# Show initial state
response = await client.get_thermostats()
for t in response.get_all_thermostats():
mode = RegulationMode(t.regulation_mode).name
print(f"[INIT] {t.room}: {t.temperature_celsius:.1f}°C ({mode})")
# Watch for changes
while True:
notification = await client.wait_for_notification()
if notification:
t = notification.thermostat
mode = RegulationMode(t.regulation_mode).name
print(f"[CHANGE] {t.room}: {t.temperature_celsius:.1f}°C ({mode})")
asyncio.run(monitor())
Development
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run linter
ruff check .
# Run type checker
mypy senzwifi
License
MIT
Metadata
Release files for senzwifi 2026.6.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| senzwifi-2026.6.2.tar.gz | 24.6 kB | With provenance | Details for senzwifi-2026.6.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| senzwifi-2026.6.2-py3-none-any.whl | Python 3 | none | any | Details for senzwifi-2026.6.2-py3-none-any.whl |
Total release size: 41.9 kB
Release files / senzwifi-2026.6.2.tar.gz
| Download URL | senzwifi-2026.6.2.tar.gz |
|---|---|
| Size | 24.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
219007308c7ade41567c3bd742d4ac20e4f822ab821a9aaa239f880608006715
|
|
BLAKE2b-256 checksum How to use checksums |
d9182c2e7807fc131d7212f4ae2f091779819eb1a564d26ec6be6c1a35948804
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 21, 2026.
Transparency logRelease files / senzwifi-2026.6.2-py3-none-any.whl
| Download URL | senzwifi-2026.6.2-py3-none-any.whl |
|---|---|
| Size | 17.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b6f768a79301605e472e66d4be38107093921bb9b2fe4962aeac47d1b0ff0338
|
|
BLAKE2b-256 checksum How to use checksums |
c58772b433a09dfead98d7087fabe56b252ead09fb705e7d3d46701befb24161
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 21, 2026.
Transparency logSecurity for senzwifi 2026.6.2
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for senzwifi-2026.6.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 21, 2026.
Transparency logA 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.