From 4479a7f71bf37058476dc68b6ad18cd47d1baaf4 Mon Sep 17 00:00:00 2001
From: Chris Caron <lead2gold@gmail.com>
Date: Mon, 8 Oct 2018 15:21:08 -0400
Subject: [PATCH] details() preview commit for review; refs #21

---
 apprise/Apprise.py                         | 33 +++++++++++++++++
 apprise/AppriseAsset.py                    | 15 ++++++++
 apprise/plugins/NotifyBase.py              | 17 +++++++--
 apprise/plugins/NotifyBoxcar.py            |  9 +++++
 apprise/plugins/NotifyDiscord.py           |  8 ++++
 apprise/plugins/NotifyEmail.py             | 16 +++++---
 apprise/plugins/NotifyEmby.py              |  8 ++++
 apprise/plugins/NotifyFaast.py             |  9 +++++
 apprise/plugins/NotifyGrowl/NotifyGrowl.py |  9 +++++
 test/test_api.py                           | 43 ++++++++++++++++++++++
 10 files changed, 158 insertions(+), 9 deletions(-)

diff --git a/apprise/Apprise.py b/apprise/Apprise.py
index 8512ea14..bd81f5d5 100644
--- a/apprise/Apprise.py
+++ b/apprise/Apprise.py
@@ -32,6 +32,7 @@ from .AppriseAsset import AppriseAsset
 
 from . import NotifyBase
 from . import plugins
+from . import __version__
 
 logger = logging.getLogger(__name__)
 
@@ -277,6 +278,38 @@ class Apprise(object):
 
         return status
 
+    def details(self):
+        """
+        Returns the details associated with the Apprise object
+
+        """
+
+        # general object returned
+        response = {
+            # Defines the current version of Apprise
+            'version': __version__,
+            # Lists all of the currently supported Notifications
+            'schemas': [],
+            # Includes the configured asset details
+            'asset': self.asset.details(),
+        }
+
+        # to add it's mapping to our hash table
+        for entry in sorted(dir(plugins)):
+
+            # Get our plugin
+            plugin = getattr(plugins, entry)
+
+            # Build our response object
+            response['schemas'].append({
+                'service_name': getattr(plugin, 'service_name', None),
+                'service_url': getattr(plugin, 'service_url', None),
+                'protocol': getattr(plugin, 'protocol', None),
+                'secure_protocol': getattr(plugin, 'secure_protocol', None),
+            })
+
+        return response
+
     def __len__(self):
         """
         Returns the number of servers loaded
diff --git a/apprise/AppriseAsset.py b/apprise/AppriseAsset.py
index 5bbba2a9..4af1c72b 100644
--- a/apprise/AppriseAsset.py
+++ b/apprise/AppriseAsset.py
@@ -216,6 +216,21 @@ class AppriseAsset(object):
 
         return None
 
+    def details(self):
+        """
+        Returns the details associated with the AppriseAsset object
+
+        """
+        return {
+            'app_id': self.app_id,
+            'app_desc': self.app_desc,
+            'default_extension': self.default_extension,
+            'theme': self.theme,
+            'image_path_mask': self.image_url_mask,
+            'image_url_mask': self.image_url_mask,
+            'image_url_logo': self.image_url_logo,
+        }
+
     @staticmethod
     def hex_to_rgb(value):
         """
diff --git a/apprise/plugins/NotifyBase.py b/apprise/plugins/NotifyBase.py
index 9f028499..0a8a3687 100644
--- a/apprise/plugins/NotifyBase.py
+++ b/apprise/plugins/NotifyBase.py
@@ -34,7 +34,6 @@ except ImportError:
 from ..utils import parse_url
 from ..utils import parse_bool
 from ..utils import is_hostname
-from ..common import NOTIFY_IMAGE_SIZES
 from ..common import NOTIFY_TYPES
 from ..common import NotifyFormat
 from ..common import NOTIFY_FORMATS
@@ -70,7 +69,8 @@ PATHSPLIT_LIST_DELIM = re.compile(r'[ \t\r\n,\\/]+')
 # Regular expression retrieved from:
 # http://www.regular-expressions.info/email.html
 IS_EMAIL_RE = re.compile(
-    r"(?P<userid>[a-z0-9$%+=_~-]+"
+    r"((?P<label>[^+]+)\+)?"
+    r"(?P<userid>[a-z0-9$%=_~-]+"
     r"(?:\.[a-z0-9$%+=_~-]+)"
     r"*)@(?P<domain>(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+"
     r"[a-z0-9](?:[a-z0-9-]*"
@@ -84,16 +84,25 @@ class NotifyBase(object):
     This is the base class for all notification services
     """
 
+    # The default descriptive name associated with the Notification
+    service_name = None
+
+    # The services URL
+    service_url = None
+
     # The default simple (insecure) protocol
     # all inheriting entries must provide their protocol lookup
     # protocol:// (in this example they would specify 'protocol')
-    protocol = ''
+    protocol = None
 
     # The default secure protocol
     # all inheriting entries must provide their protocol lookup
     # protocols:// (in this example they would specify 'protocols')
     # This value can be the same as the defined protocol.
-    secure_protocol = ''
+    secure_protocol = None
+
+    # A URL that takes you to the setup/help of the specific protocol
+    setup_url = None
 
     # Most Servers do not like more then 1 request per 5 seconds, so 5.5 gives
     # us a safe play range...
diff --git a/apprise/plugins/NotifyBoxcar.py b/apprise/plugins/NotifyBoxcar.py
index 2d35d119..5d336647 100644
--- a/apprise/plugins/NotifyBoxcar.py
+++ b/apprise/plugins/NotifyBoxcar.py
@@ -63,9 +63,18 @@ class NotifyBoxcar(NotifyBase):
     A wrapper for Boxcar Notifications
     """
 
+    # The default descriptive name associated with the Notification
+    service_name = 'Boxcar'
+
+    # The services URL
+    service_url = 'https://boxcar.io/'
+
     # All boxcar notifications are secure
     secure_protocol = 'boxcar'
 
+    # A URL that takes you to the setup/help of the specific protocol
+    setup_url = 'https://github.com/caronc/apprise/wiki/Notify_boxcar'
+
     # Boxcar URL
     notify_url = 'https://boxcar-api.io/api/push/'
 
diff --git a/apprise/plugins/NotifyDiscord.py b/apprise/plugins/NotifyDiscord.py
index b97e6ff6..7b41bd0d 100644
--- a/apprise/plugins/NotifyDiscord.py
+++ b/apprise/plugins/NotifyDiscord.py
@@ -49,10 +49,18 @@ class NotifyDiscord(NotifyBase):
     A wrapper to Discord Notifications
 
     """
+    # The default descriptive name associated with the Notification
+    service_name = 'Discord'
+
+    # The services URL
+    service_url = 'https://discordapp.com/'
 
     # The default secure protocol
     secure_protocol = 'discord'
 
+    # A URL that takes you to the setup/help of the specific protocol
+    setup_url = 'https://github.com/caronc/apprise/wiki/Notify_discored'
+
     # Discord Webhook
     notify_url = 'https://discordapp.com/api/webhooks'
 
diff --git a/apprise/plugins/NotifyEmail.py b/apprise/plugins/NotifyEmail.py
index e6d16c32..1dcd5f38 100644
--- a/apprise/plugins/NotifyEmail.py
+++ b/apprise/plugins/NotifyEmail.py
@@ -47,7 +47,7 @@ WEBBASE_LOOKUP_TABLE = (
     # Google GMail
     (
         'Google Mail',
-        re.compile(r'^(?P<id>[^@]+)@(?P<domain>gmail\.com)$', re.I),
+        re.compile(r'^((?P<label>[^+]+)\+)?(?P<id>[^@]+)@(?P<domain>gmail\.com)$', re.I),
         {
             'port': 587,
             'smtp_host': 'smtp.gmail.com',
@@ -59,7 +59,7 @@ WEBBASE_LOOKUP_TABLE = (
     # Pronto Mail
     (
         'Pronto Mail',
-        re.compile(r'^(?P<id>[^@]+)@(?P<domain>prontomail\.com)$', re.I),
+        re.compile(r'^((?P<label>[^+]+)\+)?(?P<id>[^@]+)@(?P<domain>prontomail\.com)$', re.I),
         {
             'port': 465,
             'smtp_host': 'secure.emailsrvr.com',
@@ -71,7 +71,7 @@ WEBBASE_LOOKUP_TABLE = (
     # Microsoft Hotmail
     (
         'Microsoft Hotmail',
-        re.compile(r'^(?P<id>[^@]+)@(?P<domain>(hotmail|live)\.com)$', re.I),
+        re.compile(r'^((?P<label>[^+]+)\+)?(?P<id>[^@]+)@(?P<domain>(hotmail|live)\.com)$', re.I),
         {
             'port': 587,
             'smtp_host': 'smtp.live.com',
@@ -83,7 +83,7 @@ WEBBASE_LOOKUP_TABLE = (
     # Yahoo Mail
     (
         'Yahoo Mail',
-        re.compile(r'^(?P<id>[^@]+)@(?P<domain>yahoo\.(ca|com))$', re.I),
+        re.compile(r'^((?P<label>[^+]+)\+)?(?P<id>[^@]+)@(?P<domain>yahoo\.(ca|com))$', re.I),
         {
             'port': 465,
             'smtp_host': 'smtp.mail.yahoo.com',
@@ -95,7 +95,7 @@ WEBBASE_LOOKUP_TABLE = (
     # Catch All
     (
         'Custom',
-        re.compile(r'^(?P<id>[^@]+)@(?P<domain>.+)$', re.I),
+        re.compile(r'^((?P<label>[^+]+)\+)?(?P<id>[^@]+)@(?P<domain>.+)$', re.I),
         {
             # Setting smtp_host to None is a way of
             # auto-detecting it based on other parameters
@@ -113,12 +113,18 @@ class NotifyEmail(NotifyBase):
 
     """
 
+    # The default descriptive name associated with the Notification
+    service_name = 'E-Mail'
+
     # The default simple (insecure) protocol
     protocol = 'mailto'
 
     # The default secure protocol
     secure_protocol = 'mailtos'
 
+    # A URL that takes you to the setup/help of the specific protocol
+    setup_url = 'https://github.com/caronc/apprise/wiki/Notify_email'
+
     # Default Non-Encryption Port
     default_port = 25
 
diff --git a/apprise/plugins/NotifyEmby.py b/apprise/plugins/NotifyEmby.py
index 8c56272f..1ecc5f46 100644
--- a/apprise/plugins/NotifyEmby.py
+++ b/apprise/plugins/NotifyEmby.py
@@ -37,6 +37,11 @@ class NotifyEmby(NotifyBase):
     """
     A wrapper for Emby Notifications
     """
+    # The default descriptive name associated with the Notification
+    service_name = 'Emby'
+
+    # The services URL
+    service_url = 'https://emby.media/'
 
     # The default protocol
     protocol = 'emby'
@@ -44,6 +49,9 @@ class NotifyEmby(NotifyBase):
     # The default secure protocol
     secure_protocol = 'embys'
 
+    # A URL that takes you to the setup/help of the specific protocol
+    setup_url = 'https://github.com/caronc/apprise/wiki/Notify_emby'
+
     # Emby uses the http protocol with JSON requests
     emby_default_port = 8096
 
diff --git a/apprise/plugins/NotifyFaast.py b/apprise/plugins/NotifyFaast.py
index eb02bc2c..5d6fb54b 100644
--- a/apprise/plugins/NotifyFaast.py
+++ b/apprise/plugins/NotifyFaast.py
@@ -28,9 +28,18 @@ class NotifyFaast(NotifyBase):
     A wrapper for Faast Notifications
     """
 
+    # The default descriptive name associated with the Notification
+    service_name = 'Faast'
+
+    # The services URL
+    service_url = 'http://www.faast.io/'
+
     # The default protocol (this is secure for faast)
     protocol = 'faast'
 
+    # A URL that takes you to the setup/help of the specific protocol
+    setup_url = 'https://github.com/caronc/apprise/wiki/Notify_faast'
+
     # Faast uses the http protocol with JSON requests
     notify_url = 'https://www.appnotifications.com/account/notifications.json'
 
diff --git a/apprise/plugins/NotifyGrowl/NotifyGrowl.py b/apprise/plugins/NotifyGrowl/NotifyGrowl.py
index 32934b3e..ccfe5d02 100644
--- a/apprise/plugins/NotifyGrowl/NotifyGrowl.py
+++ b/apprise/plugins/NotifyGrowl/NotifyGrowl.py
@@ -50,9 +50,18 @@ class NotifyGrowl(NotifyBase):
 
     """
 
+    # The default descriptive name associated with the Notification
+    service_name = 'Growl'
+
+    # The services URL
+    service_url = 'http://growl.info/'
+
     # The default protocol
     protocol = 'growl'
 
+    # A URL that takes you to the setup/help of the specific protocol
+    setup_url = 'https://github.com/caronc/apprise/wiki/Notify_growl'
+
     # Default Growl Port
     default_port = 23053
 
diff --git a/test/test_api.py b/test/test_api.py
index 84c2e79d..fddd3159 100644
--- a/test/test_api.py
+++ b/test/test_api.py
@@ -27,6 +27,8 @@ from apprise import NotifyBase
 from apprise import NotifyType
 from apprise import NotifyFormat
 from apprise import NotifyImageSize
+from apprise import plugins
+from apprise import __version__
 from apprise.Apprise import __load_matrix
 import pytest
 
@@ -468,3 +470,44 @@ def test_apprise_asset(tmpdir):
         NotifyImageSize.XY_256,
         extension='.test') == 'http://localhost/'
                               'default/info-256x256.test')
+
+
+def test_apprise_details():
+    """
+    API: Apprise() Details
+
+    """
+
+    # Caling load matix a second time which is an internal function causes it
+    # to skip over content already loaded into our matrix and thefore accesses
+    # other if/else parts of the code that aren't otherwise called
+    __load_matrix()
+
+    a = Apprise()
+
+    # Details object
+    details = a.details()
+
+    # Dictionary response
+    assert isinstance(details, dict)
+
+    # Apprise version
+    assert 'version' in details
+    assert details.get('version') == __version__
+
+    # Defined schemas identify each plugin
+    assert 'schemas' in details
+    assert isinstance(details.get('schemas'), list)
+
+    # We have an entry per defined plugin
+    assert len(details.get('schemas')) == len(dir(plugins))
+
+    assert 'asset' in details
+    assert isinstance(details.get('asset'), dict)
+    assert 'app_id' in details['asset']
+    assert 'app_desc' in details['asset']
+    assert 'default_extension' in details['asset']
+    assert 'theme' in details['asset']
+    assert 'image_path_mask' in details['asset']
+    assert 'image_url_mask' in details['asset']
+    assert 'image_url_logo' in details['asset']