mirror of https://github.com/caronc/apprise
Updated Development_API (markdown)
Chris Caron
parent
1431031a40
commit
c9c7cc2698
|
|
@ -310,56 +310,149 @@ The idea behind the **details()** function is that it allows developers to pass
|
|||
More detailed information about this object can be found [[here|Development_Apprise_Details]].
|
||||
|
||||
## The AppriseAsset 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're 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).
|
||||
`AppriseAsset` is the central configuration object that controls the look, feel, and behaviour of your notifications. Even when you simply instantiate `Apprise()`, it creates a default `AppriseAsset()` under the hood (using the “default” theme in `apprise/assets/themes/default`). By customizing `AppriseAsset`, you can:
|
||||
|
||||
A default **AppriseAsset()** object might have the following defined in it:
|
||||
- Override the application identifier, description, and URL
|
||||
- Point to your own local or hosted images (logos and type-specific icons)
|
||||
- Enable or disable asynchronous delivery, logging filters, and escape-sequence interpretation
|
||||
- Configure persistent storage (caching) for repeated notifications
|
||||
- Add your own plugin directories or files
|
||||
|
||||
| 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:
|
||||
### Constructor Signature
|
||||
|
||||
| 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**|
|
||||
|
||||
Every time 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
|
||||
from typing import Union, List, Optional
|
||||
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"
|
||||
# Theme & app identity
|
||||
theme: str = "default",
|
||||
app_id: str = "Apprise",
|
||||
app_desc: str = "Apprise Notifications",
|
||||
app_url: str = "https://github.com/caronc/apprise",
|
||||
|
||||
# Image settings
|
||||
default_extension: str = ".png",
|
||||
image_path_mask: str = "/…/apprise/assets/themes/{THEME}/apprise-{TYPE}-{XY}{EXTENSION}",
|
||||
image_url_mask: str = (
|
||||
"https://raw.githubusercontent.com/caronc/apprise/master"
|
||||
"/apprise/assets/themes/{THEME}/apprise-{TYPE}-{XY}{EXTENSION}"
|
||||
),
|
||||
image_url_logo: Optional[str] = None,
|
||||
|
||||
# Plugin discovery
|
||||
plugin_paths: Union[str, List[str]] = None,
|
||||
|
||||
# Delivery behaviour
|
||||
async_mode: bool = True,
|
||||
interpret_escapes: bool = False,
|
||||
encoding: str = "utf-8",
|
||||
secure_logging: bool = True,
|
||||
|
||||
# Persistent storage (caching)
|
||||
storage_mode: Optional[str] = None, # "auto" | "flush"
|
||||
storage_path: Optional[str] = None,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Key Attributes
|
||||
|
||||
| Name | Type | Default | Description |
|
||||
|-----------------------|------------------------|----------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------|
|
||||
| **theme** | `str` | `"default"` | Which theme directory to use (maps into `{THEME}`). |
|
||||
| **app_id** | `str` | `"Apprise"` | A short identifier/name for your application. |
|
||||
| **app_desc** | `str` | `"Apprise Notifications"` | A brief description of your notification system. |
|
||||
| **app_url** | `str` | `"https://github.com/caronc/apprise"` | A URL where users can learn more about your app. |
|
||||
| **default_extension** | `str` | `".png"` | Default image file extension (e.g. `".png"`, `".jpeg"`). |
|
||||
| **image_path_mask** | `str` | Local path mask using `{THEME}`, `{TYPE}`, `{XY}`, `{EXTENSION}`. | Where on disk to find your images/icons. |
|
||||
| **image_url_mask** | `str` | Remote URL mask using `{THEME}`, `{TYPE}`, `{XY}`, `{EXTENSION}`. | Where to fetch hosted images/icons. |
|
||||
| **image_url_logo** | `Optional[str]` | `None` | A single logo URL for your app (uses `{THEME}` if provided). |
|
||||
| **html_notify_map** | `Dict[NotifyType,str]` | Maps each `NotifyType` (INFO/SUCCESS/WARNING/FAILURE) → a hex colour code.| Used by some services that support colourised HTML. An example of this can be found below |
|
||||
| **async_mode** | `bool` | `True` | Send notifications concurrently (if the service/client supports it). |
|
||||
| **interpret_escapes** | `bool` | `False` | Convert `\r` and `\n` etc., in your title/body before sending. |
|
||||
| **encoding** | `str` | `"utf-8"` | Character encoding for your content. |
|
||||
| **secure_logging** | `bool` | `True` | Filter out secrets (passwords, tokens) from debug logs. |
|
||||
| **plugin_paths** | `List[str]` | `[]` | One-level scan of directories or explicit `.py` files for custom notification plugins. |
|
||||
| **storage_mode** | `Optional[str]` | `None` | Enable persistent storage: `"auto"` (on-demand) or `"flush"` (per notification). |
|
||||
| **storage_path** | `Optional[str]` | `None` | Custom file path to use for persistent storage (overrides default). |
|
||||
| **_recursion** | `int` | Internal counter | Tracks recursive calls when using `apprise-api`. |
|
||||
| **_uid** | `str` | Internal UUID | Unique identifier to prevent API-level loops. |
|
||||
|
||||
Here is an example of what the `html_notify_map` may look like (below is the default settings):
|
||||
```python
|
||||
html_notify_map = {
|
||||
NotifyType.INFO: '#3AA3E3',
|
||||
NotifyType.SUCCESS: '#3AA337',
|
||||
NotifyType.FAILURE: '#A32037',
|
||||
NotifyType.WARNING: '#CACF29',
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
### Templating Placeholders
|
||||
|
||||
When resolving `image_path_mask` or `image_url_mask`, the following tokens are replaced:
|
||||
|
||||
| Placeholder | Runtime Value | Example | Description |
|
||||
|----------------|---------------------------|---------------------------|-------------------------------------------------------------------------------------------------|
|
||||
| **`{THEME}`** | `asset.theme` | `"default"` | The theme folder name to reference. |
|
||||
| **`{TYPE}`** | lower-cased `NotifyType` | `"warning"` | Type of notification (`info`, `success`, `warning`, `failure`, etc.). |
|
||||
| **`{XY}`** | resolution string | `"72x72"` | Pixel dimensions of the icon. Apprise ships `32x32`, `72x72`, `128x128`, `256x256` by default. |
|
||||
| **`{EXTENSION}`** | `asset.default_extension` | `".png"` | File extension for your images. |
|
||||
|
||||
---
|
||||
|
||||
### Usage Example
|
||||
|
||||
```python
|
||||
import apprise
|
||||
from apprise import AppriseAsset
|
||||
|
||||
# 1. Define your custom asset:
|
||||
asset = AppriseAsset(
|
||||
app_id="MyApp",
|
||||
app_desc="MyApp Alerts",
|
||||
app_url="https://example.com",
|
||||
theme="custom-theme",
|
||||
default_extension=".jpeg",
|
||||
image_path_mask="/opt/images/{THEME}/{TYPE}-{XY}{EXTENSION}",
|
||||
image_url_mask=(
|
||||
"https://cdn.example.com/assets/{THEME}/{TYPE}-{XY}{EXTENSION}"
|
||||
),
|
||||
plugin_paths=[
|
||||
"/opt/myapp/plugins", # Scan this directory for .py plugins
|
||||
"/opt/myapp/custom.py", # Load this single plugin file
|
||||
],
|
||||
async_mode=False, # Send one notification at a time
|
||||
storage_mode="flush", # Persist every notification to disk
|
||||
storage_path="/var/cache/myapp.db",
|
||||
)
|
||||
|
||||
# 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:
|
||||
# 2. Create Apprise with your asset:
|
||||
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.
|
||||
# 3. Add your services and send a notification:
|
||||
apobj.add("mailto://user:pass@example.com")
|
||||
apobj.add("discord://webhook_id/webhook_token")
|
||||
apobj.notify(
|
||||
title="Deployment Complete",
|
||||
body="Version 2.1.0 has been successfully deployed!",
|
||||
)
|
||||
```
|
||||
|
||||
> **Tip:** You can also override any attribute on the fly:
|
||||
> ```python
|
||||
> asset.theme = "night-mode"
|
||||
> asset.secure_logging = False
|
||||
> ```
|
||||
|
||||
## The Apprise Notification Object
|
||||
The **[[The Apprise Object|Development_API#the-apprise-object]]** actually already does a really good managing these for you. But if you want to manage the notifications yourself here is how you can do it:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue