notifiers 0.6.0

Advantages

• Spend your precious time on your own code base, instead of chasing down 3rd party provider APIs. That’s what we’re here for!

• With a minimal set of well known and stable dependencies (requests, jsonschema and click) you’re better off than installing 3rd party SDKs.

• A unified interface means that you already support any new providers that will be added, no more work needed!

• Thorough testing means protection against any breaking API changes. We make sure your code your notifications will always get delivered!

Basic Usage

>>> from notifiers import get_notifier
>>> p = get_notifier('pushover')
>>> p.required
['user', 'message', 'token']
>>> p.notify(user='foo', token='bar', message='test')
<NotificationResponse,provider=Pushover,status=Success>

Setup

Install with pip:

pip install notifiers

Usage

Get a notifier:

>>> import notifiers
>>> pushover = notifiers.get_notifier('pushover')
>>> pushover
<NotificationProvider:[Pushover]>

Or:

>>> from notifiers.providers.pushover import Pushover
>>> pushover = Pushover()

Send a notification:

>>> pushover.notify(token='TOKEN', title='Foo', message='Bar')

Get notifier metadata:

>>> pushover.metadata
{'base_url': 'https://api.pushover.net/1/messages.json', 'site_url': 'https://pushover.net/', 'provider_name': 'pushover'}

Required arguments:

>>> pushover.required
['user', 'message', 'token']

All arguments (in JSON schema format):

>>> pushover.arguments
{'user': {'oneOf': [{'type': 'array', 'items': {'type': 'string', 'title': 'the user/group key (not e-mail address) of your user (or you)'}, 'minItems': 1, 'uniqueItems': True}, {'type': 'string', 'title': 'the user/group key (not e-mail address) of your user (or you)'}]}, 'message': {'type': 'string', 'title': 'your message'}, 'title': {'type': 'string', 'title': "your message's title, otherwise your app's name is used"}, 'token': {'type': 'string', 'title': "your application's API token"}, 'device': {'oneOf': [{'type': 'array', 'items': {'type': 'string', 'title': "your user's device name to send the message directly to that device"}, 'minItems': 1, 'uniqueItems': True}, {'type': 'string', 'title': "your user's device name to send the message directly to that device"}]}, 'priority': {'oneOf': [{'type': 'number', 'minimum': -2, 'maximum': 2}, {'type': 'string'}], 'title': 'notification priority'}, 'url': {'type': 'string', 'format': 'uri', 'title': 'a supplementary URL to show with your message'}, 'url_title': {'type': 'string', 'title': 'a title for your supplementary URL, otherwise just the URL is shown'}, 'sound': {'type': 'string', 'title': "the name of one of the sounds supported by device clients to override the user's default sound choice"}, 'timestamp': {'type': 'integer', 'minimum': 0, 'title': "a Unix timestamp of your message's date and time to display to the user, rather than the time your message is received by our API"}, 'retry': {'type': 'integer', 'minimum': 30, 'title': 'how often (in seconds) the Pushover servers will send the same notification to the user. priority must be set to 2'}, 'expire': {'type': 'integer', 'maximum': 86400, 'title': 'how many seconds your notification will continue to be retried for. priority must be set to 2'}, 'callback': {'type': 'string', 'format': 'uri', 'title': 'a publicly-accessible URL that our servers will send a request to when the user has acknowledged your notification. priority must be set to 2'}, 'html': {'type': 'integer', 'minimum': 0, 'maximum': 1, 'title': 'enable HTML formatting'}}

View all available providers (continuously updated):

>>> notifiers.all_providers()
['pushover', 'simplepush', 'slack', 'email', 'gmail', 'pushbullet']

Some provider have default values set:

>>> e = notifiers.get_notifier('gmail')
>>> e.defaults
{'subject': "New email from 'notifiers'!", 'from': '<USER@LOCAL_HOST>', 'host': 'smtp.gmail.com', 'port': 587, 'tls': True, 'ssl': False, 'html': False}

Environment variables

You can set environment variable to replace any argument that the notifier can use. The default syntax to follow is NOTIFIERS_[PROVIDER_NAME]_[ARGUMENT_NAME]:

export NOTIFIERS_PUSHOVER_TOKEN=FOO
export NOTIFIERS_PUSHOVER_USER=BAR

Then you could just use:

>>> p.notify(message='message')

Note that you can also set MESSAGE in an environment variable. You can also change the default prefix of NOTIFIERS_ by pass the env_prefix argument on notify:

>>> p.notify(message='test', env_prefix='MY_OWN_PREFIX_')

Command Line Interface

Notifiers come with CLI support:

(notifiers_venv) ip-192-168-1-169:notifiers $ notifiers
Usage: notifiers [OPTIONS] COMMAND [ARGS]...

  Notifiers CLI operation

Options:
  --help  Show this message and exit.

Commands:
  arguments  Shows the name and schema of all the...
  defaults   Shows the provider's defaults.
  metadata   Shows the provider's metadata.
  notify     Send a notification to a passed provider.
  providers  Shows all available providers
  required   Shows the required attributes of a provider.

Because of the dynamic nature of using different provider options, those are passed in a keyword=value style to the command as so:

$ notifiers notify pushover token=foo user=bar message=test

Environment variables are used in the CLI as well. Explicitly passing keyword values takes precedence. You can also pipe into the command:

$ cat file.txt | notifiers notify pushover token=foo user=bar

You can set NOTIFIERS_DEFAULT_PROVIDER environment variable which will be used by the CLI. Combining that with the other required provider arguments can lead to very succinct commands:

$ cat file.txt | notifiers notify

Note that unlike the other environment variables, you cannot change the prefix of this one.

Provider specific CLI

Some providers have their own CLI commands:

$ notifiers telegram --help
Usage: core.py telegram [OPTIONS] COMMAND [ARGS]...

  Telegram specific commands

Options:
  --help  Show this message and exit.

Commands:
  updates  Get a list of active chat IDs for your bot.

Supported providers

• Pushover

• SimplePush

• Slack

• Gmail

• Email (SMTP)

• Telegram

• Gitter

• Pushbullet

• Join

• Hipchat

In the near future

• SendGrid, Graphite, Stride, Prowl, Teams, Twilio and many more…

• Docs!