diff --git a/decorator_notify.md b/decorator_notify.md index a31855c..ad09306 100644 --- a/decorator_notify.md +++ b/decorator_notify.md @@ -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