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.

Added 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.

Added 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.

Added 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:

02 Feb 2026

salespyforce.errors.handlers.display_warning(message: str, *, category: type[Warning] = <class 'UserWarning'>, stacklevel: int = 2) → None[source]

This function emits a warning that points to the caller by default.

Added in version 1.4.0.

Parameters:

  • message (str) – Warning message to emit

  • category (type[Warning]) – Warning category class (default: UserWarning)

  • stacklevel (int) – How far up the call stack to attribute the warning (2 by default - caller of this helper)

Returns:

None

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

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

salespyforce.errors.handlers.get_exception_type(exc) → str[source]

This function returns the exception type (e.g. RuntimeError, TypeError, etc.) for a given exception.

Added in version 1.4.0.

Returns:

The exception type as a string

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:

02 Feb 2026

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

This function displays a UserWarning message via the warnings module.

Deprecated since version 1.4.0: Use salespyforce.errors.handlers.display_warning() instead.

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_18_char_id(record_id: str) → str[source]

This function converts a 15-character Salesforce record ID to its 18-character case-insensitive form.

Added in version 1.4.0.

Parameters:

record_id (str) – The Salesforce record ID to convert (or return unchanged if already 18 characters)

Returns:

The 18-character Salesforce record ID

Raises:

ValueError

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, salespyforce.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.is_valid_salesforce_url(url: str) → bool[source]

This function evaluates a URL to determine if it is a valid Salesforce URL.

Added in version 1.4.0.

Parameters:

url (str) – The URL to evaluate

Returns:

Boolean value depending on whether the URL meets the criteria

salespyforce.utils.core_utils.matches_regex_pattern(pattern: str, text: str, full_match: bool = False, must_start_with: bool = False) → bool[source]

This function compares a text string against a regex pattern and determines whether they match.

Added in version 1.4.0.

Parameters:

  • pattern (str) – The regex pattern that should match

  • text (str) – The text string to evaluate

  • full_match (bool) – Determines if the entire string should be validated

  • must_start_with – Determines if the pattern must be at the beginning of the string

Returns:

True if the regex pattern matches anywhere in the text string

Raises:

TypeError

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:

03 Feb 2026

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:

31 Dec 2025

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 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:

Utilities for working with the package version.

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

17 Nov 2025

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

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

Changed in version 1.4.0: The function now retrieves the version from the package metadata, rather than from the __version__ special variable.

Retrieves the package version from the installed package metadata, which is populated from the version field in pyproject.toml.

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

Return the current major.minor (i.e., X.Y) version of the package.

Changed in version 1.4.0: The function utilizes the salespyforce.utils.version.get_full_version() function to get the package version rather than using __version__.

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.

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:

20 Dec 2025

These tests rely on the salesforce_unit fixture defined in conftest.py to keep them fast and deterministic. When you want to verify behavior against a real org, add @pytest.mark.integration and switch the fixture parameter to salesforce_integration.

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

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

Added in version 1.1.0.

Changed in version 1.4.0: The function now utilizes the salesforce_unit fixture.

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

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

Added in version 1.1.0.

Changed in version 1.4.0: The function now utilizes the salesforce_unit fixture.

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

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

Added in version 1.1.0.

Changed in version 1.4.0: The function now utilizes the salesforce_unit fixture.

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

This function tests the ability to instantiate the core object.

Added in version 1.1.0.

Changed in version 1.4.0: The function now utilizes the salesforce_unit fixture.

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.

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_soql

Synopsis:

This module is used by pytest to test performing SOQL queries

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

20 Dec 2025

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

This function tests the ability to perform a SOQL query.

Added in version 1.1.0.

Changed in version 1.4.0: The function now utilizes the salesforce_unit fixture.

Return to Top


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

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

Return to Top