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.
797 lines
28 KiB
797 lines
28 KiB
# -*- coding: utf-8 -*-
|
|
# BSD 2-Clause License
|
|
#
|
|
# Apprise - Push Notification Library.
|
|
# Copyright (c) 2023, 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 re
|
|
from .logger import logger
|
|
from time import sleep
|
|
from datetime import datetime
|
|
from xml.sax.saxutils import escape as sax_escape
|
|
|
|
from urllib.parse import unquote as _unquote
|
|
from urllib.parse import quote as _quote
|
|
|
|
from .AppriseLocale import gettext_lazy as _
|
|
from .AppriseAsset import AppriseAsset
|
|
from .utils import urlencode
|
|
from .utils import parse_url
|
|
from .utils import parse_bool
|
|
from .utils import parse_list
|
|
from .utils import parse_phone_no
|
|
|
|
# Used to break a path list into parts
|
|
PATHSPLIT_LIST_DELIM = re.compile(r'[ \t\r\n,\\/]+')
|
|
|
|
|
|
class PrivacyMode:
|
|
# Defines different privacy modes strings can be printed as
|
|
# Astrisk sets 4 of them: e.g. ****
|
|
# This is used for passwords
|
|
Secret = '*'
|
|
|
|
# Outer takes the first and last character displaying them with
|
|
# 3 dots between. Hence, 'i-am-a-token' would become 'i...n'
|
|
Outer = 'o'
|
|
|
|
# Displays the last four characters
|
|
Tail = 't'
|
|
|
|
|
|
# Define the HTML Lookup Table
|
|
HTML_LOOKUP = {
|
|
400: 'Bad Request - Unsupported Parameters.',
|
|
401: 'Verification Failed.',
|
|
404: 'Page not found.',
|
|
405: 'Method not allowed.',
|
|
500: 'Internal server error.',
|
|
503: 'Servers are overloaded.',
|
|
}
|
|
|
|
|
|
class URLBase:
|
|
"""
|
|
This is the base class for all URL Manipulation
|
|
"""
|
|
|
|
# The default descriptive name associated with the URL
|
|
service_name = None
|
|
|
|
# The default simple (insecure) protocol
|
|
# all inheriting entries must provide their protocol lookup
|
|
# protocol:// (in this example they would specify '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 = None
|
|
|
|
# Throttle
|
|
request_rate_per_sec = 0
|
|
|
|
# The connect timeout is the number of seconds Requests will wait for your
|
|
# client to establish a connection to a remote machine (corresponding to
|
|
# the connect()) call on the socket.
|
|
socket_connect_timeout = 4.0
|
|
|
|
# The read timeout is the number of seconds the client will wait for the
|
|
# server to send a response.
|
|
socket_read_timeout = 4.0
|
|
|
|
# Handle
|
|
# Maintain a set of tags to associate with this specific notification
|
|
tags = set()
|
|
|
|
# Secure sites should be verified against a Certificate Authority
|
|
verify_certificate = True
|
|
|
|
# Logging to our global logger
|
|
logger = logger
|
|
|
|
# Define a default set of template arguments used for dynamically building
|
|
# details about our individual plugins for developers.
|
|
|
|
# Define object templates
|
|
templates = ()
|
|
|
|
# Provides a mapping of tokens, certain entries are fixed and automatically
|
|
# configured if found (such as schema, host, user, pass, and port)
|
|
template_tokens = {}
|
|
|
|
# Here is where we define all of the arguments we accept on the url
|
|
# such as: schema://whatever/?cto=5.0&rto=15
|
|
# These act the same way as tokens except they are optional and/or
|
|
# have default values set if mandatory. This rule must be followed
|
|
template_args = {
|
|
'verify': {
|
|
'name': _('Verify SSL'),
|
|
# SSL Certificate Authority Verification
|
|
'type': 'bool',
|
|
# Provide a default
|
|
'default': verify_certificate,
|
|
# look up default using the following parent class value at
|
|
# runtime.
|
|
'_lookup_default': 'verify_certificate',
|
|
},
|
|
'rto': {
|
|
'name': _('Socket Read Timeout'),
|
|
'type': 'float',
|
|
# Provide a default
|
|
'default': socket_read_timeout,
|
|
# look up default using the following parent class value at
|
|
# runtime. The variable name identified here (in this case
|
|
# socket_read_timeout) is checked and it's result is placed
|
|
# over-top of the 'default'. This is done because once a parent
|
|
# class inherits this one, the overflow_mode already set as a
|
|
# default 'could' be potentially over-ridden and changed to a
|
|
# different value.
|
|
'_lookup_default': 'socket_read_timeout',
|
|
},
|
|
'cto': {
|
|
'name': _('Socket Connect Timeout'),
|
|
'type': 'float',
|
|
# Provide a default
|
|
'default': socket_connect_timeout,
|
|
# look up default using the following parent class value at
|
|
# runtime. The variable name identified here (in this case
|
|
# socket_connect_timeout) is checked and it's result is placed
|
|
# over-top of the 'default'. This is done because once a parent
|
|
# class inherits this one, the overflow_mode already set as a
|
|
# default 'could' be potentially over-ridden and changed to a
|
|
# different value.
|
|
'_lookup_default': 'socket_connect_timeout',
|
|
},
|
|
}
|
|
|
|
# kwargs are dynamically built because a prefix causes us to parse the
|
|
# content slightly differently. The prefix is required and can be either
|
|
# a (+ or -). Below would handle the +key=value:
|
|
# {
|
|
# 'headers': {
|
|
# 'name': _('HTTP Header'),
|
|
# 'prefix': '+',
|
|
# 'type': 'string',
|
|
# },
|
|
# },
|
|
#
|
|
# In a kwarg situation, the 'key' is always presumed to be treated as
|
|
# a string. When the 'type' is defined, it is being defined to respect
|
|
# the 'value'.
|
|
|
|
template_kwargs = {}
|
|
|
|
def __init__(self, asset=None, **kwargs):
|
|
"""
|
|
Initialize some general logging and common server arguments that will
|
|
keep things consistent when working with the children that
|
|
inherit this class.
|
|
|
|
"""
|
|
# Prepare our Asset Object
|
|
self.asset = \
|
|
asset if isinstance(asset, AppriseAsset) else AppriseAsset()
|
|
|
|
# Certificate Verification (for SSL calls); default to being enabled
|
|
self.verify_certificate = parse_bool(kwargs.get('verify', True))
|
|
|
|
# Secure Mode
|
|
self.secure = kwargs.get('secure', None)
|
|
try:
|
|
if not isinstance(self.secure, bool):
|
|
# Attempt to detect
|
|
self.secure = kwargs.get('schema', '')[-1].lower() == 's'
|
|
|
|
except (TypeError, IndexError):
|
|
self.secure = False
|
|
|
|
self.host = URLBase.unquote(kwargs.get('host'))
|
|
self.port = kwargs.get('port')
|
|
if self.port:
|
|
try:
|
|
self.port = int(self.port)
|
|
|
|
except (TypeError, ValueError):
|
|
self.logger.warning(
|
|
'Invalid port number specified {}'
|
|
.format(self.port))
|
|
self.port = None
|
|
|
|
self.user = kwargs.get('user')
|
|
if self.user:
|
|
# Always unquote user if it exists
|
|
self.user = URLBase.unquote(self.user)
|
|
|
|
self.password = kwargs.get('password')
|
|
if self.password:
|
|
# Always unquote the password if it exists
|
|
self.password = URLBase.unquote(self.password)
|
|
|
|
# Store our full path consistently ensuring it ends with a `/'
|
|
self.fullpath = URLBase.unquote(kwargs.get('fullpath'))
|
|
if not isinstance(self.fullpath, str) or not self.fullpath:
|
|
self.fullpath = '/'
|
|
|
|
# Store our Timeout Variables
|
|
if 'rto' in kwargs:
|
|
try:
|
|
self.socket_read_timeout = float(kwargs.get('rto'))
|
|
except (TypeError, ValueError):
|
|
self.logger.warning(
|
|
'Invalid socket read timeout (rto) was specified {}'
|
|
.format(kwargs.get('rto')))
|
|
|
|
if 'cto' in kwargs:
|
|
try:
|
|
self.socket_connect_timeout = float(kwargs.get('cto'))
|
|
|
|
except (TypeError, ValueError):
|
|
self.logger.warning(
|
|
'Invalid socket connect timeout (cto) was specified {}'
|
|
.format(kwargs.get('cto')))
|
|
|
|
if 'tag' in kwargs:
|
|
# We want to associate some tags with our notification service.
|
|
# the code below gets the 'tag' argument if defined, otherwise
|
|
# it just falls back to whatever was already defined globally
|
|
self.tags = set(parse_list(kwargs.get('tag'), self.tags))
|
|
|
|
# Tracks the time any i/o was made to the remote server. This value
|
|
# is automatically set and controlled through the throttle() call.
|
|
self._last_io_datetime = None
|
|
|
|
def throttle(self, last_io=None, wait=None):
|
|
"""
|
|
A common throttle control
|
|
|
|
if a wait is specified, then it will force a sleep of the
|
|
specified time if it is larger then the calculated throttle
|
|
time.
|
|
"""
|
|
|
|
if last_io is not None:
|
|
# Assume specified last_io
|
|
self._last_io_datetime = last_io
|
|
|
|
# Get ourselves a reference time of 'now'
|
|
reference = datetime.now()
|
|
|
|
if self._last_io_datetime is None:
|
|
# Set time to 'now' and no need to throttle
|
|
self._last_io_datetime = reference
|
|
return
|
|
|
|
if self.request_rate_per_sec <= 0.0 and not wait:
|
|
# We're done if there is no throttle limit set
|
|
return
|
|
|
|
# If we reach here, we need to do additional logic.
|
|
# If the difference between the reference time and 'now' is less than
|
|
# the defined request_rate_per_sec then we need to throttle for the
|
|
# remaining balance of this time.
|
|
|
|
elapsed = (reference - self._last_io_datetime).total_seconds()
|
|
|
|
if wait is not None:
|
|
self.logger.debug('Throttling forced for {}s...'.format(wait))
|
|
sleep(wait)
|
|
|
|
elif elapsed < self.request_rate_per_sec:
|
|
self.logger.debug('Throttling for {}s...'.format(
|
|
self.request_rate_per_sec - elapsed))
|
|
sleep(self.request_rate_per_sec - elapsed)
|
|
|
|
# Update our timestamp before we leave
|
|
self._last_io_datetime = datetime.now()
|
|
return
|
|
|
|
def url(self, privacy=False, *args, **kwargs):
|
|
"""
|
|
Assembles the URL associated with the notification based on the
|
|
arguments provied.
|
|
|
|
"""
|
|
|
|
# Our default parameters
|
|
params = self.url_parameters(privacy=privacy, *args, **kwargs)
|
|
|
|
# Determine Authentication
|
|
auth = ''
|
|
if self.user and self.password:
|
|
auth = '{user}:{password}@'.format(
|
|
user=URLBase.quote(self.user, safe=''),
|
|
password=self.pprint(
|
|
self.password, privacy, mode=PrivacyMode.Secret, safe=''),
|
|
)
|
|
elif self.user:
|
|
auth = '{user}@'.format(
|
|
user=URLBase.quote(self.user, safe=''),
|
|
)
|
|
|
|
default_port = 443 if self.secure else 80
|
|
|
|
return '{schema}://{auth}{hostname}{port}{fullpath}?{params}'.format(
|
|
schema='https' if self.secure else 'http',
|
|
auth=auth,
|
|
# never encode hostname since we're expecting it to be a valid one
|
|
hostname=self.host,
|
|
port='' if self.port is None or self.port == default_port
|
|
else ':{}'.format(self.port),
|
|
fullpath=URLBase.quote(self.fullpath, safe='/')
|
|
if self.fullpath else '/',
|
|
params=URLBase.urlencode(params),
|
|
)
|
|
|
|
def __contains__(self, tags):
|
|
"""
|
|
Returns true if the tag specified is associated with this notification.
|
|
|
|
tag can also be a tuple, set, and/or list
|
|
|
|
"""
|
|
if isinstance(tags, (tuple, set, list)):
|
|
return bool(set(tags) & self.tags)
|
|
|
|
# return any match
|
|
return tags in self.tags
|
|
|
|
def __str__(self):
|
|
"""
|
|
Returns the url path
|
|
"""
|
|
return self.url(privacy=True)
|
|
|
|
@staticmethod
|
|
def escape_html(html, convert_new_lines=False, whitespace=True):
|
|
"""
|
|
Takes html text as input and escapes it so that it won't
|
|
conflict with any xml/html wrapping characters.
|
|
|
|
Args:
|
|
html (str): The HTML code to escape
|
|
convert_new_lines (:obj:`bool`, optional): escape new lines (\n)
|
|
whitespace (:obj:`bool`, optional): escape whitespace
|
|
|
|
Returns:
|
|
str: The escaped html
|
|
"""
|
|
if not isinstance(html, str) or not html:
|
|
return ''
|
|
|
|
# Escape HTML
|
|
escaped = sax_escape(html, {"'": "'", "\"": """})
|
|
|
|
if whitespace:
|
|
# Tidy up whitespace too
|
|
escaped = escaped\
|
|
.replace(u'\t', u' ')\
|
|
.replace(u' ', u' ')
|
|
|
|
if convert_new_lines:
|
|
return escaped.replace(u'\n', u'<br/>')
|
|
|
|
return escaped
|
|
|
|
@staticmethod
|
|
def unquote(content, encoding='utf-8', errors='replace'):
|
|
"""
|
|
Replace %xx escapes by their single-character equivalent. The optional
|
|
encoding and errors parameters specify how to decode percent-encoded
|
|
sequences.
|
|
|
|
Wrapper to Python's `unquote` while remaining compatible with both
|
|
Python 2 & 3 since the reference to this function changed between
|
|
versions.
|
|
|
|
Note: errors set to 'replace' means that invalid sequences are
|
|
replaced by a placeholder character.
|
|
|
|
Args:
|
|
content (str): The quoted URI string you wish to unquote
|
|
encoding (:obj:`str`, optional): encoding type
|
|
errors (:obj:`str`, errors): how to handle invalid character found
|
|
in encoded string (defined by encoding)
|
|
|
|
Returns:
|
|
str: The unquoted URI string
|
|
"""
|
|
if not content:
|
|
return ''
|
|
|
|
return _unquote(content, encoding=encoding, errors=errors)
|
|
|
|
@staticmethod
|
|
def quote(content, safe='/', encoding=None, errors=None):
|
|
""" Replaces single character non-ascii characters and URI specific
|
|
ones by their %xx code.
|
|
|
|
Wrapper to Python's `quote` while remaining compatible with both
|
|
Python 2 & 3 since the reference to this function changed between
|
|
versions.
|
|
|
|
Args:
|
|
content (str): The URI string you wish to quote
|
|
safe (str): non-ascii characters and URI specific ones that you
|
|
do not wish to escape (if detected). Setting this
|
|
string to an empty one causes everything to be
|
|
escaped.
|
|
encoding (:obj:`str`, optional): encoding type
|
|
errors (:obj:`str`, errors): how to handle invalid character found
|
|
in encoded string (defined by encoding)
|
|
|
|
Returns:
|
|
str: The quoted URI string
|
|
"""
|
|
if not content:
|
|
return ''
|
|
|
|
return _quote(content, safe=safe, encoding=encoding, errors=errors)
|
|
|
|
@staticmethod
|
|
def pprint(content, privacy=True, mode=PrivacyMode.Outer,
|
|
# privacy print; quoting is ignored when privacy is set to True
|
|
quote=True, safe='/', encoding=None, errors=None):
|
|
"""
|
|
Privacy Print is used to mainpulate the string before passing it into
|
|
part of the URL. It is used to mask/hide private details such as
|
|
tokens, passwords, apikeys, etc from on-lookers. If the privacy=False
|
|
is set, then the quote variable is the next flag checked.
|
|
|
|
Quoting is never done if the privacy flag is set to true to avoid
|
|
skewing the expected output.
|
|
"""
|
|
|
|
if not privacy:
|
|
if quote:
|
|
# Return quoted string if specified to do so
|
|
return URLBase.quote(
|
|
content, safe=safe, encoding=encoding, errors=errors)
|
|
|
|
# Return content 'as-is'
|
|
return content
|
|
|
|
if mode is PrivacyMode.Secret:
|
|
# Return 4 Asterisks
|
|
return '****'
|
|
|
|
if not isinstance(content, str) or not content:
|
|
# Nothing more to do
|
|
return ''
|
|
|
|
if mode is PrivacyMode.Tail:
|
|
# Return the trailing 4 characters
|
|
return '...{}'.format(content[-4:])
|
|
|
|
# Default mode is Outer Mode
|
|
return '{}...{}'.format(content[0:1], content[-1:])
|
|
|
|
@staticmethod
|
|
def urlencode(query, doseq=False, safe='', encoding=None, errors=None):
|
|
"""Convert a mapping object or a sequence of two-element tuples
|
|
|
|
Wrapper to Python's `urlencode` while remaining compatible with both
|
|
Python 2 & 3 since the reference to this function changed between
|
|
versions.
|
|
|
|
The resulting string is a series of key=value pairs separated by '&'
|
|
characters, where both key and value are quoted using the quote()
|
|
function.
|
|
|
|
Note: If the dictionary entry contains an entry that is set to None
|
|
it is not included in the final result set. If you want to
|
|
pass in an empty variable, set it to an empty string.
|
|
|
|
Args:
|
|
query (str): The dictionary to encode
|
|
doseq (:obj:`bool`, optional): Handle sequences
|
|
safe (:obj:`str`): non-ascii characters and URI specific ones that
|
|
you do not wish to escape (if detected). Setting this string
|
|
to an empty one causes everything to be escaped.
|
|
encoding (:obj:`str`, optional): encoding type
|
|
errors (:obj:`str`, errors): how to handle invalid character found
|
|
in encoded string (defined by encoding)
|
|
|
|
Returns:
|
|
str: The escaped parameters returned as a string
|
|
"""
|
|
return urlencode(
|
|
query, doseq=doseq, safe=safe, encoding=encoding, errors=errors)
|
|
|
|
@staticmethod
|
|
def split_path(path, unquote=True):
|
|
"""Splits a URL up into a list object.
|
|
|
|
Parses a specified URL and breaks it into a list.
|
|
|
|
Args:
|
|
path (str): The path to split up into a list.
|
|
unquote (:obj:`bool`, optional): call unquote on each element
|
|
added to the returned list.
|
|
|
|
Returns:
|
|
list: A list containing all of the elements in the path
|
|
"""
|
|
|
|
try:
|
|
paths = PATHSPLIT_LIST_DELIM.split(path.lstrip('/'))
|
|
if unquote:
|
|
paths = \
|
|
[URLBase.unquote(x) for x in filter(bool, paths)]
|
|
|
|
except AttributeError:
|
|
# path is not useable, we still want to gracefully return an
|
|
# empty list
|
|
paths = []
|
|
|
|
return paths
|
|
|
|
@staticmethod
|
|
def parse_list(content, unquote=True):
|
|
"""A wrapper to utils.parse_list() with unquoting support
|
|
|
|
Parses a specified set of data and breaks it into a list.
|
|
|
|
Args:
|
|
content (str): The path to split up into a list. If a list is
|
|
provided, then it's individual entries are processed.
|
|
|
|
unquote (:obj:`bool`, optional): call unquote on each element
|
|
added to the returned list.
|
|
|
|
Returns:
|
|
list: A unique list containing all of the elements in the path
|
|
"""
|
|
|
|
content = parse_list(content)
|
|
if unquote:
|
|
content = \
|
|
[URLBase.unquote(x) for x in filter(bool, content)]
|
|
|
|
return content
|
|
|
|
@staticmethod
|
|
def parse_phone_no(content, unquote=True):
|
|
"""A wrapper to utils.parse_phone_no() with unquoting support
|
|
|
|
Parses a specified set of data and breaks it into a list.
|
|
|
|
Args:
|
|
content (str): The path to split up into a list. If a list is
|
|
provided, then it's individual entries are processed.
|
|
|
|
unquote (:obj:`bool`, optional): call unquote on each element
|
|
added to the returned list.
|
|
|
|
Returns:
|
|
list: A unique list containing all of the elements in the path
|
|
"""
|
|
|
|
if unquote:
|
|
try:
|
|
content = URLBase.unquote(content)
|
|
except TypeError:
|
|
# Nothing further to do
|
|
return []
|
|
|
|
content = parse_phone_no(content)
|
|
|
|
return content
|
|
|
|
@property
|
|
def app_id(self):
|
|
return self.asset.app_id if self.asset.app_id else ''
|
|
|
|
@property
|
|
def app_desc(self):
|
|
return self.asset.app_desc if self.asset.app_desc else ''
|
|
|
|
@property
|
|
def app_url(self):
|
|
return self.asset.app_url if self.asset.app_url else ''
|
|
|
|
@property
|
|
def request_timeout(self):
|
|
"""This is primarily used to fullfill the `timeout` keyword argument
|
|
that is used by requests.get() and requests.put() calls.
|
|
"""
|
|
return (self.socket_connect_timeout, self.socket_read_timeout)
|
|
|
|
@property
|
|
def request_auth(self):
|
|
"""This is primarily used to fullfill the `auth` keyword argument
|
|
that is used by requests.get() and requests.put() calls.
|
|
"""
|
|
return (self.user, self.password) if self.user else None
|
|
|
|
@property
|
|
def request_url(self):
|
|
"""
|
|
Assemble a simple URL that can be used by the requests library
|
|
|
|
"""
|
|
|
|
# Acquire our schema
|
|
schema = 'https' if self.secure else 'http'
|
|
|
|
# Prepare our URL
|
|
url = '%s://%s' % (schema, self.host)
|
|
|
|
# Apply Port information if present
|
|
if isinstance(self.port, int):
|
|
url += ':%d' % self.port
|
|
|
|
# Append our full path
|
|
return url + self.fullpath
|
|
|
|
def url_parameters(self, *args, **kwargs):
|
|
"""
|
|
Provides a default set of args to work with. This can greatly
|
|
simplify URL construction in the acommpanied url() function.
|
|
|
|
The following property returns a dictionary (of strings) containing
|
|
all of the parameters that can be set on a URL and managed through
|
|
this class.
|
|
"""
|
|
|
|
return {
|
|
# The socket read timeout
|
|
'rto': str(self.socket_read_timeout),
|
|
# The request/socket connect timeout
|
|
'cto': str(self.socket_connect_timeout),
|
|
# Certificate verification
|
|
'verify': 'yes' if self.verify_certificate else 'no',
|
|
}
|
|
|
|
@staticmethod
|
|
def parse_url(url, verify_host=True, plus_to_space=False,
|
|
strict_port=False):
|
|
"""Parses the URL and returns it broken apart into a dictionary.
|
|
|
|
This is very specific and customized for Apprise.
|
|
|
|
|
|
Args:
|
|
url (str): The URL you want to fully parse.
|
|
verify_host (:obj:`bool`, optional): a flag kept with the parsed
|
|
URL which some child classes will later use to verify SSL
|
|
keys (if SSL transactions take place). Unless under very
|
|
specific circumstances, it is strongly recomended that
|
|
you leave this default value set to True.
|
|
|
|
Returns:
|
|
A dictionary is returned containing the URL fully parsed if
|
|
successful, otherwise None is returned.
|
|
"""
|
|
|
|
results = parse_url(
|
|
url, default_schema='unknown', verify_host=verify_host,
|
|
plus_to_space=plus_to_space, strict_port=strict_port)
|
|
|
|
if not results:
|
|
# We're done; we failed to parse our url
|
|
return results
|
|
|
|
# if our URL ends with an 's', then assume our secure flag is set.
|
|
results['secure'] = (results['schema'][-1] == 's')
|
|
|
|
# Support SSL Certificate 'verify' keyword. Default to being enabled
|
|
results['verify'] = True
|
|
|
|
if 'verify' in results['qsd']:
|
|
results['verify'] = parse_bool(
|
|
results['qsd'].get('verify', True))
|
|
|
|
# Password overrides
|
|
if 'password' in results['qsd']:
|
|
results['password'] = results['qsd']['password']
|
|
if 'pass' in results['qsd']:
|
|
results['password'] = results['qsd']['pass']
|
|
|
|
# User overrides
|
|
if 'user' in results['qsd']:
|
|
results['user'] = results['qsd']['user']
|
|
|
|
# parse_url() always creates a 'password' and 'user' entry in the
|
|
# results returned. Entries are set to None if they weren't specified
|
|
if results['password'] is None and 'user' in results['qsd']:
|
|
# Handle cases where the user= provided in 2 locations, we want
|
|
# the original to fall back as a being a password (if one wasn't
|
|
# otherwise defined)
|
|
# e.g.
|
|
# mailtos://PASSWORD@hostname?user=admin@mail-domain.com
|
|
# - the PASSWORD gets lost in the parse url() since a user=
|
|
# over-ride is specified.
|
|
presults = parse_url(results['url'])
|
|
if presults:
|
|
# Store our Password
|
|
results['password'] = presults['user']
|
|
|
|
# Store our socket read timeout if specified
|
|
if 'rto' in results['qsd']:
|
|
results['rto'] = results['qsd']['rto']
|
|
|
|
# Store our socket connect timeout if specified
|
|
if 'cto' in results['qsd']:
|
|
results['cto'] = results['qsd']['cto']
|
|
|
|
if 'port' in results['qsd']:
|
|
results['port'] = results['qsd']['port']
|
|
|
|
return results
|
|
|
|
@staticmethod
|
|
def http_response_code_lookup(code, response_mask=None):
|
|
"""Parses the interger response code returned by a remote call from
|
|
a web request into it's human readable string version.
|
|
|
|
You can over-ride codes or add new ones by providing your own
|
|
response_mask that contains a dictionary of integer -> string mapped
|
|
variables
|
|
"""
|
|
if isinstance(response_mask, dict):
|
|
# Apply any/all header over-rides defined
|
|
HTML_LOOKUP.update(response_mask)
|
|
|
|
# Look up our response
|
|
try:
|
|
response = HTML_LOOKUP[code]
|
|
|
|
except KeyError:
|
|
response = ''
|
|
|
|
return response
|
|
|
|
def __len__(self):
|
|
"""
|
|
Should be over-ridden and allows the tracking of how many targets
|
|
are associated with each URLBase object.
|
|
|
|
Default is always 1
|
|
"""
|
|
return 1
|
|
|
|
def schemas(self):
|
|
"""A simple function that returns a set of all schemas associated
|
|
with this object based on the object.protocol and
|
|
object.secure_protocol
|
|
"""
|
|
|
|
schemas = set([])
|
|
|
|
for key in ('protocol', 'secure_protocol'):
|
|
schema = getattr(self, key, None)
|
|
if isinstance(schema, str):
|
|
schemas.add(schema)
|
|
|
|
elif isinstance(schema, (set, list, tuple)):
|
|
# Support iterables list types
|
|
for s in schema:
|
|
if isinstance(s, str):
|
|
schemas.add(s)
|
|
|
|
return schemas
|