Development_API

Development API

Apprise is very easy to use as a developer. The Apprise() object handles everything for you, meanwhile the AppriseAsset() Object allows you to stray away from some default configuration to personalize the users experience (and perhaps fit your application better):

• The Apprise Object
• The Apprise Asset Object

The Apprise Object

The Apprise() object is the heart and soul of this library. To instantiate an instance of the object, one might do the following:

# Import this library
import apprise

# create an Apprise instance and assign it to variable `apobj`
apobj = apprise.Apprise()

Use the add() function to append the notification URLs we want to provide notifications for.

# Add all of the notification services by their server url.
# A sample email notification
isokay = apobj.add('mailto://myemail:[email protected]')

# add() will return a True if the URL was successfully parsed and added into
# our notification pool.  Otherwise it returns False.

# A sample pushbullet notification
isokay = apobj.add('pbul://o.gn5kj6nfhv736I7jC3cj3QLRiyhgl98b')

We can retrieve a list of the active and loaded notification services by using python's built in len() function.

# len(apobj) returns the number of notifications loaded
# the below calls this and prints it to the screen:
print("There are %d notification services loaded" % len(apobj))

You can send a notification to all of the loaded notifications services by just providing it a title and a body like so:

# Then notify these services any time you desire. The below would
# notify all of the services loaded into our Apprise object.
apobj.notify(
    title='my notification title',
    body='what a great notification service!',
)

By default, all notifications are sent as type NotifyType.INFO using the default theme. The following other types are included with this theme:

Notification Type	Text Representation	Description
NotifyType.INFO	info
NotifyType.SUCCESS	warning
NotifyType.WARNING	success
NotifyType.FAILURE	failure

Should you want to send a notification using a different status, simply include it as part of your notify() call:

# Import our NotifyType
from apprise import NotifyType

# Then notify these services any time you desire. The below would
# notify all of the services loaded into our Apprise object as a WARNING.
apobj.notify(
    title='my notification title',
    body='what a great notification service!',
    notify_type=NotifyType.WARNING,
)

If you ever want to reset the object, you can use the clear() function.

# clears out all of the loaded notification services associated with our
# Apprise Object.
apobj.clear()

Developers who wish to be able to generate information based on this library dynamically can use the details() function:

# returns an object containing details about the plugin for dynamic integration.
apobj.details()

The output will look like:

{
    "version": "0.5.2",
    "asset": {
        "default_extension": ".png",
        "app_desc": "Apprise Notifications",
        "image_path_mask": "https://github.com/caronc/apprise/raw/master/apprise/assets/themes/{THEME}/apprise-{TYPE}-{XY}{EXTENSION}",
        "app_id": "Apprise",
        "theme": "default",
        "image_url_logo": "https://github.com/caronc/apprise/raw/master/apprise/assets/themes/{THEME}/apprise-logo.png",
        "image_url_mask": "https://github.com/caronc/apprise/raw/master/apprise/assets/themes/{THEME}/apprise-{TYPE}-{XY}{EXTENSION}"
    },
    "schemas": [
        {
            "service_name": "Boxcar",
            "setup_url": "https://github.com/caronc/apprise/wiki/Notify_boxcar",
            "service_url": "https://boxcar.io/",
            "protocols": null,
            "secure_protocols": [
                "boxcar"
            ]
        },
        {
            "service_name": "Discord",
            "setup_url": "https://github.com/caronc/apprise/wiki/Notify_discored",
            "service_url": "https://discordapp.com/",
            "protocols": null,
            "secure_protocols": [
                "discord"
            ]
        },
        {
            "service_name": "E-Mail",
            "setup_url": "https://github.com/caronc/apprise/wiki/Notify_email",
            "service_url": null,
            "protocols": [
                "mailto"
            ],
            "secure_protocols": [
                "mailtos"
            ]
        },

        "... etc, ..."

    ]
}

The idea behind the details() function is that it allows developers to pass details back through their program letting their users know what notifications are supported. Thus as this library deprecates and introduces new notification services, calling front end applications (built around the details() function) can automatically serve this information back to their user base.

The Apprise Asset Object

The apprise object allows you to customize your alarms by offering it different images, different sources and different themes. Different notification services support different ways of passing images into it (and some don't support images at all). Apprise offers a way of supporting both local and hosted images and looks after passing the correct one to the correct service (when requested).

Even when you just using the Apprise() object, behind the scenes a generic AppriseAsset() object is created which retrieves all of it's information from this path: https://github.com/caronc/apprise/tree/master/apprise/assets/themes/default (which is the default theme directory).

A default AppriseAsset() object might have the following defined in it:

Variable	Default	Type	Description
app_id	Apprise	String	A Short Identifier defining the name of the application.
app_desc	Apprise Notifications	String	A brief way of describing your notification system
app_url	https://github.com/caronc/apprise	String	The URL someone could go to to find more information about your application if they so desired.
image_url_mask	https://github.com/caronc/apprise/raw/master /apprise/assets/themes/{THEME}/apprise-{TYPE}-{XY}{EXTENSION}	String	A URL accessible from the internet that contains the images you want your notifications to reference. The URL should make use of available TEMPLATES MASKS that are encapsulated in {} brackets.
image_path_mask	abspath(join( dirname(__file__), 'assets', 'themes', '{THEME}', 'apprise-{TYPE}-{XY}{EXTENSION}', ))	String	A locally accessible path that contains the images you want your notifications to reference. The path should make use of available TEMPLATES MASKS that are encapsulated in {} brackets. Note: Don't let the python code above confuse you. It is used to dynamically figure out the path relative to where you installed apprise to so that it can point to the image files the product ships with.

The AppriseAsset() object also performs some dynamic templating of the specified image and URL paths. First I'll explain the template values, and then I'll explain how it works:

Template Value	Variable	Type	Default	Description
{THEME}	theme	String	default	The theme to reference.
{EXTENSION}	default_extension	String	.png	The image file extension
{TYPE}				The type of notification being preformed. For example, if the user calling the notify() function specifies a notify_type of NotifyType.WARNING, the string warning would be placed as the {TYPE}
{XY}				The image size to use which is in the format of AAxBB (as an example 72x72). Depending on the notification service being called; this value will vary. If you plan on defining your own images, you should facilitate the sizes: 32x32, 72x72, 128x128, and 256x256

Everytime the notify() function is called from the Apprise object, it uses the URL and/or local path and applies all of the templated masked values so that it can figure out what image to display. Here is an example how one might over-ride apprise to suit their own custom project needs:

# Import this library
import apprise

# Create our AppriseAsset and populate it with some of our new values:
asset = apprise.AppriseAsset(
   # The following would allow you to support:
   # C:\Path\To\My\Images\info-32x32.jpeg
   # C:\Path\To\My\Images\warning-72x72.jpeg
   # etc...
   image_path_mask="C:\Path\To\My\Images\{TYPE}-{XY}{EXTENSION}",
   default_extension=".jpeg"
)

# Change our name a bit:
asset.app_id = "My App"
asset.app_desc = "My App Announcement"
asset.app_url = "http://nuxref.com/"

# create an Apprise instance and assign it our asset we created:
apobj = apprise.Apprise(asset=asset)

# At this point you can use the Apprise() object knowing that all of the
# default configuration has been over-ridden.