Updated decorator_notify (markdown)

master
Chris Caron 2022-07-15 14:46:21 -04:00
parent 09ce1a69d5
commit 69b579b1d9
1 changed files with 60 additions and 6 deletions

@ -9,11 +9,11 @@ A Custom notification works the same way by letting Apprise know you want to map
The advantage of having your own custom hook is that you can now extend Apprise to do just about anything. You're free to write any logic you want within the confines of your custom wrapper. You could:
1. Process the message `body` as an instruction set to run and admin task such as:
1. Cleaning a directory of old files
1. performing server maintenance
1. Updating your SSL Certificates on your website
1. Trigger a puppet call into your fleet of servers
1. Trigger code to sell stocks/bitcoins or buy some
- :broom: Cleaning a directory of old files
- :computer: performing server maintenance
- :closed_lock_with_key: Updating your SSL Certificates on your website
- :rocket: Trigger a puppet call into your fleet of servers
- :coin: Trigger code to sell stocks/bitcoins or buy some
1. Trigger your own custom notification service
1. Anything you want can be mapped to it's own `schema://` that you define.
@ -30,6 +30,8 @@ def my_wrapper(body, title, notify_type, *args, **kwargs):
# A simple test - print to screen
print("{}: {} - {}".format(notify_type, title, body))
```
### Wrapper Return Values
Your function can optionally return `True` if it was successful or `False` if it wasn't. This information will get passed back up through the Apprise library. If you choose to not return anything at all (or return `None`) then this is interpreted as being successful.
### Wrapper Parameter Breakdown
When you define your wrapper function that `@notify` will control, you will need to consider the following function parameters you can provide it:
@ -102,6 +104,58 @@ Only variables that are required are provided in this dictionary. At worst case
"tag": set(),
}
```
### Complex Declarations
You can use the `@notify` declaration to define a more complex URL (instead of just the schema as explained up until now). For example:
```python
# include the decorator
from apprise.decorators import notify
# We can pass a full URL into the declaration instead of just the schema.
@notify(on="foobar://hostname:234?notify_on_complete=0")
def my_wrapper(body, meta, *args, **kwargs):
# write our logic here
```
The above example does the following:
1. Identify `foobar://` as still the trigger to trigger our wrapper
1. We actually preload our meta dictionary with a breakdown of an already preconstructed URL to be passed into our wrapper function.
The wrapper already contains a `meta` variable that looks like this now:
```json
{
"schema": "foorbar",
"url": "foobar://hostname:234?notify_on_complete=0",
"host": "hostname",
"port": 234,
"qsd": {"notify_on_complete": "0"}
}
```
The advantage of this is now when someone attempts to trigger your wrapper script, they can choose to over-ride the defaults you provided or not. For example:
```bash
# The below actually triggers your wrapper with `meta` set to exactly
# what was identified above.
bin/apprise -vv -b "use defaults" foobar://
```
But one could also do something like:
```bash
bin/apprise -vv -b "over-ride some" \
"foobar://example.com?notify_on_complete=1&just=checking"
```
The above would apply what what was identified over-top of the defaults building a `meta` block that looks like:
```json
{
"schema": "foorbar",
"url": "foobar://example.com:234?notify_on_complete=1&just=checking",
"host": "example.com",
"port": 234,
"qsd": {"notify_on_complete": "1", "just": "checking"}
}
```
You can see that fields that were not changed do not get changed. Ones that did however do. This allows you to prepare all of your configuration your wrapper may need ahead of time, but still allow a call to alter it if needed on a per configuration basis.
## Plugin Loading
Apprise will only load functions wrapped with `@notify()`. These must be placed in a `.py`. The loading process works as follows:
@ -132,7 +186,7 @@ apprise -vv -b "test" foobar://
## Developer API References
Developers only need to let their AppriseAsset know which directories it should scan for modules to load.
Developers only need to let their **AppriseAsset()** object know which directories it should scan for modules to load.
```python
from apprise import Apprise