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

Updated Development_Contribution (markdown)

master
Chris Caron 2021-08-29 11:59:01 -04:00
parent 30deaafeb9
commit bd42e040af
1 changed files with 75 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
Development_Contribution.md

@ -10,14 +10,68 @@ The following should get you all set up:
pip install --requirement requirements.txt --requirement dev-requirements.txt
```
# Testing
There is a few tools that work right out of the box in the root of any branch you're working in. These tools allow you to clone the Apprise branch and immediately test your changes without having to install anything into your environment.
More details can be found [here](https://github.com/caronc/apprise/tree/master/bin) about them.
# Building Your Own Notification Plugin
It basically boils down to this:
```python
# Whatever your class is called that inherits NotifyBase, make sure
# to also make that the filename as well. Below is an example of what
# plugins/NotifyFooBar.py might look like:
from .NotifyBase import NotifyBase
class NotifyFooBar(NotifyBase):
# Define a human readable description of our object
service_name = 'FooBar Notification'
# Our protocol:// Apprise will detect and hand off further
# parsing of the URL to your parse_url() function you write:
protocol = 'foobar'
# Where can people get information on how to use your plugin?
setup_url = 'https://github.com/caronc/apprise/wiki/Notify_FooBar'
def __init__(self, **kwargs):
"""
Your class initialization
"""
super(NotifyFooBar, self).__init__(**kwargs)
def url(self, privacy=False, *args, **kwargs):
"""
Always be able to build your Apprise URL exactly the way you parsed
it in the parse_url() function
"""
return self.protocol + "://"
def send(self, body, title='', **kwargs):
"""
Perform Notification here using the provided body and title
"""
print("Foobar Notification Sent to STDOUT")
# always return True if your notification was sent successfully
# otherwise return False if it failed.
return True
@staticmethod
def parse_url(url):
"""
The URL that starts with foobar://
"""
# NotifyBase.parse_url() will make the initial parsing of your string
# very easy to use. It will tokenize the entire URL for you. The tokens
# are then passed into your __init__() function you defined to generate
# you're object
tokens = NotifyBase.parse_url(url, verify_host=False)
# massage your tokens here
return tokens
```
With respect to the above example:
- You just need to create a single notification python file as `/plugins/NotifyServiceName.py`
- Make sure you call the class inside `NotifyServiceName` and inherit from `NotifyBase`
- Make sure your class object name is the same as the filename you create. This is very important!
@ -25,15 +79,14 @@ It basically boils down to this:
- **the class objects**:
- `service_name`: A string that acts as a default descriptive name associated with the Notification
- `service_url`: A string that identifies the platform/services URL. This is used purely as meta data for those who seek it. But this field is required.
- `secure_protocol`: A string (or can be a list of strings) identifying the scheme:// keyword. So setting this to say `'bad'` means that this class you're creating will be instantiated if someone tries to access `bad://`
- `protocol` and/or `secure_protocol`: A string (or can be a list of strings) identifying the scheme:// keyword that apprise uses to map to the Plugin Class it's associated with. For example, `slack` is mapped to the `NotifySlack` class found in the `/plugins/NotifySlack.py` file. This must be defined so that people can leverage your plugin. You must choose a protocol name that isn't already taken.
- `setup_url`: A string that identifies the URL a user can use to get information on how to use this Apprise Notification. At this time I'm just creating URLs that point back to my GitHub Wiki page.
- `templates`, `template_tokens`, and `template_args`. It's best to look at all of the many services that exist to see how to prepare this. But this is just a way of identifying what the class accepts as arguments. You can optionally identify some regular expressions to validate the arguments as well. This is provided as both meta data to those requesting it (it plays a huge role in the API i built as the JSON output is based on this). This data is also heavily validated using unit tests. So if you identify something there that isn't defined in the `__init__()` of your class, or vs versa (you declare something in your `__init__()` and do not identify it here. Then you'll get an error (tests will not pass). The problem is the error is rather cryptic; (this is what is happening to you; you've identified `secret` in only one location)
- **the functions**:
- `__init__(self, *args, **kwargs)`: Define what is required to initialize your object/notification. Just make sure to cross reference it in the `template*` stuff (explained above).
-`send(self, body, title='', *args, **kwargs)` at a bare minimum. See other Notify scripts as to how you can expand on this. But just take the `body` and `title` and construct your message and send it.
- `url()`. This function must be able to construct a URL that would re-generate a copy of the exact same object if passed into `parse_url()`
- `parse_url(url)`: this is a **staticmethod** that parses the Apprise URL and breaks it into a dictionary of the components. The dictionary it creates must map up to what the `__init__()` takes as it's arguments
1. `__init__(self, *args, **kwargs)`: Define what is required to initialize your object/notification. Just make sure to cross reference it in the `template*` stuff (explained above).
1. `send(self, body, title='', *args, **kwargs)` at a bare minimum. See other Notify scripts as to how you can expand on this. But just take the `body` and `title` and construct your message and send it.
1. `url()`. This function must be able to construct a URL that would re-generate a copy of the exact same object if passed into `parse_url()`
1. `parse_url(url)`: this is a **staticmethod** that parses the Apprise URL and breaks it into a dictionary of the components. The dictionary it creates must map up to what the `__init__()` takes as it's arguments
- **Putting it together**:
```python
@ -121,5 +174,13 @@ It basically boils down to this:
You can have a look at the NotifyBase object and see all of the other entries you can define that Apprise can look after for you (such as restricting the message length, title length, handling TEXT -> Markdown, etc). You can also look at how other classes were built.
# Demo Plugins
- [An HTTP Web Request Based Plugin](DemoPlugin_WebRequest)
## Demo Plugins
Some people learn by just working with already pre-written code. So here are some sample plugins I put together that you can copy and paste and start your own notification service off of. Each plugin tries to explain with a lot of in-line code comments what is going on and why things are the way they are:
- [An HTTP Web Request Based Plugin](DemoPlugin_WebRequest)
- More coming soon :slightly_smiling_face:
# Testing
There is a few tools that work right out of the box in the root of any branch you're working in. These tools allow you to clone the Apprise branch and immediately test your changes without having to install anything into your environment.
More details can be found [here](https://github.com/caronc/apprise/tree/master/bin) about them.