Utilities#

Core Utilities#

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:

28 Feb 2026

salespyforce.utils.core_utils.display_warning(warn_msg: str) → None[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: str | None = None, file_name: str | None = None, file_path: str | None = None, response=None, extension: str = 'jpeg') → str[source]#

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

Changed in version 1.5.0: This function now raises more specific exceptions instead of the generic RuntimeError exception.

Parameters:

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

  • file_name (str, None) – The file name (including extension) to use as the file name (Default: randomly generated)

  • file_path (str, None) – File path where the image file should be saved (Default: ./)

  • 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 (Default: jpeg)

Returns:

The full path to the downloaded image

Raises:

salespyforce.errors.exceptions.MissingRequiredDataError, salespyforce.errors.exceptions.GETRequestError

salespyforce.utils.core_utils.ensure_ends_with(eval_string, suffix)[source]#

This function ensures that a string ends with a given suffix.

Added in version 1.5.0.

Parameters:

  • eval_string (str) – The string to be evaluated

  • suffix (str) – The suffix string that must be at the end of the evaluated string

Returns:

The string with the suffix at the end

salespyforce.utils.core_utils.ensure_starts_with(eval_string, prefix)[source]#

This function ensures that a string starts with a given prefix.

Added in version 1.5.0.

Parameters:

  • eval_string (str) – The string to be evaluated

  • prefix (str) – The prefix string that must be at the beginning of the evaluated string

Returns:

The string with the prefix at the start

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: str) → str[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: str) → str[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: int = 32, prefix_string: str = '') → str[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: str) → str[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: str) → str[source]#

This function encodes a string for use in URLs.

Parameters:

raw_string (str) – The raw string to be encoded

Returns:

The encoded string

Helper Utilities#

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:

25 Feb 2026

salespyforce.utils.helper.get_helper_settings(file_path: str, file_type: str = 'yaml', defined_settings: dict | None = None) → dict[source]#

This function returns a dictionary of the defined helper settings.

Changed in version 1.5.0: The file_type parameter now accepts both yaml and yml as file extensions for YAML.

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: str, file_type: str) → dict[source]#

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

Changed in version 1.5.0: The file_type parameter now accepts both yaml and yml as file extensions for YAML.

Parameters:

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

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

Returns:

The parsed configuration data

Raises:

FileNotFoundError, salespyforce.errors.exceptions.InvalidHelperFileTypeError

Logging Utilities#

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]#

Bases: Filter

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.

Version Utilities#

Module:

salespyforce.utils.version

Synopsis:

Utilities for working with the package version

Created By:

Jeff Shurtliff

Last Modified:

Jeff Shurtliff

Modified Date:

19 Feb 2026

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

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

Changed in version 1.5.0: The function will now attempt to retrieve the version from the pyproject.toml file if it cannot be retrieved via the package metadata.

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

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

Returns:

The current package version as a string

salespyforce.utils.version.get_major_minor_version(full_version: str | None = None) → str[source]#

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

Changed in version 1.5.0: The function now accepts an optional full version if already defined.

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

Parameters:

full_version (str, None) – The full package version (e.g. X.Y.Z)

Returns:

The current package version (X.Y) as a string

salespyforce.utils.version.get_version_from_pyproject(pyproject_path: str | None = None) → str[source]#

This function retrieves the current version from the pyproject.toml file.

Added in version 1.5.0.

Parameters:

pyproject_path (str, None) – The path to the pyproject.toml file (optional)

Returns:

The current package version as a string