bazarr/libs/apprise/plugins/__init__.py

# -*- coding: utf-8 -*-
# BSD 2-Clause License
#
# Apprise - Push Notification Library.
# Copyright (c) 2024, Chris Caron <lead2gold@gmail.com>
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# 1. Redistributions of source code must retain the above copyright notice,
#    this list of conditions and the following disclaimer.
#
# 2. Redistributions in binary form must reproduce the above copyright notice,
#    this list of conditions and the following disclaimer in the documentation
#    and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.

import os
import copy

# Used for testing
from .NotifyBase 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 cwe312_url
from ..utils import GET_SCHEMA_RE
from ..logger import logger
from ..AppriseLocale import gettext_lazy as _
from ..AppriseLocale import LazyTranslation
from ..NotificationManager import NotificationManager


# Grant access to our Notification Manager Singleton
N_MGR = NotificationManager()

__all__ = [
    # Reference
    'NotifyImageSize', 'NOTIFY_IMAGE_SIZES', 'NotifyType', 'NOTIFY_TYPES',
    'NotifyBase',

    # Tokenizer
    'url_to_dict',
]


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.

    """

    # Used for tracking groups
    group_map = {}

    # 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

        elif 'name' not in tokens[key]:
            # Default to key
            tokens[key]['name'] = key

        if 'map_to' not in tokens[key]:
            # Default type to key
            tokens[key]['map_to'] = key

        # Track our map_to objects
        if tokens[key]['map_to'] not in group_map:
            group_map[tokens[key]['map_to']] = set()
        group_map[tokens[key]['map_to']].add(key)

        if 'type' not in tokens[key]:
            # Default type to string
            tokens[key]['type'] = 'string'

        elif tokens[key]['type'].startswith('list'):
            if 'delim' not in tokens[key]:
                # Default list delimiter (if not otherwise specified)
                tokens[key]['delim'] = default_delimiter

            if key in group_map[tokens[key]['map_to']]:  # pragma: no branch
                # Remove ourselves from the list
                group_map[tokens[key]['map_to']].remove(key)

            # Pointing to the set directly so we can dynamically update
            # ourselves
            tokens[key]['group'] = group_map[tokens[key]['map_to']]

        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
            #  - support dictionaries too
            tokens[key]['default'] = tokens[key]['values'][0] \
                if not isinstance(tokens[key]['values'], dict) \
                else next(iter(tokens[key]['values']))

        if 'values' in tokens[key] and isinstance(tokens[key]['values'], dict):
            # Convert values into a list if it was defined as a dictionary
            tokens[key]['values'] = [k for k in tokens[key]['values'].keys()]

        if 'regex' in tokens[key]:
            # Verify that we are a tuple; convert strings to tuples
            if isinstance(tokens[key]['regex'], str):
                # 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,
    #
    #            # Identifies all tokens detected to be associated with the
    #            # list:string
    #            # This is ony present in list:string objects and is only set
    #            # if this element acts as an alias for several other
    #            # kwargs/fields.
    #            'group': [],
    #
    #            # 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 requirements(plugin):
    """
    Provides a list of packages and its requirement details

    """
    requirements = {
        # Use the description to provide a human interpretable description of
        # what is required to make the plugin work. This is only nessisary
        # if there are package dependencies
        'details': '',

        # Define any required packages needed for the plugin to run.  This is
        # an array of strings that simply look like lines in the
        # `requirements.txt` file...
        #
        # A single string is perfectly acceptable:
        # 'packages_required' = 'cryptography'
        #
        # Multiple entries should look like the following
        # 'packages_required' = [
        #   'cryptography < 3.4`,
        # ]
        #
        'packages_required': [],

        # Recommended packages identify packages that are not required to make
        # your plugin work, but would improve it's use or grant it access to
        # full functionality (that might otherwise be limited).

        # Similar to `packages_required`, you would identify each entry in
        # the array as you would in a `requirements.txt` file.
        #
        #   - Do not re-provide entries already in the `packages_required`
        'packages_recommended': [],
    }

    # Populate our template differently if we don't find anything above
    if not (hasattr(plugin, 'requirements')
            and isinstance(plugin.requirements, dict)):
        # We're done early
        return requirements

    # Get our required packages
    _req_packages = plugin.requirements.get('packages_required')
    if isinstance(_req_packages, str):
        # Convert to list
        _req_packages = [_req_packages]

    elif not isinstance(_req_packages, (set, list, tuple)):
        # Allow one to set the required packages to None (as an example)
        _req_packages = []

    requirements['packages_required'] = [str(p) for p in _req_packages]

    # Get our recommended packages
    _opt_packages = plugin.requirements.get('packages_recommended')
    if isinstance(_opt_packages, str):
        # Convert to list
        _opt_packages = [_opt_packages]

    elif not isinstance(_opt_packages, (set, list, tuple)):
        # Allow one to set the recommended packages to None (as an example)
        _opt_packages = []

    requirements['packages_recommended'] = [str(p) for p in _opt_packages]

    # Get our package details
    _req_details = plugin.requirements.get('details')
    if not _req_details:
        if not (_req_packages or _opt_packages):
            _req_details = _('No dependencies.')

        elif _req_packages:
            _req_details = _('Packages are required to function.')

        else:  # opt_packages
            _req_details = \
                _('Packages are recommended to improve functionality.')
    else:
        # Store our details if defined
        requirements['details'] = _req_details

    # Return our compiled package requirements
    return requirements


def url_to_dict(url, secure_logging=True):
    """
    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')

    # CWE-312 (Secure Logging) Handling
    loggable_url = url if not secure_logging else cwe312_url(url)

    # 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
        logger.error('Unsupported URL: {}'.format(loggable_url))
        return None

    # Ensure our schema is always in lower case
    schema = schema.group('schema').lower()
    if schema not in N_MGR:
        # 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 = None
        for plugin in N_MGR.plugins():
            results = plugin.parse_native_url(_url)
            if results:
                break

        if not results:
            logger.error('Unparseable URL {}'.format(loggable_url))
            return None

        logger.trace('URL {} unpacked as:{}{}'.format(
            url, os.linesep, os.linesep.join(
                ['{}="{}"'.format(k, v) for k, v in results.items()])))

    else:
        # Parse our url details of the server object as dictionary
        # containing all of the information parsed from our URL
        results = N_MGR[schema].parse_url(_url)
        if not results:
            logger.error('Unparseable {} URL {}'.format(
                N_MGR[schema].service_name, loggable_url))
            return None

        logger.trace('{} URL {} unpacked as:{}{}'.format(
            N_MGR[schema].service_name, url,
            os.linesep, os.linesep.join(
                ['{}="{}"'.format(k, v) for k, v in results.items()])))

    # Return our results
    return results