Created decorator_notify (markdown)

decorator_notify.md

@@ -0,0 +1,106 @@
+# Custom Notifications
+This functionality is only available starting at Apprise v1+. The idea is to no longer be limited to just the Notification Services already built into Apprise.  Instead you can now very easily write your own and assign it to your own `schema://`
+
+To explain this further, first consider that Apprise is completely built around the Apprise URL's you feed it.
+
+If you feed Apprise a URL such as `tgram://private_credentials` (whether it be via the command line or a configuration file), you're telling it you want to send a [Telegram](notify_telegram) notification. Apprise is able to determine the building blocks it needs to prepare a Telegram notification from the `tgram://` prefix, and then it sends the notification by using the `private_credentials` you provided it.
+
+A Custom notification works the same way by letting Apprise know you want to map your `schema://` to custom code you wrote (instead of the Apprise Notification base it's already aware of).
+
+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
+1. Trigger your own custom notification service
+1. Anything you want can be mapped to it's own `schema://` that you define.
+
+## The Notification Decorator
+The `@notify` decorator is the key to linking everything together.  Below is a very simple example of what your `hook.py` might look like:
+```python
+# include the decorator
+from apprise.decorators import notify
+
+# This example maps foobar:// to your my_wrapper function
+@notify(on="foobar")
+def my_wrapper(body, title, notify_type, *args, **kwargs):
+
+   # A simple test - print to screen
+    print("{}: {} - {}".format(notify_type, title, body))
+```
+
+### Function 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:
+| Variable    | Required | Description
+| ----------- | -------- | -----------
+| body        | Yes     | The message body the calling user passed along
+| title       | No      | The message title which is an optional switch for Apprise so it wont' always be populated.
+| notify_type | No      | The message type will be `info`, `success`, `warning` or `failure`
+| meta        | No      | The **combined** URL configuration passed into your my_wrapper.  By the time your wrapper function is called, it will have been defined twice.  First it's declaration (by the `@notify(on=schema)`, second by how the user called your `schema://`.  The `@notify` declaration makes up the base of the URL while whatever the user provides to trigger your wrapper is applied on top.<br/>[See here](#the-meta-variable) for more details on the `meta` variable.
+
+**ALWAYS** end your wrapper declaration with `*args, **kwargs`.  This is VERY important to be forwards compatible with future versions of Apprise while at the same time being able to park entries on the wrapper you're not interested (flagged with `No` in the **Required** section above).  Hence your wrapper could be as simple as this if you wanted it to be:
+```python
+# include the decorator
+from apprise.decorators import notify
+
+# This example maps foobar:// to your my_wrapper function
+@notify(on="foobar")
+def my_wrapper(body, *args, **kwargs):
+    #                  ^         ^
+    #                  |         |
+    #               Always place here!
+    print(body)
+
+```
+
+# The `meta` Variable
+The `meta` variable passed into your wrapper function is always a dictionary and contains the fully constructed URL based on your declaration (in the `@notify` decorator) in addition to what was parsed by the user who loaded it.
+
+The following is an example of what the `meta` variable might look like in your wrapper:
+```python
+{
+  "schema": "foorbar",
+  "url": "foorbar://john:doe@hostname:80/test.php?key=value&KEY2=value2",
+  "host": "hostname",
+
+  "user": "john",
+  "password": "doe",
+  "port": 80,
+  "path": "/",
+  "fullpath": "/test.php",
+  "query": "test.php",
+
+  "qsd": {"key": "value", "key2": "value2"},
+
+  # An AppriseAsset object grants you access to any customization
+  # user of Apprise set up such as icon sets, application name, etc.
+  "asset": AppriseAsset(),
+
+  # The tag(s) that was assigned to this notification (by the user)
+  # that caused it to trigger.
+  "tag": set(),
+}
+```
+**Note**: the keys identified on the parameter list are always converted to lowercase, but the values remain untouched.
+
+Only variables that are required are provided in this dictionary. At worst case you will only have 4 entries such as:
+```python
+{
+  # This will always map back to your @notify(on="<schema>") declaration
+  "schema": "foorbar",
+
+  # This is the URL that was built based on your declaration and whatever was
+  # Additionally passed in by the user through is config and/or cli call
+  "url": "foorbar://",
+
+  # These 2 are ALWAYS present
+  "asset": AppriseAsset(),
+  "tag": set(),
+}
+```
+
+## Command Line References
+
+## Developer API References