You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
465 lines
17 KiB
465 lines
17 KiB
# -*- coding: utf-8 -*-
|
|
#
|
|
# Copyright (C) 2019 Chris Caron <lead2gold@gmail.com>
|
|
# All rights reserved.
|
|
#
|
|
# This code is licensed under the MIT License.
|
|
#
|
|
# Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
# of this software and associated documentation files(the "Software"), to deal
|
|
# in the Software without restriction, including without limitation the rights
|
|
# to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
|
|
# copies of the Software, and to permit persons to whom the Software is
|
|
# furnished to do so, subject to the following conditions :
|
|
#
|
|
# The above copyright notice and this permission notice shall be included in
|
|
# all copies or substantial portions of the Software.
|
|
#
|
|
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.IN NO EVENT SHALL THE
|
|
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
# THE SOFTWARE.
|
|
|
|
import six
|
|
import re
|
|
import copy
|
|
|
|
from os import listdir
|
|
from os.path import dirname
|
|
from os.path import abspath
|
|
|
|
# Used for testing
|
|
from . import NotifyEmail as NotifyEmailBase
|
|
from .NotifyGrowl import gntp
|
|
|
|
# NotifyBase object is passed in as a module not class
|
|
from . import NotifyBase
|
|
|
|
from ..common import NotifyImageSize
|
|
from ..common import NOTIFY_IMAGE_SIZES
|
|
from ..common import NotifyType
|
|
from ..common import NOTIFY_TYPES
|
|
from ..utils import parse_list
|
|
from ..utils import GET_SCHEMA_RE
|
|
from ..AppriseLocale import gettext_lazy as _
|
|
from ..AppriseLocale import LazyTranslation
|
|
|
|
# Maintains a mapping of all of the Notification services
|
|
SCHEMA_MAP = {}
|
|
|
|
__all__ = [
|
|
# Reference
|
|
'NotifyImageSize', 'NOTIFY_IMAGE_SIZES', 'NotifyType', 'NOTIFY_TYPES',
|
|
'NotifyBase',
|
|
|
|
# NotifyEmail Base Module (used for NotifyEmail testing)
|
|
'NotifyEmailBase',
|
|
|
|
# Tokenizer
|
|
'url_to_dict',
|
|
|
|
# gntp (used for NotifyGrowl Testing)
|
|
'gntp',
|
|
]
|
|
|
|
# we mirror our base purely for the ability to reset everything; this
|
|
# is generally only used in testing and should not be used by developers
|
|
MODULE_MAP = {}
|
|
|
|
|
|
# Load our Lookup Matrix
|
|
def __load_matrix(path=abspath(dirname(__file__)), name='apprise.plugins'):
|
|
"""
|
|
Dynamically load our schema map; this allows us to gracefully
|
|
skip over modules we simply don't have the dependencies for.
|
|
|
|
"""
|
|
# Used for the detection of additional Notify Services objects
|
|
# The .py extension is optional as we support loading directories too
|
|
module_re = re.compile(r'^(?P<name>Notify[a-z0-9]+)(\.py)?$', re.I)
|
|
|
|
for f in listdir(path):
|
|
match = module_re.match(f)
|
|
if not match:
|
|
# keep going
|
|
continue
|
|
|
|
# Store our notification/plugin name:
|
|
plugin_name = match.group('name')
|
|
try:
|
|
module = __import__(
|
|
'{}.{}'.format(name, plugin_name),
|
|
globals(), locals(),
|
|
fromlist=[plugin_name])
|
|
|
|
except ImportError:
|
|
# No problem, we can't use this object
|
|
continue
|
|
|
|
if not hasattr(module, plugin_name):
|
|
# Not a library we can load as it doesn't follow the simple rule
|
|
# that the class must bear the same name as the notification
|
|
# file itself.
|
|
continue
|
|
|
|
# Get our plugin
|
|
plugin = getattr(module, plugin_name)
|
|
if not hasattr(plugin, 'app_id'):
|
|
# Filter out non-notification modules
|
|
continue
|
|
|
|
elif plugin_name in MODULE_MAP:
|
|
# we're already handling this object
|
|
continue
|
|
|
|
# Add our plugin name to our module map
|
|
MODULE_MAP[plugin_name] = {
|
|
'plugin': plugin,
|
|
'module': module,
|
|
}
|
|
|
|
# Add our module name to our __all__
|
|
__all__.append(plugin_name)
|
|
|
|
# Load our module into memory so it's accessible to all
|
|
globals()[plugin_name] = plugin
|
|
|
|
# Load protocol(s) if defined
|
|
proto = getattr(plugin, 'protocol', None)
|
|
if isinstance(proto, six.string_types):
|
|
if proto not in SCHEMA_MAP:
|
|
SCHEMA_MAP[proto] = plugin
|
|
|
|
elif isinstance(proto, (set, list, tuple)):
|
|
# Support iterables list types
|
|
for p in proto:
|
|
if p not in SCHEMA_MAP:
|
|
SCHEMA_MAP[p] = plugin
|
|
|
|
# Load secure protocol(s) if defined
|
|
protos = getattr(plugin, 'secure_protocol', None)
|
|
if isinstance(protos, six.string_types):
|
|
if protos not in SCHEMA_MAP:
|
|
SCHEMA_MAP[protos] = plugin
|
|
|
|
if isinstance(protos, (set, list, tuple)):
|
|
# Support iterables list types
|
|
for p in protos:
|
|
if p not in SCHEMA_MAP:
|
|
SCHEMA_MAP[p] = plugin
|
|
|
|
return SCHEMA_MAP
|
|
|
|
|
|
# Reset our Lookup Matrix
|
|
def __reset_matrix():
|
|
"""
|
|
Restores the Lookup matrix to it's base setting. This is only used through
|
|
testing and should not be directly called.
|
|
"""
|
|
|
|
# Reset our schema map
|
|
SCHEMA_MAP.clear()
|
|
|
|
# Iterate over our module map so we can clear out our __all__ and globals
|
|
for plugin_name in MODULE_MAP.keys():
|
|
# Clear out globals
|
|
del globals()[plugin_name]
|
|
|
|
# Remove element from plugins
|
|
__all__.remove(plugin_name)
|
|
|
|
# Clear out our module map
|
|
MODULE_MAP.clear()
|
|
|
|
|
|
# Dynamically build our schema base
|
|
__load_matrix()
|
|
|
|
|
|
def _sanitize_token(tokens, default_delimiter):
|
|
"""
|
|
This is called by the details() function and santizes the output by
|
|
populating expected and consistent arguments if they weren't otherwise
|
|
specified.
|
|
|
|
"""
|
|
|
|
# Iterate over our tokens
|
|
for key in tokens.keys():
|
|
|
|
for element in tokens[key].keys():
|
|
# Perform translations (if detected to do so)
|
|
if isinstance(tokens[key][element], LazyTranslation):
|
|
tokens[key][element] = str(tokens[key][element])
|
|
|
|
if 'alias_of' in tokens[key]:
|
|
# Do not touch this field
|
|
continue
|
|
|
|
if 'map_to' not in tokens[key]:
|
|
# Default type to key
|
|
tokens[key]['map_to'] = key
|
|
|
|
if 'type' not in tokens[key]:
|
|
# Default type to string
|
|
tokens[key]['type'] = 'string'
|
|
|
|
elif tokens[key]['type'].startswith('list') \
|
|
and 'delim' not in tokens[key]:
|
|
# Default list delimiter (if not otherwise specified)
|
|
tokens[key]['delim'] = default_delimiter
|
|
|
|
elif tokens[key]['type'].startswith('choice') \
|
|
and 'default' not in tokens[key] \
|
|
and 'values' in tokens[key] \
|
|
and len(tokens[key]['values']) == 1:
|
|
# If there is only one choice; then make it the default
|
|
tokens[key]['default'] = \
|
|
tokens[key]['values'][0]
|
|
|
|
if 'regex' in tokens[key]:
|
|
# Verify that we are a tuple; convert strings to tuples
|
|
if isinstance(tokens[key]['regex'], six.string_types):
|
|
# Default tuple setup
|
|
tokens[key]['regex'] = \
|
|
(tokens[key]['regex'], None)
|
|
|
|
elif not isinstance(tokens[key]['regex'], (list, tuple)):
|
|
# Invalid regex
|
|
del tokens[key]['regex']
|
|
|
|
if 'required' not in tokens[key]:
|
|
# Default required is False
|
|
tokens[key]['required'] = False
|
|
|
|
if 'private' not in tokens[key]:
|
|
# Private flag defaults to False if not set
|
|
tokens[key]['private'] = False
|
|
return
|
|
|
|
|
|
def details(plugin):
|
|
"""
|
|
Provides templates that can be used by developers to build URLs
|
|
dynamically.
|
|
|
|
If a list of templates is provided, then they will be used over
|
|
the default value.
|
|
|
|
If a list of tokens are provided, then they will over-ride any
|
|
additional settings built from this script and/or will be appended
|
|
to them afterwards.
|
|
"""
|
|
|
|
# Our unique list of parsing will be based on the provided templates
|
|
# if none are provided we will use our own
|
|
templates = tuple(plugin.templates)
|
|
|
|
# The syntax is simple
|
|
# {
|
|
# # The token_name must tie back to an entry found in the
|
|
# # templates list.
|
|
# 'token_name': {
|
|
#
|
|
# # types can be 'string', 'int', 'choice', 'list, 'float'
|
|
# # both choice and list may additionally have a : identify
|
|
# # what the list/choice type is comprised of; the default
|
|
# # is string.
|
|
# 'type': 'choice:string',
|
|
#
|
|
# # values will only exist the type must be a fixed
|
|
# # list of inputs (generated from type choice for example)
|
|
#
|
|
# # If this is a choice:bool then you should ALWAYS define
|
|
# # this list as a (True, False) such as ('Yes, 'No') or
|
|
# # ('Enabled', 'Disabled'), etc
|
|
# 'values': [ 'http', 'https' ],
|
|
#
|
|
# # Identifies if the entry specified is required or not
|
|
# 'required': True,
|
|
#
|
|
# # Identify a default value
|
|
# 'default': 'http',
|
|
#
|
|
# # Optional Verification Entries min and max are for floats
|
|
# # and/or integers
|
|
# 'min': 4,
|
|
# 'max': 5,
|
|
#
|
|
# # A list will always identify a delimiter. If this is
|
|
# # part of a path, this may be a '/', or it could be a
|
|
# # comma and/or space. delimiters are always in a list
|
|
# # eg (if space and/or comma is a delimiter the entry
|
|
# # would look like: 'delim': [',' , ' ' ]
|
|
# 'delim': None,
|
|
#
|
|
# # Use regex if you want to share the regular expression
|
|
# # required to validate the field. The regex will never
|
|
# # accomodate the prefix (if one is specified). That is
|
|
# # up to the user building the URLs to include the prefix
|
|
# # on the URL when constructing it.
|
|
# # The format is ('regex', 'reg options')
|
|
# 'regex': (r'[A-Z0-9]+', 'i'),
|
|
#
|
|
# # A Prefix is always a string, to differentiate between
|
|
# # multiple arguments, sometimes content is prefixed.
|
|
# 'prefix': '@',
|
|
#
|
|
# # By default the key of this object is to be interpreted
|
|
# # as the argument to the notification in question. However
|
|
# # To accomodate cases where there are multiple types that
|
|
# # all map to the same entry, one can find a map_to value.
|
|
# 'map_to': 'function_arg',
|
|
#
|
|
# # Some arguments act as an alias_of an already defined object
|
|
# # This plays a role more with configuration file generation
|
|
# # since yaml files allow you to define different argumuments
|
|
# # in line to simplify things. If this directive is set, then
|
|
# # it should be treated exactly the same as the object it is
|
|
# # an alias of
|
|
# 'alias_of': 'function_arg',
|
|
#
|
|
# # Advise developers to consider the potential sensitivity
|
|
# # of this field owned by the user. This is for passwords,
|
|
# # and api keys, etc...
|
|
# 'private': False,
|
|
# },
|
|
# }
|
|
|
|
# Template tokens identify the arguments required to initialize the
|
|
# plugin itself. It identifies all of the tokens and provides some
|
|
# details on their use. Each token defined should in some way map
|
|
# back to at least one URL {token} defined in the templates
|
|
|
|
# Since we nest a dictionary within a dictionary, a simple copy isn't
|
|
# enough. a deepcopy allows us to manipulate this object in this
|
|
# funtion without obstructing the original.
|
|
template_tokens = copy.deepcopy(plugin.template_tokens)
|
|
|
|
# Arguments and/or Options either have a default value and/or are
|
|
# optional to be set.
|
|
#
|
|
# Since we nest a dictionary within a dictionary, a simple copy isn't
|
|
# enough. a deepcopy allows us to manipulate this object in this
|
|
# funtion without obstructing the original.
|
|
template_args = copy.deepcopy(plugin.template_args)
|
|
|
|
# Our template keyword arguments ?+key=value&-key=value
|
|
# Basically the user provides both the key and the value. this is only
|
|
# possibly by identifying the key prefix required for them to be
|
|
# interpreted hence the +/- keys are built into apprise by default for easy
|
|
# reference. In these cases, entry might look like '+' being the prefix:
|
|
# {
|
|
# 'arg_name': {
|
|
# 'name': 'label',
|
|
# 'prefix': '+',
|
|
# }
|
|
# }
|
|
#
|
|
# Since we nest a dictionary within a dictionary, a simple copy isn't
|
|
# enough. a deepcopy allows us to manipulate this object in this
|
|
# funtion without obstructing the original.
|
|
template_kwargs = copy.deepcopy(plugin.template_kwargs)
|
|
|
|
# We automatically create a schema entry
|
|
template_tokens['schema'] = {
|
|
'name': _('Schema'),
|
|
'type': 'choice:string',
|
|
'required': True,
|
|
'values': parse_list(plugin.secure_protocol, plugin.protocol)
|
|
}
|
|
|
|
# Sanitize our tokens
|
|
_sanitize_token(template_tokens, default_delimiter=('/', ))
|
|
# Delimiter(s) are space and/or comma
|
|
_sanitize_token(template_args, default_delimiter=(',', ' '))
|
|
_sanitize_token(template_kwargs, default_delimiter=(',', ' '))
|
|
|
|
# Argument/Option Handling
|
|
for key in list(template_args.keys()):
|
|
|
|
if 'alias_of' in template_args[key]:
|
|
# Check if the mapped reference is a list; if it is, then
|
|
# we need to store a different delimiter
|
|
alias_of = template_tokens.get(template_args[key]['alias_of'], {})
|
|
if alias_of.get('type', '').startswith('list') \
|
|
and 'delim' not in template_args[key]:
|
|
# Set a default delimiter of a comma and/or space if one
|
|
# hasn't already been specified
|
|
template_args[key]['delim'] = (',', ' ')
|
|
|
|
# _lookup_default looks up what the default value
|
|
if '_lookup_default' in template_args[key]:
|
|
template_args[key]['default'] = getattr(
|
|
plugin, template_args[key]['_lookup_default'])
|
|
|
|
# Tidy as we don't want to pass this along in response
|
|
del template_args[key]['_lookup_default']
|
|
|
|
# _exists_if causes the argument to only exist IF after checking
|
|
# the return of an internal variable requiring a check
|
|
if '_exists_if' in template_args[key]:
|
|
if not getattr(plugin,
|
|
template_args[key]['_exists_if']):
|
|
# Remove entire object
|
|
del template_args[key]
|
|
|
|
else:
|
|
# We only nee to remove this key
|
|
del template_args[key]['_exists_if']
|
|
|
|
return {
|
|
'templates': templates,
|
|
'tokens': template_tokens,
|
|
'args': template_args,
|
|
'kwargs': template_kwargs,
|
|
}
|
|
|
|
|
|
def url_to_dict(url):
|
|
"""
|
|
Takes an apprise URL and returns the tokens associated with it
|
|
if they can be acquired based on the plugins available.
|
|
|
|
None is returned if the URL could not be parsed, otherwise the
|
|
tokens are returned.
|
|
|
|
These tokens can be loaded into apprise through it's add()
|
|
function.
|
|
"""
|
|
|
|
# swap hash (#) tag values with their html version
|
|
_url = url.replace('/#', '/%23')
|
|
|
|
# Attempt to acquire the schema at the very least to allow our plugins to
|
|
# determine if they can make a better interpretation of a URL geared for
|
|
# them.
|
|
schema = GET_SCHEMA_RE.match(_url)
|
|
if schema is None:
|
|
# Not a valid URL; take an early exit
|
|
return None
|
|
|
|
# Ensure our schema is always in lower case
|
|
schema = schema.group('schema').lower()
|
|
if schema not in SCHEMA_MAP:
|
|
# Give the user the benefit of the doubt that the user may be using
|
|
# one of the URLs provided to them by their notification service.
|
|
# Before we fail for good, just scan all the plugins that support the
|
|
# native_url() parse function
|
|
results = \
|
|
next((r['plugin'].parse_native_url(_url)
|
|
for r in MODULE_MAP.values()
|
|
if r['plugin'].parse_native_url(_url) is not None),
|
|
None)
|
|
else:
|
|
# Parse our url details of the server object as dictionary
|
|
# containing all of the information parsed from our URL
|
|
results = SCHEMA_MAP[schema].parse_url(_url)
|
|
|
|
# Return our results
|
|
return results
|