github
/
apprise
mirror of https://github.com/caronc/apprise
1
0
Fork 0
Code Issues Releases Wiki Activity

Updated Development_API (markdown)

master
lead2gold 2018-10-10 15:05:11 -04:00
parent bd461aac17
commit 7123d8fcd9
1 changed files with 55 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
Development_API.md

@ -45,12 +45,12 @@ apobj.notify(
``` ```
By default, all notifications are sent as type **NotifyType.INFO** using the _default_ theme. The following other types are included with this theme: 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 | Description | | Notification Type | Text Representation | Description |
| -------------------- | ----------- | | -------------------- | ------------------- | ----------- |
| **NotifyType.INFO** | [![Build Status](https://github.com/caronc/apprise/blob/master/apprise/assets/themes/default/apprise-info-72x72.png)](https://github.com/caronc/apprise/tree/master/apprise/assets/themes/default) | | **NotifyType.INFO** | _info_ | [![Build Status](https://github.com/caronc/apprise/blob/master/apprise/assets/themes/default/apprise-info-72x72.png)](https://github.com/caronc/apprise/tree/master/apprise/assets/themes/default) |
| **NotifyType.SUCCESS** | [![Build Status](https://github.com/caronc/apprise/blob/master/apprise/assets/themes/default/apprise-success-72x72.png)](https://github.com/caronc/apprise/tree/master/apprise/assets/themes/default) | | **NotifyType.SUCCESS** | _warning_ | [![Build Status](https://github.com/caronc/apprise/blob/master/apprise/assets/themes/default/apprise-success-72x72.png)](https://github.com/caronc/apprise/tree/master/apprise/assets/themes/default) |
| **NotifyType.WARNING** | [![Build Status](https://github.com/caronc/apprise/blob/master/apprise/assets/themes/default/apprise-warning-72x72.png)](https://github.com/caronc/apprise/tree/master/apprise/assets/themes/default) | | **NotifyType.WARNING** | _success_ | [![Build Status](https://github.com/caronc/apprise/blob/master/apprise/assets/themes/default/apprise-warning-72x72.png)](https://github.com/caronc/apprise/tree/master/apprise/assets/themes/default) |
| **NotifyType.FAILURE** | [![Build Status](https://github.com/caronc/apprise/blob/master/apprise/assets/themes/default/apprise-failure-72x72.png)](https://github.com/caronc/apprise/tree/master/apprise/assets/themes/default) | | **NotifyType.FAILURE** | _failure_ | [![Build Status](https://github.com/caronc/apprise/blob/master/apprise/assets/themes/default/apprise-failure-72x72.png)](https://github.com/caronc/apprise/tree/master/apprise/assets/themes/default) |
Should you want to send a notification using a different status, simply include it as part of your **notify()** call: Should you want to send a notification using a different status, simply include it as part of your **notify()** call:
```python ```python
@ -75,4 +75,52 @@ apobj.clear()
## The Apprise Asset Object ## The Apprise Asset Object
The apprise object allows you to customize your alarms by offering it different images, different sources and different themes. 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`<br/> `/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(` <br/>` dirname(__file__),`<br/> ` 'assets', `<br/> ` 'themes', '{THEME}', `<br/> ` 'apprise-{TYPE}-{XY}{EXTENSION}',`<br/> ` ))`<br/> | 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. <br/>**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:
```python
# 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.
```