Bug fixes and documentation

Author: joergschultzelutter

README.md

@@ -0,0 +1,52 @@
+# robotframework-aprslib
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+```robotframework-apprise``` is a [Robot Framework](https://www.robotframework.org) keyword collection for the [apprise](https://github.com/caronc/apprise) push message library. It enables Robot Framework users to send push/email messages to every message service supported by Apprise.
+
+![transmit](img/message.jpg)
+
+## Installation
+
+- clone repository
+- ``pip install -r dependencies.txt``
+
+## Robot Framework Library Example
+
+In order to run the example code, you need to provide at least one valid target messenger. Have a look at [Apprise's list of supported messengers](https://github.com/caronc/apprise/wiki)
+
+- [send_apprise_message](src/send_apprise_message.robot)
+
+## Library usage and supported keywords
+
+| Keyword|Description|
+|------- |-----------|
+|``Send Apprise Message``|Sends a push message through Apprise|
+|``Set Clients`` and ``Set Attachments``|Sets a new value list and replace the previous values|
+|``Add Client`` and ``Add Attachment``|Adds a value to an existing list|
+|``Remove Client`` and ``Remove Attachment``|Removes a value from an existing list (if present)|
+|``Clear All Clients`` and ``Clear All Attachments``|Completely removes the current values from the respective list|
+|``Set Delimiter``|Optional reconfiguration of this Robot Framework library's delimiter. See details below|
+
+
+All ``clients`` and ``attachments`` options can be passed as a ``List`` type variable or as a string. If you use a string, the default delimiter is a comma ``,``. In case you need to use a different delimiter, use the ``Set Delimiter`` keyword.
+
+``Attachments`` are purely optional. Providing at least one ``Client`` is mandatory, though. Both ``Attachments`` and ``Clients`` can either be provided as a ``List`` item or as a separated string.
+
+Examples:
+
+        # Send a message with one client and a List which contains our images
+        @{IMAGE_LIST}=          Create List     http://www.mysite.com/image1.jpg    http://www.mysite.com/image2.jpg
+        Send Apprise Message    title=Robot Framework Apprise Demo   body=Connect to Apprise with your Robot Framework Tests!    clients=<apprise_client>     attachments=${IMAGE_LIST}
+
+        # Send a message with one client. Our attachments use a comma-separated string (default)
+        Send Apprise Message    title=Robot Framework Apprise Demo   body=Connect to Apprise with your Robot Framework Tests!    clients=<apprise_client>     attachments=http://www.mysite.com/image1.jpg,http://www.mysite.com/image2.jpg
+
+        # Send a message with one client. Our attachments use a custom delimiter ^
+        Set Delimiter            ^
+        Send Apprise Message    title=Robot Framework Apprise Demo   body=Connect to Apprise with your Robot Framework Tests!    clients=<apprise_client>     attachments=http://www.mysite.com/image1.jpg^http://www.mysite.com/image2.jpg
+
+
+## Known issues
+
+- This library uses Apprise's default async behavior. Currently, you cannot send messages in a synchronous way.
+- The current version of this library does not permit you to set the target format (text, HTML). It uses Apprise's default format which is HTML.

img/message.jpg

@@ -1,8 +1,8 @@
 #!/opt/local/bin/python3
 #
 # Robot Framework Keyword library wrapper for
-# https://github.com/rossengeorgiev/aprs-python
-# Author: Joerg Schultze-Lutter, 2021
+# https://github.com/caronc/apprise
+# Author: Joerg Schultze-Lutter, 2022
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -43,12 +43,14 @@ class AppriseLibrary:
     DEFAULT_BODY = ""
     DEFAULT_CLIENTS = []
     DEFAULT_ATTACHMENTS = []
+    DEFAULT_DELIMITER = ','
 
     # Class-internal Apprise parameters
     __title = None
     __body = None
     __clients = None
     __attachments = None
+    __delimiter = None
 
     # This is our Apprise object
     __instance = None
@@ -59,10 +61,12 @@ def __init__(
         body: int = DEFAULT_BODY,
         clients: list = DEFAULT_CLIENTS,
         attachments: list = DEFAULT_ATTACHMENTS,
+        delimiter: str = DEFAULT_DELIMITER,
     ):
         self.__title = title
         self.__body = body
         self.__instance = None
+        self.__delimiter = delimiter
         self.__clients = self.__transform_apprise_clients(clients=clients)
         self.__attachments = self.__transform_apprise_attachments(
             attachments=attachments
@@ -75,7 +79,7 @@ def __transform_apprise_clients(self, clients: object):
 
         # if we deal with a string, split it up and return it as a list
         if isinstance(clients, str):
-            return clients.split(",")
+            return clients.split(self.delimiter)
         else:
             return clients
 
@@ -88,7 +92,7 @@ def __transform_apprise_attachments(self, attachments: object):
 
         # if we deal with a string, split it up and return it as a list
         if isinstance(attachments, str):
-            return attachments.split(",")
+            return attachments.split(self.delimiter)
         else:
             return attachments
 
@@ -105,6 +109,10 @@ def title(self):
     def body(self):
         return self.__body
 
+    @property
+    def delimiter(self):
+        return self.__delimiter
+
     @property
     def clients(self):
         return self.__clients
@@ -135,6 +143,14 @@ def body(self, body: str):
             raise ValueError("No value for 'body' has been specified")
         self.__body = body
 
+    @delimiter.setter
+    def delimiter(self, delimiter: str):
+        if not delimiter:
+            raise ValueError("No value for 'delimiter' has been specified")
+        if len(delimiter) != 1:
+            raise ValueError("'delimiter' needs to be exactly one character")
+        self.__delimiter = delimiter
+
     @attachments.setter
     def attachments(self, attachments: object):
         if not attachments:
@@ -166,6 +182,10 @@ def get_title(self):
     def get_body(self):
         return self.body
 
+    @keyword("Get Delimiter")
+    def get_delimiter(self):
+        return self.delimiter
+
     @keyword("Get Clients")
     def get_clients(self):
         return self.clients
@@ -187,6 +207,11 @@ def set_body(self, body: str = None):
         logger.debug(msg="Setting 'body' attribute")
         self.body = body
 
+    @keyword("Set Delimiter")
+    def set_delimiter(self, delimiter: str = None):
+        logger.debug(msg="Setting 'delimiter' attribute")
+        self.delimiter = delimiter
+
     @keyword("Set Clients")
     def set_clients(self, clients: object):
         logger.debug(msg="Setting 'clients' attribute")
@@ -262,6 +287,10 @@ def send_apprise_message(
         if attachments:
             self.attachments = self.__transform_apprise_attachments(attachments)
 
+        # Check if we have received at least one client
+        if len(self.clients) < 1:
+            raise ValueError("You need to specify at least one target client")
+
         # Attach the clients
         for client in self.clients:
             logger.debug(msg=f"Attaching client '{client}'")
@@ -286,7 +315,10 @@ def send_apprise_message(
             body=self.body,
             attach=self.attachments,
         )
+        return result
 
 
 if __name__ == "__main__":
+    a = AppriseLibrary()
+    a.set_delimiter(',')
     pass