Independent maintenance fork of ryanbdclark/pyowletapi,
retaining upstream history and the MIT license. The development branch
is maintenance/local-candidate. Prereleases are experimental, not production-ready
or endorsed by Owlet. The companion Home Assistant integration
uses this library. The package/import name remains pyowletapi; upstream's PyPI
package is separate and is not controlled by this fork.
Maintenance adds serialized authentication, persistent rotating-token snapshots, bounded HTTP retries/timeouts, redacted failures, caller-owned session support, and handling of missing or invalid measurements. V3 timestamps use timezone-aware ISO 8601 UTC. See CHANGELOG.md and CONTRIBUTORS.md for contribution sources and interface changes.
Requires Python >=3.11 and aiohttp >=3.9,<4. The 40 synthetic API regressions have passed on Python 3.12.3 and 3.14.6 with aiohttp 3.14.3. The companion integration has passed tests with HA Core 2026.9.3 / Python 3.14.6. Other Python versions, including the minimum, are not independently verified. No live HAOS or hardware testing is claimed. Cloud token rotation, rate limits and hardware variants need further validation. There is no global rate limiter, camera API or automatic alarm acknowledgment. Do not rely on this experimental software as a primary monitor.
Use this fork's versioned release wheel and SHA256 checksum.
A plain pip install pyowletapi installs upstream's distribution. The integration
pins the maintained wheel's HTTPS URL and hash in its manifest. Release assets
are never silently replaced; local builds may differ from an existing release
when documentation changes.
To build and test this checkout with uv:
uv venv .venv-target --python 3.14.6
uv pip install --python .venv-target/bin/python -r requirements-test-target.lock
uv pip install --python .venv-target/bin/python build==1.6.1 setuptools==84.0.0 wheel==0.48.0
SOURCE_DATE_EPOCH=1789862400 .venv-target/bin/python -m build --no-isolation --outdir dist
uv pip install --python .venv-target/bin/python --reinstall --no-deps dist/pyowletapi-2026.9.20rc2-py3-none-any.whl
.venv-target/bin/python -m pytest tests/test_maintenance.py -q
sha256sum dist/*.whl dist/*.tar.gzTests import the installed package; do not add src to PYTHONPATH. The pinned test
lock is for this exact Python target, not runtime dependencies. The inherited
tests/test.py uses live credentials and is excluded from regression discovery.
Do not run it as part of offline verification or commit login.json.
Import OwletAPI from pyowletapi.api and Sock from pyowletapi.sock. Supply
region world or europe, your account externally, and optionally an aiohttp
session. Calls are async. Persist api.tokens securely in a finally block after
account operations: a token can rotate before a later operation fails. Snapshots
are independent and non-consuming. Close an API-owned session using
await api.close(); borrowed sessions remain caller-owned.
Requests have a 20-second total and 10-second connect timeout. Safe reads and idempotent APP_ACTIVE assignments have at most three attempts; other commands are not replayed on transient failure. Authentication rejection has one separate recovery attempt. Passwords can remain in memory; the library does not provide encrypted token storage. Never log credentials, token snapshots or raw responses. Inherited application constants are not personal account credentials. Permission from Owlet to redistribute the Ayla application credential has not been established.
Original author: Ryan Clark and upstream contributors. Upstream credits BastianPoe/owlet_api and mbevand/owlet_monitor for API inspiration. CONTRIBUTORS.md retains maintenance attribution. Use issues for bugs and SECURITY.md for sensitive reports.
GitHub Actions builds the wheel and sdist and runs the offline regression suite against the installed wheel on Python 3.14.6. Live-login tests are excluded.