Supporting Modules

This section provides details around the supporting modules used in the salespyforce package, which are listed below.


Classes & Exceptions

This section includes modules that contain the classes and exceptions used throughout the package.


Errors Module (salespyforce.errors)

This module contains all of the exception classes and error handling functions leveraged throughout the library.

Package:

salespyforce.errors

Synopsis:

This module includes custom exceptions and handlers

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

13 Mar 2023

Return to Top


Exceptions Module (salespyforce.errors.exceptions)

This sub-module defines custom exceptions that are leveraged throughout the library.

Module:

salespyforce.errors.exceptions

Synopsis:

Collection of exception classes relating to the SalesPyForce library

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

13 Mar 2023

exception salespyforce.errors.exceptions.APIConnectionError(*args, **kwargs)[source]

This exception is used when the API query could not be completed due to connection aborts and/or timeouts.

exception salespyforce.errors.exceptions.APIRequestError(*args, **kwargs)[source]

This exception is used for generic API request errors when there isn’t a more specific exception.

Changed in version 4.5.0: Fixed an issue with the default message.

exception salespyforce.errors.exceptions.CurrentlyUnsupportedError(*args, **kwargs)[source]

This exception is used when a feature or functionality being used is currently unsupported.

exception salespyforce.errors.exceptions.DELETERequestError(*args, **kwargs)[source]

This exception is used for generic DELETE request errors when there isn’t a more specific exception.

exception salespyforce.errors.exceptions.DataMismatchError(*args, **kwargs)[source]

This exception is used when there is a mismatch between two data sources.

exception salespyforce.errors.exceptions.FeatureNotConfiguredError(*args, **kwargs)[source]

This exception is used when an API request fails because a feature is not configured.

New in version 4.0.0.

exception salespyforce.errors.exceptions.GETRequestError(*args, **kwargs)[source]

This exception is used for generic GET request errors when there isn’t a more specific exception.

Changed in version 3.2.0: Enabled the ability to optionally pass status_code and/or message arguments.

exception salespyforce.errors.exceptions.HelperFunctionNotFoundError(*args, **kwargs)[source]

This exception is used when a function referenced in the helper config file does not exist.

exception salespyforce.errors.exceptions.InvalidEndpointError(*args, **kwargs)[source]

This exception is used when an invalid API endpoint / service is provided.

Changed in version 5.1.2: Removed part of the default message that was specifically for Khoros JX, which is obsolete.

exception salespyforce.errors.exceptions.InvalidFieldError(*args, **kwargs)[source]

This exception is used when an invalid field is provided.

exception salespyforce.errors.exceptions.InvalidHelperArgumentsError(*args, **kwargs)[source]

This exception is used when the helper function was supplied arguments instead of keyword arguments.

exception salespyforce.errors.exceptions.InvalidHelperFileTypeError(*args, **kwargs)[source]

This exception is used when an invalid file type is provided for the helper file.

exception salespyforce.errors.exceptions.InvalidLookupTypeError(*args, **kwargs)[source]

This exception is used when an invalid API lookup type is provided.

exception salespyforce.errors.exceptions.InvalidParameterError(*args, **kwargs)[source]

This exception is used when an invalid parameter is provided.

exception salespyforce.errors.exceptions.InvalidPayloadValueError(*args, **kwargs)[source]

This exception is used when an invalid value is provided for a payload field.

New in version 2.6.0.

exception salespyforce.errors.exceptions.InvalidRequestTypeError(*args, **kwargs)[source]

This exception is used when an invalid API request type is provided.

exception salespyforce.errors.exceptions.InvalidURLError(*args, **kwargs)[source]

This exception is used when a provided URL is invalid.

exception salespyforce.errors.exceptions.LookupMismatchError(*args, **kwargs)[source]

This exception is used when an a lookup value doesn’t match the supplied lookup type.

exception salespyforce.errors.exceptions.MissingRequiredDataError(*args, **kwargs)[source]

This exception is used when a function or method is missing one or more required arguments.

exception salespyforce.errors.exceptions.NotFoundResponseError(*args, **kwargs)[source]

This exception is used when an API query returns a 404 response and there isn’t a more specific class.

exception salespyforce.errors.exceptions.POSTRequestError(*args, **kwargs)[source]

This exception is used for generic POST request errors when there isn’t a more specific exception.

Changed in version 3.2.0: Enabled the ability to optionally pass status_code and/or message arguments.

exception salespyforce.errors.exceptions.PUTRequestError(*args, **kwargs)[source]

This exception is used for generic PUT request errors when there isn’t a more specific exception.

Changed in version 3.2.0: Enabled the ability to optionally pass status_code and/or message arguments.

exception salespyforce.errors.exceptions.PayloadMismatchError(*args, **kwargs)[source]

This exception is used when more than one payload is supplied for an API request.

New in version 3.2.0.

exception salespyforce.errors.exceptions.SalesPyForceError[source]

This is the base class for SalesPyForce exceptions.

exception salespyforce.errors.exceptions.UnknownFileTypeError(*args, **kwargs)[source]

This exception is used when a file type for a given file cannot be identified.

Return to Top


Handlers Module (salespyforce.errors.handlers)

This sub-module contains various error handling functions that are leveraged throughout the library.

Module:

salespyforce.errors.handlers

Synopsis:

Functions that handle various error situations within the namespace

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

22 Feb 2023

salespyforce.errors.handlers.eprint(*args, **kwargs)[source]

This function behaves the same as the print() function but is leveraged to print errors to sys.stderr.

Return to Top


Tools & Utilities

This section includes modules that contain tools and utilities leveraged by other scripts.


Core Utilities Module (salespyforce.utils.core_utils)

This module includes various utilities to assist with the core functionality.

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

salespyforce.utils.core_utils.display_warning(warn_msg)[source]

This function displays a UserWarning message via the warnings module.

Parameters:

warn_msg (str) – The message to be displayed

Returns:

None

salespyforce.utils.core_utils.download_image(image_url=None, file_name=None, file_path=None, response=None, extension='jpeg')[source]

This function downloads an image and saves it to a specified directory.

Parameters:

  • image_url (str) – The absolute URL to the image

  • file_name (str) – The file name including extension as which to save the file

  • file_path (str, None) – File path where the image file should be saved (default: var/images/)

  • response – The response of the previously performed API call

  • extension (str) – The file extension to use if a file name with extension is not provided

Returns:

The full path to the downloaded image

Raises:

RuntimeError

salespyforce.utils.core_utils.get_file_type(file_path)[source]

This function attempts to identify if a given file path is for a YAML or JSON file.

Parameters:

file_path (str) – The full path to the file

Returns:

The file type in string format (e.g. yaml or json)

Raises:

FileNotFoundError, khoros.errors.exceptions.UnknownFileTypeError

salespyforce.utils.core_utils.get_image_ref_id(image_url)[source]

This function parses an image URL to identify the reference ID (refid) value. (Reference 1, Reference 2)

Parameters:

image_url (str) – The URL of an image from within Salesforce

Returns:

The reference ID (refid) value

salespyforce.utils.core_utils.get_random_string(length=32, prefix_string='')[source]

This function returns a random alphanumeric string.

Parameters:

  • length (int) – The length of the string (32 by default)

  • prefix_string (str) – A string to which the random string should be appended (optional)

Returns:

The alphanumeric string

salespyforce.utils.core_utils.url_decode(encoded_string)[source]

This function decodes a url-encoded string.

Parameters:

encoded_string (str) – The url-encoded string

Returns:

The unencoded string

salespyforce.utils.core_utils.url_encode(raw_string)[source]

This function encodes a string for use in URLs.

Parameters:

raw_string (str) – The raw string to be encoded

Returns:

The encoded string

Return to Top


Helper Module (salespyforce.utils.helper)

This module enables the use of helper files to define core object configuration.

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

class salespyforce.utils.helper.HelperParsing[source]

This class is used to help parse values imported from a YAML configuration file.

salespyforce.utils.helper.get_helper_settings(file_path, file_type='yaml', defined_settings=None)[source]

This function returns a dictionary of the defined helper settings.

Parameters:

  • file_path (str) – The file path to the helper configuration file

  • file_type (str) – Defines the helper configuration file as a yaml file (default) or a json file

  • defined_settings (dict, None) – Core object settings (if any) defined via the defined_settings parameter

Returns:

Dictionary of helper variables

Raises:

salespyforce.errors.exceptions.InvalidHelperFileTypeError

salespyforce.utils.helper.import_helper_file(file_path, file_type)[source]

This function imports a YAML (.yml) or JSON (.json) helper config file.

Parameters:

  • file_path (str) – The file path to the YAML file

  • file_type (str) – Defines the file type as either yaml or json

Returns:

The parsed configuration data

Raises:

FileNotFoundError, salespyforce.errors.exceptions.InvalidHelperFileTypeError

Return to Top


Logging Utilities Module (salespyforce.utils.log_utils)

This module includes various utilities to assist with logging.

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

class salespyforce.utils.log_utils.LessThanFilter(exclusive_maximum, name='')[source]

This class allows filters to be set to limit log levels to only less than a specified level.

See also

Zoey Greer is the original author of this class which was provided on Stack Overflow.

filter(record)[source]

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.

salespyforce.utils.log_utils.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)[source]

This function initializes logging for the salespyforce library.

Return to Top


Version Module (salespyforce.utils.version)

This module is the primary source of the current version of the salespyforce package.

Module:

salespyforce.utils.version

Synopsis:

This simple script contains the package version

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

01 Sep 2023

salespyforce.utils.version.get_full_version()[source]

This function returns the current full version of the salespyforce package.

salespyforce.utils.version.get_major_minor_version()[source]

This function returns the current major.minor (i.e. X.Y) version of the salespyforce package.

Return to Top


Unit Testing

This section includes modules that are used in unit testing the library.


Tests Module (salespyforce.utils.tests)

This module includes unit tests for the package that are performed using pytest.

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

Return to Top


Resources Module (salespyforce.utils.tests.resources)

This module includes frequently used resources for performing unit testing.

Module:

salespyforce.utils.tests.resources

Synopsis:

Frequently used resources for performing unit testing

Usage:

from salespyforce.utils.tests import resources

Example:

exceptions = resources.import_exceptions_module()

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

27 May 2023

class salespyforce.utils.tests.resources.MockResponse(json_body, status_code=200)[source]

This class simulates an API response for testing purposes.

New in version 1.1.0.

salespyforce.utils.tests.resources.get_core_object()[source]

This function instantiates and returns the core object using a local helper file.

New in version 1.1.0.

salespyforce.utils.tests.resources.import_modules(*modules)[source]

This function imports and returns one or more modules to utilize in a unit test.

New in version 1.1.0.

Parameters:

modules – One or more module paths (absolute) in string format

Returns:

The imported module(s) as an individual object or a tuple of objects

salespyforce.utils.tests.resources.instantiate_with_local_helper()[source]

This function instantiates the Salesforce object using a local helper file for unit testing.

New in version 1.1.0.

Returns:

The instantiated salespyforce.core.Salesforce object

Raises:

FileNotFoundError

salespyforce.utils.tests.resources.instantiate_with_secrets_helper()[source]

This function instantiates the Salesforce object using the unencrypted helper file intended for GitHub Actions.

New in version 1.1.0.

Returns:

The instantiated salespyforce.core.Salesforce object

Raises:

FileNotFoundError

salespyforce.utils.tests.resources.local_helper_exists()[source]

This function checks to see if a helper file is present in the local/ directory.

New in version 1.1.0.

salespyforce.utils.tests.resources.mock_error_post(*args, **kwargs)[source]

This function works with the MockedResponse class to simulate a failed API response.

New in version 1.1.0.

salespyforce.utils.tests.resources.mock_sosl_get(*args, **kwargs)[source]

This function works with the MockedResponse class to simulate an SOSL response.

salespyforce.utils.tests.resources.mock_success_post(*args, **kwargs)[source]

This function works with the MockedResponse class to simulate a successful API response.

New in version 1.1.0.

salespyforce.utils.tests.resources.secrets_helper_exists()[source]

This function checks to see if the unencrypted helper file exists for GitHub Actions.

New in version 1.1.0.

salespyforce.utils.tests.resources.set_package_path()[source]

This function adds the high-level salespyforce directory to the sys.path list.

New in version 1.1.0.

Return to Top


Test Instantiate Object Module (salespyforce.utils.tests.test_instantiate_object)

This module is used by pytest to verify that the core object can be instantiated successfully.

Module:

salespyforce.utils.tests.test_instantiate_object

Synopsis:

This module is used by pytest to test instantiating the core object

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

29 May 2023

salespyforce.utils.tests.test_instantiate_object.test_get_api_versions()[source]

This function tests the get_api_versions() method in the core object.

New in version 1.1.0.

salespyforce.utils.tests.test_instantiate_object.test_get_org_limits()[source]

This function tests the get_org_limits() method in the core object.

New in version 1.1.0.

salespyforce.utils.tests.test_instantiate_object.test_get_rest_resources()[source]

This function tests the get_rest_resources() method in the core object.

New in version 1.1.0.

salespyforce.utils.tests.test_instantiate_object.test_instantiate_core_object()[source]

This function tests the ability to instantiate the core object.

New in version 1.1.0.

Return to Top


Test sObjects Module (salespyforce.utils.tests.test_sobjects)

This module is used by pytest to verify that the sObject-related functions work properly.

Module:

salespyforce.utils.tests.test_sobjects

Synopsis:

This module is used by pytest to test basic sObject-related methods

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

29 May 2023

salespyforce.utils.tests.test_sobjects.test_get_all_sobjects()[source]

This function tests the get_all_sobjects() method in the core object.

New in version 1.1.0.

salespyforce.utils.tests.test_sobjects.test_get_and_describe_sobject()[source]

This function tests the get_sobject() and describe_object() methods in the core object.

New in version 1.1.0.

Return to Top


Test SOQL Module (salespyforce.utils.tests.test_soql)

This module is used by pytest to verify that SOQL queries work properly.

Module:

salespyforce.utils.tests.test_sobjects

Synopsis:

This module is used by pytest to test performing SOQL queries

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

29 May 2023

salespyforce.utils.tests.test_soql.test_soql_query()[source]

This function tests the ability to perform a SOQL query.

New in version 1.1.0.

Return to Top


Test SOSL Module (salespyforce.utils.tests.test_sosl)

This module is used by pytest to verify that SOSL queries work properly.

Module:

salespyforce.utils.tests.test_sobjects

Synopsis:

This module is used by pytest to test performing SOQL queries

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

29 May 2023

salespyforce.utils.tests.test_sosl.test_search_string(monkeypatch)[source]

This function tests the ability to search for a string using an SOSL query.

New in version 1.1.0.

Return to Top