Skip to content

Latest commit

 

History

History
285 lines (197 loc) · 9.85 KB

README.rst

File metadata and controls

285 lines (197 loc) · 9.85 KB
Raw
PyPI-Server Project generated with PyScaffold

python-pushover-open-client

Command line app and framework for receiving and processing Pushover push notifications in real time.

Features

  • Receive notifications real time via Pushover websocket server.
  • Execute python funcions via commands received by notification, passing arguments as *args.
  • Execute shell commands, passing arguments.
  • Execute python functions to all received notifications (eg.,. you can use Popen to send all notifications to notify-send.)
  • Can be run as a system service, enabling your scripts from boot time.
  • It is being developed with facilities to make it easy subclassing.

Installing

pip install python-pushover-open-client

Python minimum version 3.10 is needed. (because of the `|` union annotations.)

Setting Up

The script expects a file at the home directory named ~/.pushover-open-client-creds.json. The file should be a JSON file with account's email and password, this way:

file: ~/.pushover-open-client-creds.json

{
  "email": "[email protected]",
  "password": "M4HSUP3RBPASS"
}

Given the above, by logging and getting an auth secret, a new device will be created wielding it's device_id, and that file will be updated containing all these four values.

Using

Command line

Our command line pushover-open-client still needs more functions, but we already have one. His whole interface is here.

pushover-open-client json

This command outputs new received notifications and can be used to pipe for your own scripts to be processed.

Programatically

Here is an example script of how using decorators to use the lib. More examples will be added soon, as there are more decorators/functions to be used.

file: notify.py

#!/usr/bin/env python

from subprocess import Popen

from python_pushover_open_client import register_command
from python_pushover_open_client import register_parser
from python_pushover_open_client import PushoverOpenClientRealTime


# Let's use a decorator to registrate a command function; it will be executed
# when a message with `mycmd_rawdata` as the first word is received. All
# the arguments, *ie.*, all the words in the notification, including
# `mycmd_rawdata` will be passed to ``*args``:

@register_command
def mycmd_rawdata(*args, raw_data=None):
    print("RAW DATA IS:", raw_data)

# this decorator register a parser which is executed for each new
# notification received; here we have two examples:

@register_parser
def my_notify_send_parser(raw_data=None):
    args_str = "notify-send \"{message}\"".format(message=raw_data["message"])
    Popen(args=args_str, shell=True)


@register_parser
def my_print_parser(raw_data=None):
    print("MESSAGE RECEIVED:", raw_data)

# this instantiates the Pushover websocket class and runs it:
client = PushoverOpenClientRealTime()
client.run_forever()

You can save the script above to a file (eg. ~/notify.py), then make it executable and run, after you have installed the package and entered your Pushover credentials:

chmod +x notify.py
./notify.py

Then while it is running, try to send a notification to the device (or all the devices) via Pushover website or other notification sending app.

Full featured Pushover client using this lib

Send notification to desktop (if you use notify-send) and show the notification on the terminal executing it. Only lacks the Pushover App icon.

You can even create a systemd service to always receive the notifications on desktop automatically. (In this case, you can delete the terminal printing lines.)

file: python-client.py

#!/usr/bin/env python

from subprocess import Popen

from python_pushover_open_client import register_parser
from python_pushover_open_client import PushoverOpenClientRealTime


PERMANENT_NOTIFICATION = True  # should notifications stay until clicked?

# shows notifications on Desktop using `notify-send`

@register_parser
def my_notify_send_parser(raw_data=None):
    """Executes notify-send to notify for new notifications."""

    message = raw_data['message']
    title = raw_data['title'] if raw_data['title'] else '_'

    is_permanent = ["-t", "0"] if PERMANENT_NOTIFICATION else []

    args = ['notify-send', *is_permanent, title, message ]

    Popen(args=args)

# prints to the terminal

@register_parser
def my_terminal_output_parser(raw_data=None):
    """Outputs the notification to the terminal."""

    print(raw_data)

    message = raw_data['message']
    title = raw_data['title'] if raw_data['title'] else '_'

    print(f"{title}\n{message}", end="\n\n")

# this instantiates the Pushover websocket class and runs it:

client = PushoverOpenClientRealTime()
client.run_forever()

Command line tool

Let's use Python's click to make a fancy interface to this program?

A Little More Inner

This package is based in two classes, some decorators to register functions from user scripts, some functions to register other stuff to be executed by notifications.

The two classes are python_pushover_open_client.PushoverOpenClient and python_pushover_open_client.PushoverOpenClientRealTime. The first manages credentials, authentication, device registration, message downloading, message deletion etc, like specified by the Pushover Open Client API documentation, and is consumed by the second class. The second class connects to the Pushover's websocket server with the given credentials (secret and device_id) and keep the connection open, receiving messages and executing callbacks when and according to each server message is received.

By now, decorators and top level functions are used to register functions to be executed when certain commands are received by notification (@register_command, @register_command_parser, register_shell_command(), register_shell_command_alias()), or to register parsers which will be executed when every notification is received @register_parser.)

Contributing

Please open an issue if you want to contribute with code. Or use discussions.

The sources' package in reality contain only two files:

  • __init__.py - This contains the python_pushover_open_client library itself.
  • __main__.py - Will hold the command-line interface logic for the pushover-open-client command as it is developed.

Support

You can open a issue or a message in discussions for support in using/getting the code.

Is it ready already?

100%

Note

This project has been set up using PyScaffold 4.1.4. For details and usage information on PyScaffold see https://pyscaffold.org/.