salespyforce 1.4.0.dev0__py3-none-any.whl

salespyforce/utils/core_utils.py

@@ -0,0 +1,152 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            salespyforce.utils.core_utils
+:Synopsis:          Collection of supporting utilities and functions to complement the primary modules
+:Usage:             ``from salespyforce.utils import core_utils``
+:Example:           ``encoded_string = core_utils.encode_url(decoded_string)``
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff
+:Modified Date:     29 May 2023
+"""
+
+import random
+import string
+import os.path
+import warnings
+import urllib.parse
+
+import requests
+
+from . import log_utils
+from .. import errors
+
+# Initialize the logger for this module
+logger = log_utils.initialize_logging(__name__)
+
+
+def url_encode(raw_string):
+    """This function encodes a string for use in URLs.
+
+    :param raw_string: The raw string to be encoded
+    :type raw_string: str
+    :returns: The encoded string
+    """
+    return urllib.parse.quote_plus(raw_string)
+
+
+def url_decode(encoded_string):
+    """This function decodes a url-encoded string.
+
+    :param encoded_string: The url-encoded string
+    :type encoded_string: str
+    :returns: The unencoded string
+    """
+    return urllib.parse.unquote_plus(encoded_string)
+
+
+def display_warning(warn_msg):
+    """This function displays a :py:exc:`UserWarning` message via the :py:mod:`warnings` module.
+
+    :param warn_msg: The message to be displayed
+    :type warn_msg: str
+    :returns: None
+    """
+    warnings.warn(warn_msg, UserWarning)
+
+
+def get_file_type(file_path):
+    """This function attempts to identify if a given file path is for a YAML or JSON file.
+
+    :param file_path: The full path to the file
+    :type file_path: str
+    :returns: The file type in string format (e.g. ``yaml`` or ``json``)
+    :raises: :py:exc:`FileNotFoundError`, :py:exc:`khoros.errors.exceptions.UnknownFileTypeError`
+    """
+    file_type = 'unknown'
+    if os.path.isfile(file_path):
+        if file_path.endswith('.json'):
+            file_type = 'json'
+        elif file_path.endswith('.yml') or file_path.endswith('.yaml'):
+            file_type = 'yaml'
+        else:
+            display_warning(f"Unable to recognize the file type of '{file_path}' by its extension.")
+            with open(file_path) as cfg_file:
+                for line in cfg_file:
+                    if line.startswith('#'):
+                        continue
+                    else:
+                        if '{' in line:
+                            file_type = 'json'
+                            break
+        if file_type == 'unknown':
+            raise errors.exceptions.UnknownFileTypeError(file=file_path)
+    else:
+        raise FileNotFoundError(f"Unable to locate the following file: {file_path}")
+    return file_type
+
+
+def get_random_string(length=32, prefix_string=""):
+    """This function returns a random alphanumeric string.
+
+    :param length: The length of the string (``32`` by default)
+    :type length: int
+    :param prefix_string: A string to which the random string should be appended (optional)
+    :type prefix_string: str
+    :returns: The alphanumeric string
+    """
+    return f"{prefix_string}{''.join([random.choice(string.ascii_letters + string.digits) for _ in range(length)])}"
+
+
+def get_image_ref_id(image_url):
+    """This function parses an image URL to identify the reference ID (refid) value.
+    (`Reference 1 <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_sobject_rich_text_image_retrieve.htm>`_,
+    `Reference 2 <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_rich_text_image_retrieve.htm>`_)
+
+    :param image_url: The URL of an image from within Salesforce
+    :type image_url: str
+    :returns: The reference ID (``refid``) value
+    """
+    query_params = urllib.parse.parse_qs(urllib.parse.urlparse(image_url).query)
+    # noinspection PyTypeChecker
+    ref_id = query_params.get('refid')
+    ref_id = ref_id[0] if not isinstance(ref_id, str) else ref_id
+    return ref_id
+
+
+def download_image(image_url=None, file_name=None, file_path=None, response=None, extension='jpeg'):
+    """This function downloads an image and saves it to a specified directory.
+
+    :param image_url: The absolute URL to the image
+    :type image_url: str
+    :param file_name: The file name including extension as which to save the file
+    :type file_name: str
+    :param file_path: File path where the image file should be saved (default: ``var/images/``)
+    :type file_path: str, None
+    :param response: The response of the previously performed API call
+    :param extension: The file extension to use if a file name with extension is not provided
+    :type extension: str
+    :returns: The full path to the downloaded image
+    :raises: :py:exc:`RuntimeError`
+    """
+    if not image_url and not response:
+        raise RuntimeError('An image URL or an API response must be provided to download an image.')
+
+    # Define an appropriate file path
+    file_path = './' if not file_path else file_path
+    file_path = f'{file_path}/' if not any((file_path.endswith('/'), file_path.endswith('\\'))) else file_path
+
+    # Define a file name if not provided
+    if not file_name:
+        file_name = get_random_string(10, 'image_')
+        file_name += extension
+
+    # Perform the API call if not supplied
+    if not response:
+        response = requests.get(image_url)
+    if response.status_code != 200:
+        raise RuntimeError(f'The image failed to download with a {response.status_code} status code.')
+
+    # Export the response data as an image file
+    with open(f'{file_path}{file_name}', 'wb') as file:
+        file.write(response.content)
+    return f'{file_path}{file_name}'

salespyforce/utils/helper.py

@@ -0,0 +1,140 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            salespyforce.utils.helper
+:Synopsis:          Module that allows the salespyforce library to leverage a helper configuration file
+:Usage:             ``from salespyforce.utils import helper``
+:Example:           ``helper_settings = helper.get_settings('/tmp/helper.yml', 'yaml')``
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff
+:Modified Date:     13 Mar 2023
+"""
+
+import json
+
+import yaml
+
+from .. import errors
+from . import log_utils
+from .core_utils import get_file_type
+
+# Initialize logging within the module
+logger = log_utils.initialize_logging(__name__)
+
+
+def import_helper_file(file_path, file_type):
+    """This function imports a YAML (.yml) or JSON (.json) helper config file.
+
+    :param file_path: The file path to the YAML file
+    :type file_path: str
+    :param file_type: Defines the file type as either ``yaml`` or ``json``
+    :type file_type: str
+    :returns: The parsed configuration data
+    :raises: :py:exc:`FileNotFoundError`, :py:exc:`salespyforce.errors.exceptions.InvalidHelperFileTypeError`
+    """
+    with open(file_path, 'r') as cfg_file:
+        if file_type == 'yaml':
+            helper_cfg = yaml.safe_load(cfg_file)
+        elif file_type == 'json':
+            helper_cfg = json.load(cfg_file)
+        else:
+            raise errors.exceptions.InvalidHelperFileTypeError()
+    logger.info(f'The helper file {file_path} was imported successfully.')
+    return helper_cfg
+
+
+def _convert_yaml_to_bool(_yaml_bool_value):
+    """This function converts the 'yes' and 'no' YAML values to traditional Boolean values."""
+    _true_values = ['yes', 'true']
+    if _yaml_bool_value.lower() in _true_values:
+        _bool_value = True
+    else:
+        _bool_value = False
+    return _bool_value
+
+
+def _get_connection_info(_helper_cfg):
+    """This function parses any connection information found in the helper file."""
+    _connection_info = {}
+    _connection_keys = ['username', 'password', 'base_url', 'endpoint_url',
+                        'client_key', 'client_secret', 'org_id', 'security_token']
+    for _key in _connection_keys:
+        if _key in _helper_cfg['connection']:
+            _connection_info[_key] = _helper_cfg['connection'][_key]
+    return _connection_info
+
+
+def _collect_values(_top_level_keys, _helper_cfg, _helper_dict=None, _ignore_missing=False):
+    """This function loops through a list of top-level keys to collect their corresponding values.
+
+    :param _top_level_keys: One or more top-level keys that might be found in the helper config file
+    :type _top_level_keys: list, tuple, set, str
+    :param _helper_cfg: The configuration parsed from the helper configuration file
+    :type _helper_cfg: dict
+    :param _helper_dict: A predefined dictionary to which the key value pairs should be added
+    :type _helper_dict: dict, None
+    :param _ignore_missing: Indicates whether fields with null values should be ignored (``False`` by default)
+    :type _ignore_missing: bool
+    :returns: A dictionary with the identified key value pairs
+    """
+    _helper_dict = {} if not _helper_dict else _helper_dict
+    _top_level_keys = (_top_level_keys, ) if isinstance(_top_level_keys, str) else _top_level_keys
+    for _key in _top_level_keys:
+        if _key in _helper_cfg:
+            _key_val = _helper_cfg[_key]
+            if _key_val in HelperParsing.yaml_boolean_values:
+                _key_val = HelperParsing.yaml_boolean_values.get(_key_val)
+            _helper_dict[_key] = _key_val
+        elif _key == "ssl_verify":
+            # Verify SSL certificates by default unless explicitly set to false
+            _helper_dict[_key] = True
+        else:
+            if not _ignore_missing:
+                _helper_dict[_key] = None
+    return _helper_dict
+
+
+def get_helper_settings(file_path, file_type='yaml', defined_settings=None):
+    """This function returns a dictionary of the defined helper settings.
+
+    :param file_path: The file path to the helper configuration file
+    :type file_path: str
+    :param file_type: Defines the helper configuration file as a ``yaml`` file (default) or a ``json`` file
+    :type file_type: str
+    :param defined_settings: Core object settings (if any) defined via the ``defined_settings`` parameter
+    :type defined_settings: dict, None
+    :returns: Dictionary of helper variables
+    :raises: :py:exc:`salespyforce.errors.exceptions.InvalidHelperFileTypeError`
+    """
+    # Initialize the helper_settings dictionary
+    helper_settings = {}
+
+    # Convert the defined_settings parameter to an empty dictionary if null
+    defined_settings = {} if not defined_settings else defined_settings
+
+    if file_type != 'yaml' and file_type != 'json':
+        file_type = get_file_type(file_path)
+
+    # Import the helper configuration file
+    helper_cfg = import_helper_file(file_path, file_type)
+
+    # Populate the connection information in the helper dictionary
+    if 'connection' in helper_cfg and 'connection' not in defined_settings:
+        helper_settings['connection'] = _get_connection_info(helper_cfg)
+
+    # Populate the SSL certificate verification setting in the helper dictionary
+    if 'ssl_verify' not in defined_settings:
+        helper_settings.update(_collect_values('ssl_verify', helper_cfg))
+
+    # Return the helper_settings dictionary
+    return helper_settings
+
+
+class HelperParsing:
+    """This class is used to help parse values imported from a YAML configuration file."""
+    # Define dictionary to map YAML Boolean to Python Boolean
+    yaml_boolean_values = {
+        True: True,
+        False: False,
+        'yes': True,
+        'no': False
+    }

salespyforce/utils/log_utils.py

@@ -0,0 +1,264 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            salespyforce.utils.log_utils
+:Synopsis:          Collection of logging utilities and functions
+:Usage:             ``from salespyforce.utils import log_utils``
+:Example:           ``logger = log_utils.initialize_logging(__name__)``
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff
+:Modified Date:     22 Jan 2023
+"""
+
+import os
+import sys
+import logging
+import logging.handlers
+from pathlib import Path
+
+LOGGING_DEFAULTS = {
+    'logger_name': __name__,
+    'log_level': 'info',
+    'formatter': logging.Formatter('%(asctime)s - %(levelname)s - %(name)s - %(message)s'),
+    'date_format': '%Y-%m-%d %I:%M:%S',
+}
+HANDLER_DEFAULTS = {
+    'file_log_level': 'info',
+    'console_log_level': 'warning',
+    'syslog_log_level': 'info',
+    'syslog_address': 'localhost',
+    'syslog_port': 514,
+}
+
+
+def initialize_logging(logger_name=None, log_level=None, formatter=None, debug=None, no_output=None, file_output=None,
+                       file_log_level=None, log_file=None, overwrite_log_files=None, console_output=None,
+                       console_log_level=None, syslog_output=None, syslog_log_level=None, syslog_address=None,
+                       syslog_port=None):
+    """This function initializes logging for the salespyforce library."""
+    # TODO: Complete the docstring above with parameters
+    logger_name, log_levels, formatter = _apply_defaults(logger_name, formatter, debug, log_level, file_log_level,
+                                                         console_log_level, syslog_log_level)
+    log_level, file_log_level, console_log_level, syslog_log_level = _get_log_levels_from_dict(log_levels)
+    logger = logging.getLogger(logger_name)
+    logger = _set_logging_level(logger, log_level)
+    logger = _add_handlers(logger, formatter, no_output, file_output, file_log_level, log_file, overwrite_log_files,
+                           console_output, console_log_level, syslog_output, syslog_log_level, syslog_address,
+                           syslog_port)
+    return logger
+
+
+class LessThanFilter(logging.Filter):
+    """This class allows filters to be set to limit log levels to only less than a specified level.
+
+    .. seealso:: `Zoey Greer <https://stackoverflow.com/users/5124424/zoey-greer>`_ is the original author of
+                 this class which was provided on `Stack Overflow <https://stackoverflow.com/a/31459386>`_.
+    """
+    def __init__(self, exclusive_maximum, name=""):
+        """This method instantiates the :py:class:`salespyforce.utils.log_utils.LessThanFilter` class object."""
+        super(LessThanFilter, self).__init__(name)
+        self.max_level = exclusive_maximum
+
+    def filter(self, record):
+        """This method returns a Boolean integer value indicating whether or not a message should be logged.
+
+        .. note:: A non-zero return indicates that the message will be logged.
+        """
+        return 1 if record.levelno < self.max_level else 0
+
+
+def _apply_defaults(_logger_name, _formatter, _debug, _log_level, _file_level, _console_level, _syslog_level):
+    """This function applies default values to the configuration settings if not explicitly defined.
+
+    :param _logger_name: The name of the logger instance
+    :type _logger_name: str, None
+    :param _formatter: The log format to utilize for the logger instance
+    :type _formatter: str, None
+    :param _debug: Defines if debug mode is enabled
+    :type _debug: bool, None
+    :param _log_level: The general logging level for the logger instance
+    :type _log_level: str, None
+    :returns: The values that will be used for the configuration settings
+    """
+    _log_levels = {
+        'general': _log_level,
+        'file': _file_level,
+        'console': _console_level,
+        'syslog': _syslog_level,
+    }
+    _logger_name = LOGGING_DEFAULTS.get('logger_name') if not _logger_name else _logger_name
+    if _debug:
+        for _log_type in _log_levels:
+            _log_levels[_log_type] = 'debug'
+    else:
+        if _log_level:
+            for _lvl_type, _lvl_value in _log_levels.items():
+                if _lvl_type != 'general' and _lvl_value is None:
+                    _log_levels[_lvl_type] = _log_level
+        else:
+            _log_level = LOGGING_DEFAULTS.get('log_level')
+    if _formatter and isinstance(_formatter, str):
+        _formatter = logging.Formatter(_formatter)
+    _formatter = LOGGING_DEFAULTS.get('formatter') if not _formatter else _formatter
+    return _logger_name, _log_levels, _formatter
+
+
+def _get_log_levels_from_dict(_log_levels):
+    """This function returns the individual log level values from a dictionary.
+
+    :param _log_levels: Dictionary containing log levels for different handlers
+    :type _log_levels: dict
+    :returns: Individual string values for each handler
+    """
+    _general = _log_levels.get('general')
+    _file = _log_levels.get('file')
+    _console = _log_levels.get('console')
+    _syslog = _log_levels.get('syslog')
+    return _general, _file, _console, _syslog
+
+
+def _set_logging_level(_logger, _log_level):
+    """This function sets the logging level for a :py:class:`logging.Logger` instance.
+
+    :param _logger: The :py:class:`logging.Logger` instance
+    :type _logger: Logger
+    :param _log_level: The log level as a string (``debug``, ``info``, ``warning``, ``error`` or ``critical``)
+    :type _log_level: str
+    :returns: The :py:class:`logging.Logger` instance with a logging level set where applicable
+    """
+    if _log_level == 'debug':
+        _logger.setLevel(logging.DEBUG)
+    elif _log_level == 'info':
+        _logger.setLevel(logging.INFO)
+    elif _log_level == 'warning':
+        _logger.setLevel(logging.WARNING)
+    elif _log_level == 'error':
+        _logger.setLevel(logging.ERROR)
+    elif _log_level == 'critical':
+        _logger.setLevel(logging.CRITICAL)
+    return _logger
+
+
+def _add_handlers(_logger, _formatter, _no_output, _file_output, _file_log_level, _log_file, _overwrite_log_files,
+                  _console_output, _console_log_level, _syslog_output, _syslog_log_level, _syslog_address,
+                  _syslog_port):
+    # TODO: Add docstring
+    if _no_output or not any((_file_output, _console_output, _syslog_output)):
+        _logger.addHandler(logging.NullHandler())
+    else:
+        if _file_output:
+            # Add the FileHandler to the Logger object
+            _logger = _add_file_handler(_logger, _file_log_level, _log_file, _overwrite_log_files, _formatter)
+        if _console_output:
+            # Add the StreamHandler to the Logger object
+            _logger = _add_stream_handler(_logger, _console_log_level, _formatter)
+        if _syslog_output:
+            # Add the SyslogHandler to the Logger object
+            _logger = _add_syslog_handler(_logger, _syslog_log_level, _formatter, _syslog_address, _syslog_port)
+    return _logger
+
+
+def _add_file_handler(_logger, _log_level, _log_file, _overwrite, _formatter):
+    """This function adds a :py:class:`logging.FileHandler` to the :py:class:`logging.Logger` instance.
+
+    :param _logger: The :py:class:`logging.Logger` instance
+    :type _logger: Logger
+    :param _log_level: The log level to set for the handler
+    :type _log_level: str
+    :param _log_file: The log file (as a file name or a file path) to which messages should be written
+
+    .. note:: If a file path isn't provided then the default directory is the home directory of the user instantiating
+              the :py:class:`logging.Logger` object. If a file name is also no provided then it will default to
+              using ``salespyforce.log`` as the file name.
+
+    :param _overwrite: Determines if messages should be appended to the file (default) or overwrite it
+    :type _overwrite: bool
+    :param _formatter: The :py:class:`logging.Formatter` to apply to messages passed through the handler
+    :type _formatter: Formatter
+    :returns: The :py:class:`logging.Logger` instance with the added :py:class:`logging.FileHandler`
+    """
+    # Define the log file to use
+    _home_dir = str(Path.home())
+    if _log_file:
+        if not any((('/' in _log_file), ('\\' in _log_file))):
+            _log_file = os.path.join(_home_dir, _log_file)
+    else:
+        _log_file = os.path.join(_home_dir, 'salespyforce.log')
+
+    # Identify if log file should be overwritten
+    _write_mode = 'w' if _overwrite else 'a'
+
+    # Instantiate the handler
+    _handler = logging.FileHandler(_log_file, _write_mode)
+    _log_level = HANDLER_DEFAULTS.get('file_log_level') if not _log_level else _log_level
+    _handler = _set_logging_level(_handler, _log_level)
+    _handler.setFormatter(_formatter)
+
+    # Add the handler to the logger
+    _logger.addHandler(_handler)
+    return _logger
+
+
+def _add_stream_handler(_logger, _log_level, _formatter):
+    """This function adds a :py:class:`logging.StreamHandler` to the :py:class:`logging.Logger` instance.
+
+    :param _logger: The :py:class:`logging.Logger` instance
+    :type _logger: Logger
+    :param _log_level: The log level to set for the handler
+    :type _log_level: str
+    :param _formatter: The :py:class:`logging.Formatter` to apply to messages passed through the handler
+    :type _formatter: Formatter
+    :returns: The :py:class:`logging.Logger` instance with the added :py:class:`logging.StreamHandler`
+    """
+    _log_level = HANDLER_DEFAULTS.get('console_log_level') if not _log_level else _log_level
+    _stdout_levels = ['DEBUG', 'INFO']
+    if _log_level.upper() in _stdout_levels:
+        _logger = _add_split_stream_handlers(_logger, _log_level, _formatter)
+    else:
+        _handler = logging.StreamHandler()
+        _handler = _set_logging_level(_handler, _log_level)
+        _handler.setFormatter(_formatter)
+        _logger.addHandler(_handler)
+    return _logger
+
+
+def _add_split_stream_handlers(_logger, _log_level, _formatter):
+    """This function splits messages into q ``stdout`` or ``stderr`` handler depending on the log level.
+
+    .. seealso:: Refer to the documentation for the :py:class:`salespyforce.utils.log_utils.LessThanFilter` for
+                 more information on how this filtering is implemented and for credit to the original author.
+
+    :param _logger: The :py:class:`logging.Logger` instance
+    :type _logger: Logger
+    :param _log_level: The log level provided for the stream handler (i.e. console output)
+    :type _log_level: str
+    :param _formatter: The :py:class:`logging.Formatter` to apply to messages passed through the handlers
+    :type _formatter: Formatter
+    :returns: The logger instance with the two handlers added
+    """
+    # Configure and add the STDOUT handler
+    _stdout_handler = logging.StreamHandler(sys.stdout)
+    _stdout_handler = _set_logging_level(_stdout_handler, _log_level)
+    _stdout_handler.addFilter(LessThanFilter(logging.WARNING))
+    _stdout_handler.setFormatter(_formatter)
+    _logger.addHandler(_stdout_handler)
+
+    # Configure and add the STDERR handler
+    _stderr_handler = logging.StreamHandler(sys.stderr)
+    _stderr_handler.setLevel(logging.WARNING)
+    _stderr_handler.setFormatter(_formatter)
+    _logger.addHandler(_stderr_handler)
+
+    # Return the logger with the added handlers
+    return _logger
+
+
+def _add_syslog_handler(_logger, _log_level, _formatter, _address, _port):
+    # TODO: Add docstring
+    _log_level = HANDLER_DEFAULTS.get('syslog_log_level') if not _log_level else _log_level
+    _address = HANDLER_DEFAULTS.get('syslog_address') if not _address else _address
+    _port = HANDLER_DEFAULTS.get('syslog_port') if not _port else _port
+    _handler = logging.handlers.SysLogHandler(address=(_address, _port))
+    _handler = _set_logging_level(_handler, _log_level)
+    _handler.setFormatter(_formatter)
+    _logger.addHandler(_handler)
+    return _logger

salespyforce/utils/tests/__init__.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:         salespyforce.utils.tests
+:Synopsis:       This package includes tests for the salespyforce library.
+:Created By:     Jeff Shurtliff
+:Last Modified:  Jeff Shurtliff
+:Modified Date:  27 May 2023
+"""