justpush 0.2.0

JustPush — Python SDK

The official Python SDK for JustPush. Send push notifications to your iOS and Android devices from any Python script, server or Home Assistant integration.

• A sync client that uses only the standard library, and an async client on aiohttp
• Typed models for buttons, button groups, images, sounds and acknowledgements
• Checks the message before sending it, so you get a clear error instead of a rejected request
• Rate-limit information on every send

Installation

pip install justpush

Python 3.10 or newer.

Send a message

from justpush import JustPush

client = JustPush("YOUR_API_TOKEN")
result = client.send("The nightly backup finished", title="Backups")

print(result.key)                    # use it with get_message()
print(result.rate_limit.remaining)   # messages left this month

Get your API token from the JustPush app.

Everything a message can do

from justpush import Acknowledgement, Button, ButtonGroup, Image, JustPush, Priority, Sound

client = JustPush("YOUR_API_TOKEN")

client.send(
    "Water detected under the washing machine",
    title="💧 Leak",
    topic="Home",                        # topic name; created if it doesn't exist yet
    priority=Priority.HIGHEST,           # or 2, or "highest"
    sound=Sound.SIREN,                   # or "siren"
    buttons=[Button("Open camera", "https://example.com/cam")],
    images=[Image.from_file("snapshot.jpg", caption="Kitchen")],
    expiry=3600,                         # hide the message after an hour
    acknowledge=Acknowledgement(
        retry=True, interval=60, max_retries=10,
        callback_url="https://example.com/acknowledged",
        callback_params={"sensor": "kitchen"},
    ),
)

Check a message

details = client.get_message(result.key)
print(details.is_acknowledged, details.processed_at)

Check a token

client.verify_token()   # raises JustPushAuthenticationError if the token is invalid

This sends nothing and uses no quota, so it's safe for setup screens.

Async

import asyncio
from justpush import AsyncJustPush

async def main():
    async with AsyncJustPush("YOUR_API_TOKEN") as client:
        await client.send("Someone rang the doorbell", title="🔔 Doorbell")

asyncio.run(main())

Pass session= to reuse your own aiohttp.ClientSession, for example async_get_clientsession(hass) in a Home Assistant integration. The client never closes a session it didn't create.

Topics

topic = client.create_topic("Servers", avatar_url="https://example.com/server.png")
client.update_topic(topic.uuid, title="Production servers")
client.get_topic(topic.uuid)
client.send("Disk almost full", topic_token=topic.api_token)

Errors

Every error is a JustPushError.

Development

python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
.venv/bin/ruff check . && .venv/bin/mypy

Changelog

See CHANGELOG.md.