pyisyox.helpers.session module

HTTP session and SSL context helpers for IoX 6+ controllers.

eisy/Polisy on current IoX firmware:

  • Reject TLS 1.0 and 1.1 — confirmed against a current-firmware eisy with openssl s_client (TLS 1.0/1.1 → “no protocols available”; TLS 1.2 and 1.3 negotiate).

  • Ship a self-signed certificate. verify_ssl=False is the default so out-of-the-box deployments connect; consumers who deploy their own CA can opt into verification.

This module exposes two pure helpers that take discrete parameters (no connection-info object) so they’re trivial to call from the pyisyox.controller.Controller and from tests:

  • build_sslcontext() — returns an ssl.SSLContext (or None when the URL is HTTP-only) honouring tls_version and verify_ssl.

  • can_https() — preflight check that the requested TLS version is supported on this Python build.

Original ISY-994 hardware (TLS 1.1 only) is out of scope for this library — that path stays on PyISY 3.x. tls_version=1.1 here raises rather than silently downgrading.

exception TLSVersionError[source]

Bases: ValueError

Raised when the requested TLS version isn’t usable on this build.

build_sslcontext(*, use_https, tls_version=None, verify_ssl=False)[source]

Build an ssl.SSLContext for the connection, or None when the controller is reached over HTTP.

Parameters:

  • use_https (bool) – False short-circuits to None.

  • tls_version (float | None) – None (default) auto-negotiates the highest mutually-supported version. 1.2 or 1.3 pin a specific minimum + maximum. Anything else raises.

  • verify_ssl (bool) – False (default) accepts the controller’s self-signed certificate. True enables strict verification — requires consumers to deploy their own CA.

Raises:

TLSVersionError – When tls_version isn’t None / 1.2 / 1.3.

Return type:

SSLContext | None

can_https(tls_ver)[source]

Pre-flight check that HTTPS is usable with the requested TLS version.

Returns False and logs an error when the version is one we don’t support on IoX 6+ (anything other than None, 1.2, or 1.3). Returns True otherwise.

Parameters:

tls_ver (float | None)

Return type:

bool