Updated decorator_notify (markdown)

master
Chris Caron 2022-07-15 12:35:34 -04:00
parent 6b6969599c
commit 09ce1a69d5
1 changed files with 69 additions and 2 deletions

@ -31,7 +31,7 @@ def my_wrapper(body, title, notify_type, *args, **kwargs):
print("{}: {} - {}".format(notify_type, title, body))
```
### Function Parameter Breakdown
### 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:
| Variable | Required | Description
| ----------- | -------- | -----------
@ -39,6 +39,8 @@ When you define your wrapper function that `@notify` will control, you will need
| 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.
| attach | No | If the call to trigger your wrapper includes one or more attachment, you can find it here as `list()` of `AppriseAttachment()` objects. If there is no attachment specified, then this will be set to None.
| body_format | No | The message body format as identified by the calling user. For the CLI this defaults to `text`, but for developers, they can optionally set this or not. Possible values would be `None`, `"text"`, `"html"` or `"markdown"`.
**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
@ -101,6 +103,71 @@ Only variables that are required are provided in this dictionary. At worst case
}
```
## Plugin Loading
Apprise will only load functions wrapped with `@notify()`. These must be placed in a `.py`. The loading process works as follows:
1. If you provide an absolute path to a `.py` file, then it is simply loaded (hidden or not).
1. If you provide an absolute path to a directory, then one of 2 things can happen:
1. Any hidden directories or files are skipped.
1. if an `__init__.py` file is found in this specified directory, then it is loaded and further processing stops.
1. if no `__init__.py` file is found in the specified directory, then all `.py` files are loaded.
- if a directory is found, then one additional check is made for `directory/__init__.py`. If that is found, then that specifically is loaded (there is no recursive loading). In all other circumstances, the directory is skipped and moved on.
## Command Line References
## Developer API References
By default, the Apprise CLI tool will search the following directories for custom hooks:
**Linux/Mac**
- `~/.apprise/plugins`
- `~/.config/apprise/plugins`
**Windows**
- `%APPDATA%/Apprise/plugins`
- `%LOCALAPPDATA%/Apprise/plugins`
You can over-ride these paths by including a `--plugin-dir` (or `-P`) on the CLI to include your own location. If you provide an override the defaults are not referenced.
```bash
# Assuming we've defined a Python file with our @notify(on="foobar") and placed
# it into one of our default loading paths, we can do the following:
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.
```python
from apprise import Apprise
from apprise import AppriseAsset
# Prepare your Asset Object so that you can enable the Custom Plugins to be loaded for your
# instance of Apprise...
asset = AppriseAsset(plugin_paths="/path/to/scan")
# OR....
# You can also generate scan more then one file too:
asset = AppriseAsset(
plugin_paths=[
# iterate over all Python files found in the root of the specified path.
# This is NOT a recursive scan; see how directories work by reading
# The "Plugin Loading" section above.
"/dir/containing/many/python/libraries",
"/path/to//plugin.py",
# if you point to a directory that has an __init__.py file found in it, then only
# that directory is loaded (it's similar to point to a absolute .py file.
"/path/to/dir/library"
)
# Now that we've got our asset, we just work with our Apprise object as we normally do
aobj = Apprise(asset=asset)
# If our new custom `foobar://` library was loaded (presuming we prepared one like
# in the examples above). then you would be able to safely add it into Apprise at this point
aobj.add('foobar://')
# Send our notification out through our foobar://
aobj.notify("test")
```
### Notes and Restrictions
- You can not assign a `schema://` that already exists. You must define something unique.
- Apprise will just gracefully spit a warning out that it did not load your plugin if this conflict is found.