Skip to main content

aiosecspy

Async Python client for the SecuritySpy web API (v5 and v6).

Supports ++systemInfo, the long-lived ++eventStream, arm/disarm, schedules, PTZ, snapshots, and recording download.

Used by the hass-securityspy Home Assistant integration.

Install

pip install aiosecspy

Requires Python 3.12+ and aiohttp.

Quick start

import asyncio

from aiosecspy import SecSpyClient


async def main() -> None:
    async with SecSpyClient("192.168.1.10", 8000, "user", "pass") as client:
        info = await client.refresh()
        print(info.name, info.version, len(client.cameras))

        for camera in client.cameras.values():
            print(camera.number, camera.name, camera.armed_motion)

        jpeg = await client.get_image(3, width=1280)
        print(len(jpeg), "bytes of JPEG")


asyncio.run(main())

async with creates and owns an aiohttp.ClientSession. Pass session= if you already have one (Home Assistant does); the client will then leave it open when it closes.

Events

++eventStream is a long-lived HTTP response of CR-delimited lines. EventStream reads it in a background task, reconnects with exponential backoff and jitter, and re-reads ++systemInfo when the server reports a configuration change.

from aiosecspy import Event, EventType, SecSpyClient


def on_event(event: Event) -> None:  # sync or async callbacks both work
    if event.event_type is EventType.MOTION:
        print(event.when, "motion on camera", event.camera_number)


async def watch() -> None:
    async with SecSpyClient("192.168.1.10", 8000, "user", "pass") as client:
        unsubscribe = client.events.add_listener(on_event)
        client.events.start()
        try:
            await asyncio.sleep(3600)
        finally:
            unsubscribe()
            await client.events.stop()

Event.when is timezone-aware, using the server's UTC offset from ++systemInfo.

While the stream is running it also keeps the Camera objects current: motion_active, event_object, the classification scores, last_motion_time, trigger_reasons, arm modes, and connected all update the moment the matching event arrives, before any listener runs. Reading client.cameras is therefore always live state — no listener required.

Listeners run on a dispatcher task decoupled from the stream reads, so a slow callback delays other callbacks but never the state updates. If a callback stalls long enough to fill the backlog, the oldest queued events are dropped (and a warning logged) rather than stalling the socket.

Alongside the wire event types, the stream emits a few of its own so you can drive UI state without polling:

Event type Meaning
CONNECTED The stream attached successfully.
DISCONNECTED The stream dropped (including a clean server-side close); a reconnect is scheduled.
AUTHFAIL Credentials were rejected. The watcher stops instead of retrying, so this is the signal to start a reauth flow.
REFRESH / REFRESHFAIL Result of the automatic ++systemInfo reload after CONFIGCHANGE.

A listener that raises is logged and skipped; it never takes down the stream.

API surface

Area Methods
Lifecycle open(), close(), refresh(), camera(number), cameras, info
Arming toggle_motion(n, arm=...), toggle_actions(n, arm=...), toggle_continuous(n, arm=...), trigger_motion()
Schedules set_schedule(), set_schedule_override(), set_schedule_preset()
PTZ ptz_left/right/up/down(), diagonals, ptz_zoom/home/stop(), ptz_preset(1-8), ptz_save_preset(1-8), ptz_command()
Video get_image(), image_url(), mjpeg_url(), hls_url(), rtsp_url()
Recordings list_motion_files(), download_file(), download_latest_motion_recording()

refresh() replaces the Camera objects but carries over the runtime state the event stream maintains (motion, classification scores, trigger reasons), so a refresh does not blank out live state.

list_motion_files() returns RecordingFile(title=..., href=...) records; pass the href to download_file().

Errors

Everything derives from SecSpyError:

Exception Raised when
AuthenticationError HTTP 401/403 — bad username or password.
UnsupportedError The server does not implement the endpoint (HTTP 404 on a command).
RequestError Transport failure, timeout, or an HTTP/body error.
UntrustedHostError A server-supplied link pointed off the configured server.
ResponseTooLargeError The response exceeded the size ceiling.
InvalidResponseError The body could not be parsed or carried a DTD.

The last three are subclasses of RequestError, so catching RequestError is enough for a simple "cannot talk to the server" path.

Version differences

++ssControlContinuous is missing from many builds. toggle_continuous() falls back to the schedule API when the server answers 404, matching the "Armed 24/7" / "Disarmed 24/7" schedule by name (v5 calls the latter "Unarmed 24/7"). Real failures are not swallowed.

Trigger reason bit 512 means Animal on v5 and HomeKit on v6; the parser uses the server's major version to decide.

Security

Read SECURITY.md before logging anything this library produces. The short version: the auth query parameter is equivalent to the password, so image_url(), mjpeg_url(), hls_url() and rtsp_url() all return secrets.

Development

pip install -e ".[dev]"
pytest -q --cov
ruff check . && ruff format --check .
mypy aiosecspy

Releasing to PyPI

Publishing uses Trusted Publishing (no API token).

  1. Bump __version__ in aiosecspy/__init__.py; the packaging metadata reads it from there.
  2. Commit, merge to main, and create a GitHub Release / tag (for example v0.1.0).
  3. publish.yml checks the tag against the package version, builds the sdist/wheel, and uploads to PyPI with attestations via the pypi GitHub Environment.

Metadata

Release files for aiosecspy 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiosecspy 0.2.1
File Size Uploaded Provenance Actions
aiosecspy-0.2.1.tar.gz 38.6 kB With provenance Details for aiosecspy-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiosecspy 0.2.1
File Interpreter ABI Platform Actions
aiosecspy-0.2.1-py3-none-any.whl Python 3 none any Details for aiosecspy-0.2.1-py3-none-any.whl

Total release size: 66.4 kB

Release files / aiosecspy-0.2.1.tar.gz

Download URL aiosecspy-0.2.1.tar.gz
Size 38.6 kB
Tags Source
SHA-256 checksum
How to use checksums
34d62b1e93c62ed48fbc30bad028863568119c323901b246b074aa3444de6c70
BLAKE2b-256 checksum
How to use checksums
983780a9eba821b25a8e5d4438cfd0003cb07a777b4d51452d3348ca8c019bae
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Aug 4, 2026.

Transparency log

Release files / aiosecspy-0.2.1-py3-none-any.whl

Download URL aiosecspy-0.2.1-py3-none-any.whl
Size 27.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2f5284f1fac4dd61a96edb81aca50b417d59841abfebebfe3eaae04268bee87e
BLAKE2b-256 checksum
How to use checksums
1ae4780a922139754f9e2c09c51318ce439591e683313d1a36e3a3c4353d92f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Aug 4, 2026.

Transparency log

Security for aiosecspy 0.2.1

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.

Select from 2 files

Attestation for aiosecspy-0.2.1.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 Aug 4, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page