github
/
apprise
mirror of https://github.com/caronc/apprise
1
0
Fork 0
Code Issues Releases Wiki Activity

Updated decorator_notify (markdown)

master
Chris Caron 2022-07-16 12:20:57 -04:00
parent aaa9ab2cd7
commit 0a966c9d9e
1 changed files with 21 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
decorator_notify.md

@ -40,7 +40,7 @@ When you define your wrapper function that `@notify` will control, you will need
| 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. [See here](#the-meta-variable) for more details on the `meta` variable.
| meta | No | The **combined** (declaration + initialization) URL configuration passed into your my_wrapper. The declaration comes from the `@notify(on=schema)`. The initialization is how the calling user/application initializes your wrapper via their configuratin (a `schema://` call that aligns with your declaration). [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"`.
@ -60,7 +60,7 @@ def my_wrapper(body, *args, **kwargs):
```
# 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 `meta` variable passed into your wrapper function is always a dictionary. It contains the fully constructed URL based on your declaration (derived by the `@notify` decorator) in addition to the initialization Apprise URL specified by the user.
The following is an example of what the `meta` variable might look like in your wrapper:
```python
@ -76,6 +76,9 @@ The following is an example of what the `meta` variable might look like in your
"fullpath": "/test.php",
"query": "test.php",
# This is where the Query String Definition is identified (as a dictionary()
# You'll note that the keys identified on the parameter list are always
# converted to lowercase, but the values remain as-is.
"qsd": {"key": "value", "key2": "value2"},
# An AppriseAsset object grants you access to any customization
@ -87,16 +90,16 @@ The following is an example of what the `meta` variable might look like in your
"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:
Only the variables that are required are provided in this dictionary. Hence if both the declaration and initialization URLs are both `schema://`, then you will only have 4 entries such as:
```python
{
# This will always map back to your @notify(on="<schema>") declaration
# For this example we assume the schema was set to 'foobar'
"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
# Additionally passed in by the user (initialization) through is config and/or cli call
"url": "foorbar://",
# These 2 are ALWAYS present
@ -132,10 +135,10 @@ The wrapper already contains a `meta` variable that looks like this now:
}
```
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:
The advantage of this is now when someone attempts to trigger your wrapper script, they can choose to over-ride the defaults (during initialization) you provided (or not). For example:
```bash
# The below actually triggers your wrapper with `meta` set to exactly
# what was identified above.
# what was identified above. Hence, the template/declaration is used as is.
bin/apprise -vv -b "use defaults" foobar://
```
@ -144,7 +147,7 @@ But one could also do something like:
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:
The above would apply their initialization values on top of the declaration already set. With respect to this example, the `meta` block would now look like:
```json
{
"schema": "foorbar",
@ -155,17 +158,18 @@ The above would apply what what was identified over-top of the defaults building
}
```
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.
You can see that fields that were not changed keep the value passed from the declaration (ie.: the port). This allows you to prepare all of your configuration for your wrapper during it's declaration while still allowing the calling user to adjust values if required.
## 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.
While scanning a specified directory for all modules (due to not finding an `__init__.py` in the the path specified, all hidden files (prefixed with a period (`.`) are ignored.
## Command Line References
By default, the Apprise CLI tool will search the following directories for custom hooks:
@ -200,14 +204,16 @@ asset = AppriseAsset(plugin_paths="/path/to/scan")
# 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.
# 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",
# You can optionally specify an absolute path to a Python file
"/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.
# that directory is loaded (it's similar to point to a absolute .py file).
"/path/to/dir/library"
)