salespyforce 1.4.0.dev1__py3-none-any.whl → 1.4.0rc0__py3-none-any.whl

salespyforce/api.py

@@ -4,12 +4,13 @@
 :Synopsis:          Defines the basic functions associated with the Salesforce API
 :Created By:        Jeff Shurtliff
 :Last Modified:     Jeff Shurtliff
-:Modified Date:     17 Feb 2023
+:Modified Date:     30 Jan 2026
 """
 
 import requests
 
-from .utils import log_utils
+from . import errors
+from .utils import core_utils, log_utils
 
 # Initialize logging
 logger = log_utils.initialize_logging(__name__)
@@ -19,6 +20,10 @@ def get(sfdc_object, endpoint, params=None, headers=None, timeout=30, show_full_
     """This method performs a GET request against the Salesforce instance.
     (`Reference <https://jereze.com/code/authentification-salesforce-rest-api-python/>`_)
 
+    .. version-changed:: 1.4.0
+       The full URL for the API call is now constructed prior to making the call.
+       The provided URL is also now evaluated to ensure it is a valid Salesforce URL.
+
     :param sfdc_object: The instantiated SalesPyForce object
     :param endpoint: The API endpoint to query
     :type endpoint: str
@@ -40,12 +45,13 @@ def get(sfdc_object, endpoint, params=None, headers=None, timeout=30, show_full_
     default_headers = _get_headers(sfdc_object.access_token)
     headers = default_headers if not headers else headers
 
-    # Make sure the endpoint begins with a slash
-    endpoint = f'/{endpoint}' if not endpoint.startswith('/') else endpoint
+    # Construct the request URL
+    url = _construct_full_query_url(endpoint, sfdc_object.instance_url)
 
     # Perform the API call
-    response = requests.get(f'{sfdc_object.instance_url}{endpoint}', headers=headers, params=params, timeout=timeout)
+    response = requests.get(url, headers=headers, params=params, timeout=timeout)
     if response.status_code >= 300:
+        # TODO: Functionalize this segment and figure out how to improve on the approach somehow
         if show_full_error:
             raise RuntimeError(f'The GET request failed with a {response.status_code} status code.\n'
                                f'{response.text}')
@@ -61,6 +67,10 @@ def api_call_with_payload(sfdc_object, method, endpoint, payload, params=None, h
     """This method performs a POST call against the Salesforce instance.
     (`Reference <https://jereze.com/code/authentification-salesforce-rest-api-python/>`_)
 
+    .. version-changed:: 1.4.0
+       The full URL for the API call is now constructed prior to making the call.
+       The provided URL is also now evaluated to ensure it is a valid Salesforce URL.
+
     :param sfdc_object: The instantiated SalesPyForce object
     :param method: The API method (``post``, ``put``, or ``patch``)
     :type method: str
@@ -86,25 +96,23 @@ def api_call_with_payload(sfdc_object, method, endpoint, payload, params=None, h
     default_headers = _get_headers(sfdc_object.access_token)
     headers = default_headers if not headers else headers
 
-    # Make sure the endpoint begins with a slash
-    endpoint = f'/{endpoint}' if not endpoint.startswith('/') else endpoint
+    # Construct the request URL
+    url = _construct_full_query_url(endpoint, sfdc_object.instance_url)
 
     # Perform the API call
     if method.lower() == 'post':
-        response = requests.post(f'{sfdc_object.instance_url}{endpoint}', json=payload, headers=headers, params=params,
-                                 timeout=timeout)
+        response = requests.post(url, json=payload, headers=headers, params=params, timeout=timeout)
     elif method.lower() == 'patch':
-        response = requests.patch(f'{sfdc_object.instance_url}{endpoint}', json=payload, headers=headers, params=params,
-                                  timeout=timeout)
+        response = requests.patch(url, json=payload, headers=headers, params=params, timeout=timeout)
     elif method.lower() == 'put':
-        response = requests.put(f'{sfdc_object.instance_url}{endpoint}', json=payload, headers=headers, params=params,
-                                timeout=timeout)
+        response = requests.put(url, json=payload, headers=headers, params=params, timeout=timeout)
     else:
-        raise ValueError('The API call method (POST or PATCH OR PUT) must be defined.')
+        raise ValueError('The API call method (POST or PATCH or PUT) must be defined')
 
     # Examine the result
     if response.status_code >= 300:
         if show_full_error:
+            # TODO: Functionalize this segment and figure out how to improve on the approach somehow
             raise RuntimeError(f'The POST request failed with a {response.status_code} status code.\n'
                                f'{response.text}')
         else:
@@ -117,6 +125,49 @@ def api_call_with_payload(sfdc_object, method, endpoint, payload, params=None, h
     return response
 
 
+def delete(sfdc_object, endpoint, params=None, headers=None, timeout=30, show_full_error=True, return_json=True):
+    """This method performs a DELETE request against the Salesforce instance.
+
+    .. version-added:: 1.4.0
+
+    :param sfdc_object: The instantiated SalesPyForce object
+    :param endpoint: The API endpoint to query
+    :type endpoint: str
+    :param params: The query parameters (where applicable)
+    :type params: dict, None
+    :param headers: Specific API headers to use when performing the API call
+    :type headers: dict, None
+    :param timeout: The timeout period in seconds (defaults to ``30``)
+    :type timeout: int, str, None
+    :param show_full_error: Determines if the full error message should be displayed (defaults to ``True``)
+    :type show_full_error: bool
+    :param return_json: Determines if the response should be returned in JSON format (defaults to ``True``)
+    :returns: The API response in JSON format or as a ``requests`` object
+    """
+    # Define the parameters as an empty dictionary if none are provided
+    params = {} if params is None else params
+
+    # Define the headers
+    default_headers = _get_headers(sfdc_object.access_token)
+    headers = default_headers if not headers else headers
+
+    # Construct the request URL
+    url = _construct_full_query_url(endpoint, sfdc_object.instance_url)
+
+    # Perform the API call
+    response = requests.delete(url, headers=headers, params=params, timeout=timeout)
+    if response.status_code >= 300:
+        if show_full_error:
+            # TODO: Functionalize this segment and figure out how to improve on the approach somehow
+            raise RuntimeError(f'The DELETE request failed with a {response.status_code} status code.\n'
+                               f'{response.text}')
+        else:
+            raise RuntimeError(f'The DELETE request failed with a {response.status_code} status code.')
+    if return_json:
+        response = response.json()
+    return response
+
+
 def _get_headers(_access_token, _header_type='default'):
     """This function returns the appropriate HTTP headers to use for different types of API calls."""
     headers = {
@@ -127,3 +178,36 @@ def _get_headers(_access_token, _header_type='default'):
     if _header_type == 'articles':
         headers['accept-language'] = 'en-US'
     return headers
+
+
+def _construct_full_query_url(_endpoint: str, _instance_url: str) -> str:
+    """This function constructs the URL to use in an API call to the Salesforce REST API.
+
+    .. version-added:: 1.4.0
+
+    :param _endpoint: The endpoint provided when calling an API call method or function
+    :type _endpoint: str
+    :param _instance_url: The Salesforce instance URL defined when the core object was instantiated
+    :type _instance_url: str
+    :returns: The fully qualified URL
+    :raises: :py:exc:`TypeError`,
+             :py:exc:`errors.exceptions.InvalidURLError`
+    """
+    # Raise an exception if the endpoint is not a string
+    if not isinstance(_endpoint, str):
+        exc_msg = 'The provided URL must be a string and a valid Salesforce URL'
+        logger.critical(exc_msg)
+        raise TypeError(exc_msg)
+
+    # Construct the URL as needed by prepending the instance URL
+    if _endpoint.startswith('https://'):
+        # Only permit valid Salesforce URLs
+        if not core_utils.is_valid_salesforce_url(_endpoint):
+            raise errors.exceptions.InvalidURLError(url=_endpoint)
+        _url = _endpoint
+    else:
+        _endpoint = f'/{_endpoint}' if not _endpoint.startswith('/') else _endpoint
+        _url = f'{_instance_url}{_endpoint}'
+
+    # Return the constructed URL
+    return _url

salespyforce/core.py

@@ -6,7 +6,7 @@
 :Example:           ``sfdc = Salesforce(helper=helper_file_path)``
 :Created By:        Jeff Shurtliff
 :Last Modified:     Jeff Shurtliff
-:Modified Date:     17 Nov 2025
+:Modified Date:     03 Feb 2026
 """
 
 import re
@@ -21,6 +21,7 @@ from .utils.helper import get_helper_settings
 
 # Define constants
 FALLBACK_SFDC_API_VERSION = '65.0'      # Used if querying the org for the version fails
+VALID_ACCESS_CONTROL_FIELDS = {'HasReadAccess', 'HasEditAccess', 'HasDeleteAccess'}
 
 # Initialize logging
 logger = log_utils.initialize_logging(__name__)
@@ -60,7 +61,8 @@ class Salesforce(object):
         :param helper: The file path of a helper file
         :type helper: str, None
         :returns: The instantiated object
-        :raises: :py:exc:`TypeError`
+        :raises: :py:exc:`TypeError`,
+                 :py:exc:`RuntimeError`
         """
         # Define the default settings
         self._helper_settings = {}
@@ -94,8 +96,9 @@ class Salesforce(object):
         # Get the connection information used to connect to the instance
         self.connection_info = connection_info if connection_info is not None else self._get_empty_connection_info()
 
-        # Define the base URL value
-        self.base_url = self.connection_info.get('base_url')
+        # Define the base URL and Org ID
+        self.base_url = self.connection_info.get('base_url', '')
+        self.org_id = self.connection_info.get('org_id', '')
 
         # Define the connection response data variables
         auth_response = self.connect()
@@ -106,6 +109,9 @@ class Salesforce(object):
         # Define the version with explicitly provided version or by querying the Salesforce org
         self.version = f'v{version}' if version else f'v{self.get_latest_api_version()}'
 
+        # Retrieve info about current user
+        self.current_user_info = self.retrieve_current_user_info(on_init=True, raise_exc_on_error=False)
+
         # Import inner object classes so their methods can be called from the primary object
         self.chatter = self._import_chatter_class()
         self.knowledge = self._import_knowledge_class()
@@ -142,11 +148,40 @@ class Salesforce(object):
         """This method returns the appropriate HTTP headers to use for different types of API calls."""
         return api._get_headers(_access_token=self.access_token, _header_type=_header_type)
 
+    def _get_cached_user_info(self, _field: str, _retrieve_if_missing: bool = False):
+        """This method attempts to retrieve a value for a given field in the cached ``userinfo`` data and
+           optionally queries the API as needed to retrieve the data when not found.
+
+        .. version-added:: 1.4.0
+
+        :param _field: The name of the field for which the value is needed
+        :type _field: str
+        :param _retrieve_if_missing: Will query the Salesforce REST API for the data when missing if True
+                                     (``False`` by default)
+        :type _retrieve_if_missing: bool
+        :returns: The field value when found (or retrieved), or a None value if the field value could not be obtained
+        :raises: :py:exc:`errors.exceptions.APIRequestError`
+        """
+        _field_value = None
+        _not_present_msg = f"The '{_field}' field is not present in the current user info data"
+        if self.current_user_info and _field in self.current_user_info:
+            _field_value = self.current_user_info[_field]
+        else:
+            logger.warning(_not_present_msg)
+            if _retrieve_if_missing:
+                self.current_user_info = self.retrieve_current_user_info(raise_exc_on_error=True)
+                if self.current_user_info and _field in self.current_user_info:
+                    _field_value = self.current_user_info[_field]
+                else:
+                    logger.error(f'{_not_present_msg} even after refreshing cached current user info')
+        return _field_value
+
     def connect(self):
         """This method connects to the Salesforce instance to obtain the access token.
         (`Reference <https://jereze.com/code/authentification-salesforce-rest-api-python/>`_)
 
         :returns: The API call response with the authorization information
+        :raises: :py:exc:`RuntimeError`
         """
         params = {
             'grant_type': 'password',
@@ -160,6 +195,51 @@ class Salesforce(object):
             raise RuntimeError(f'Failed to connect to the Salesforce instance.\n{response.text}')
         return response.json()
 
+    def retrieve_current_user_info(self, all_data=False, raise_exc_on_error=False, on_init=False) -> dict:
+        """This method retrieves the ``userinfo`` data for the current/running user.
+
+        .. version-added:: 1.4.0
+
+        :param all_data: Returns all ``userinfo`` data from the API when True instead of only the relevant fields/values
+                         (``False`` by default)
+        :type all_data: bool
+        :param raise_exc_on_error: Raises an exception if the API retrieval attempt fails when True (``False`` by default)
+        :type raise_exc_on_error: bool
+        :param on_init: Indicates if the method is being called during the core object instantiation (``False`` by default)
+        :type on_init: bool
+        :returns: The user info data within a dictionary
+        :raises: :py:exc:`RuntimeError`,
+                 :py:exc:`errors.exceptions.APIRequestError`
+        """
+        user_info = {'user_id': '', 'nickname': '', 'name': '', 'email': '', 'user_type': '',
+                     'language': '', 'locale': '', 'utcOffset': '', 'is_salesforce_integration_user': None}
+        bool_fields = ['is_salesforce_integration_user']
+        endpoint = '/services/oauth2/userinfo'
+        base_error_msg = 'Failed to retrieve current user info'
+        msg_init_segment = 'on core object instantiation'
+        if on_init:
+            base_error_msg = f'{base_error_msg} {msg_init_segment}'
+        try:
+            response = self.get(endpoint)
+            if isinstance(response, dict) and all_data:
+                user_info = response
+            elif isinstance(response, dict):
+                for field in user_info.keys():
+                    if field in response:
+                        default_val = None if field in bool_fields else ''
+                        user_info[field] = response.get(field, default_val)
+            else:
+                logger.error(f'{base_error_msg} with a usable format')
+        except Exception as exc:
+            exc_type = errors.handlers.get_exception_type(exc)
+            exc_msg = f'{base_error_msg} due to {exc_type} exception: {exc}'
+            logger.error(exc_msg)
+            if raise_exc_on_error:
+                raise errors.exceptions.APIRequestError(f'{exc_type}: {exc}')
+
+        # Return the populated user info
+        return user_info
+
     def get(self, endpoint, params=None, headers=None, timeout=30, show_full_error=True, return_json=True):
         """This method performs a GET request against the Salesforce instance.
         (`Reference <https://jereze.com/code/authentification-salesforce-rest-api-python/>`_)
@@ -176,6 +256,7 @@ class Salesforce(object):
         :type show_full_error: bool
         :param return_json: Determines if the response should be returned in JSON format (defaults to ``True``)
         :returns: The API response in JSON format or as a ``requests`` object
+        :raises: :py:exc:`RuntimeError`
         """
         return api.get(self, endpoint=endpoint, params=params, headers=headers, timeout=timeout,
                        show_full_error=show_full_error, return_json=return_json)
@@ -201,6 +282,7 @@ class Salesforce(object):
         :type show_full_error: bool
         :param return_json: Determines if the response should be returned in JSON format (defaults to ``True``)
         :returns: The API response in JSON format or as a ``requests`` object
+        :raises: :py:exc:`RuntimeError`
         """
         return api.api_call_with_payload(self, method=method, endpoint=endpoint, payload=payload, params=params,
                                          headers=headers, timeout=timeout, show_full_error=show_full_error,
@@ -224,6 +306,7 @@ class Salesforce(object):
         :type show_full_error: bool
         :param return_json: Determines if the response should be returned in JSON format (defaults to ``True``)
         :returns: The API response in JSON format or as a ``requests`` object
+        :raises: :py:exc:`RuntimeError`
         """
         return api.api_call_with_payload(self, 'post', endpoint=endpoint, payload=payload, params=params,
                                          headers=headers, timeout=timeout, show_full_error=show_full_error,
@@ -247,6 +330,7 @@ class Salesforce(object):
         :type show_full_error: bool
         :param return_json: Determines if the response should be returned in JSON format (defaults to ``True``)
         :returns: The API response in JSON format or as a ``requests`` object
+        :raises: :py:exc:`RuntimeError`
         """
         return api.api_call_with_payload(self, 'patch', endpoint=endpoint, payload=payload, params=params,
                                          headers=headers, timeout=timeout, show_full_error=show_full_error,
@@ -270,16 +354,41 @@ class Salesforce(object):
         :type show_full_error: bool
         :param return_json: Determines if the response should be returned in JSON format (defaults to ``True``)
         :returns: The API response in JSON format or as a ``requests`` object
+        :raises: :py:exc:`RuntimeError`
         """
         return api.api_call_with_payload(self, 'put', endpoint=endpoint, payload=payload, params=params,
                                          headers=headers, timeout=timeout, show_full_error=show_full_error,
                                          return_json=return_json)
 
+    def delete(self, endpoint, params=None, headers=None, timeout=30, show_full_error=True, return_json=True):
+        """This method performs a DELETE request against the Salesforce instance.
+        (`Reference <https://jereze.com/code/authentification-salesforce-rest-api-python/>`_)
+
+        .. version-added:: 1.4.0
+
+        :param endpoint: The API endpoint to query
+        :type endpoint: str
+        :param params: The query parameters (where applicable)
+        :type params: dict, None
+        :param headers: Specific API headers to use when performing the API call
+        :type headers: dict, None
+        :param timeout: The timeout period in seconds (defaults to ``30``)
+        :type timeout: int, str, None
+        :param show_full_error: Determines if the full error message should be displayed (defaults to ``True``)
+        :type show_full_error: bool
+        :param return_json: Determines if the response should be returned in JSON format (defaults to ``True``)
+        :returns: The API response in JSON format or as a ``requests`` object
+        :raises: :py:exc:`RuntimeError`
+        """
+        return api.delete(self, endpoint=endpoint, params=params, headers=headers, timeout=timeout,
+                          show_full_error=show_full_error, return_json=return_json)
+
     def get_api_versions(self) -> list:
         """This method returns the API versions for the Salesforce releases.
         (`Reference <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_versions.htm>`_)
 
         :returns: A list containing the API metadata from the ``/services/data`` endpoint.
+        :raises: :py:exc:`RuntimeError`
         """
         return self.get('/services/data')
 
@@ -305,13 +414,19 @@ class Salesforce(object):
     def get_org_limits(self):
         """This method returns a list of all org limits.
 
-        .. versionadded:: 1.1.0
+        .. version-added:: 1.1.0
+
+        :returns: The Salesforce org governor limits data
+        :raises: :py:exc:`RuntimeError`
         """
         return self.get(f'/services/data/{self.version}/limits')
 
     def get_all_sobjects(self):
         """This method returns a list of all Salesforce objects. (i.e. sObjects)
         (`Reference <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_describeGlobal.htm>`_)
+
+        :returns: The list of all Salesforce objects
+        :raises: :py:exc:`RuntimeError`
         """
         return self.get(f'/services/data/{self.version}/sobjects')
 
@@ -325,6 +440,7 @@ class Salesforce(object):
         :param describe: Determines if the full (i.e. ``describe``) data should be returned (defaults to ``False``)
         :type describe: bool
         :returns: The Salesforce object data
+        :raises: :py:exc:`RuntimeError`
         """
         uri = f'/services/data/{self.version}/sobjects/{object_name}'
         uri = f'{uri}/describe' if describe else uri
@@ -337,15 +453,32 @@ class Salesforce(object):
         :param object_name: The name of the Salesforce object
         :type object_name: str
         :returns: The Salesforce object data
+        :raises: :py:exc:`RuntimeError`
         """
         return self.get_sobject(object_name, describe=True)
 
     def get_rest_resources(self):
         """This method returns a list of all available REST resources.
         (`Reference <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_discoveryresource.htm>`_)
+
+        :returns: The list of all available REST resources for the Salesforce org
+        :raises: :py:exc:`RuntimeError`
         """
         return self.get(f'/services/data/{self.version}')
 
+    @staticmethod
+    def get_18_char_id(record_id: str) -> str:
+        """This method converts a 15-character Salesforce record ID to its 18-character case-insensitive form.
+
+        .. version-added:: 1.4.0
+
+        :param record_id: The Salesforce record ID to convert (or return unchanged if already 18 characters)
+        :type record_id: str
+        :returns: The 18-character Salesforce record ID
+        :raises: :py:exc:`ValueError`
+        """
+        return core_utils.get_18_char_id(record_id=record_id)
+
     def soql_query(self, query, replace_quotes=True, next_records_url=False):
         """This method performs a SOQL query and returns the results in JSON format.
         (`Reference 1 <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query.htm>`_,
@@ -358,6 +491,7 @@ class Salesforce(object):
         :param next_records_url: Indicates that the ``query`` parameter is a ``nextRecordsUrl`` value.
         :type next_records_url: bool
         :returns: The result of the SOQL query
+        :raises: :py:exc:`RuntimeError`
         """
         if next_records_url:
             query = re.sub(r'^.*/', '', query) if '/' in query else query
@@ -372,16 +506,215 @@ class Salesforce(object):
         """This method performs a SOSL query to search for a given string.
         (`Reference <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_search.htm>`_)
 
-        .. versionadded:: 1.1.0
+        .. version-added:: 1.1.0
 
         :param string_to_search: The string for which to search
         :type string_to_search: str
         :returns: The SOSL response data in JSON format
+        :raises: :py:exc:`RuntimeError`
         """
         query = 'FIND {' + string_to_search + '}'
         query = core_utils.url_encode(query)
         return self.get(f'/services/data/{self.version}/search/?q={query}')
 
+    def check_user_record_access(self, record_id: str, user_id=None) -> dict:
+        """This method checks the Read, Edit, and Delete access for a given record and user.
+
+        .. version-added:: 1.4.0
+
+        :param record_id: The ``Id`` value of the record against which to check the user access
+        :type record_id: str
+        :param user_id: The ``Id`` of the user to evaluate (or the current user's ID if not explicitly defined)
+        :type user_id: str, None
+        :returns: Dictionary with Boolean values for ``HasReadAccess``, ``HasEditAccess``, and ``HasDeleteAccess``
+        :raises: :py:exc:`RuntimeError`,
+                 :py:exc:`errors.exceptions.APIRequestError`
+        """
+        record_access = {'HasReadAccess': None, 'HasEditAccess': None, 'HasDeleteAccess': None}
+
+        # Use the current/running user's ID if an ID wasn't explicitly provided
+        if not user_id:
+            user_id = self._get_cached_user_info(_field='user_id', _retrieve_if_missing=True)
+            if user_id:
+                logger.debug(f'Using the User Id {user_id} for the running user as an Id was not specified')
+
+        # Raise an exception if the User ID is still undefined
+        if not user_id:
+            error_msg = f'The user access for record Id {record_id} cannot be checked as the User Id is undefined'
+            logger.error(error_msg)
+            raise errors.exceptions.MissingRequiredDataError(error_msg)
+
+        # Perform SOQL query for the access data
+        query = f"""
+            SELECT RecordId, HasReadAccess, HasEditAccess, HasDeleteAccess
+            FROM UserRecordAccess
+            WHERE UserId = '{user_id}' AND RecordId = '{record_id}'
+        """
+        response = self.soql_query(query=query)
+
+        # Parse the response to extract the relevant field values
+        if 'records' in response and response['records']:
+            response = response['records'][0]
+            for field in record_access.keys():
+                record_access[field] = response.get(field, None)
+
+        # Return the record access data
+        return record_access
+
+    @staticmethod
+    def _eval_user_record_access(_field: str, _record_id: str,
+                                 _record_access_data: dict, _raise_exc_on_failure: bool = True) -> bool:
+        """This private method checks for an access level given the field and the record access data.
+
+        .. version-added:: 1.4.0
+
+        :param _field: The access level field to evaluate (``HasReadAccess``, ``HasEditAccess``, ``HasDeleteAccess``)
+        :type _field: str
+        :param _record_id: The ID value for the record whose access is being checked
+        :type _record_id: str
+        :param _record_access_data: The user record access data that has already been retrieved
+        :type _record_access_data: dict
+        :param _raise_exc_on_failure: Raises an exception rather than returning a ``None`` value (``True`` by default)
+        :type _raise_exc_on_failure: bool
+        :returns: Boolean value indicating the access level for the given field
+        :raises: :py:exc:`errors.exceptions.InvalidFieldError`
+        """
+        # Raise an exception if a valid access control field is not provided
+        if _field not in VALID_ACCESS_CONTROL_FIELDS:
+            _error_msg = f"The field '{_field}' is not a valid record access level field"
+            raise errors.exceptions.InvalidFieldError(_error_msg)
+
+        # Identify the access level value if possible (API retrievals should be handled in a parent method)
+        _has_access = _record_access_data.get(_field) if _field in _record_access_data else None
+        if _has_access is None:
+            _error_msg = f"The value for the '{_field}' is undefined for the given Record Id '{_record_id}'"
+            logger.error(_error_msg)
+            if _raise_exc_on_failure:
+                raise errors.exceptions.MissingRequiredDataError(_error_msg)
+
+        # Return the identified access level value
+        return _has_access
+
+    def can_access_record(self, access_type, record_id, user_id=None, record_access_data=None, raise_exc_on_failure=True):
+        """This method evaluates if a user can access a specific record given the access type.
+
+        .. version-added:: 1.4.0
+
+        :param access_type: The type of access to evaluate (``read``, ``edit``, or ``delete``)
+        :type access_type: str
+        :param record_id: The ID of the record
+        :type record_id: str
+        :param user_id: The ID of the user to evaluate (defaults to the current/running user if not defined)
+        :type user_id: str, None
+        :param record_access_data: The user record access data that has already been retrieved (optional)
+        :type record_access_data: dict, None
+        :param raise_exc_on_failure: Raises an exception rather than returning a ``None`` value (``True`` by default)
+        :type raise_exc_on_failure: bool
+        :returns: Boolean value indicating the access level for the given field
+        :raises: :py:exc:`errors.exceptions.InvalidFieldError`
+        """
+        # Define the initial value for the result
+        can_access = None
+
+        # Identify the correct field to query based on access type
+        access_type_field_mapping = {
+            'read': 'HasReadAccess',
+            'edit': 'HasEditAccess',
+            'delete': 'HasDeleteAccess',
+        }
+        if access_type.lower() not in access_type_field_mapping:
+            error_msg = f"The access_type '{access_type}' is invalid (must use 'read', 'edit', or 'delete')"
+            logger.error(error_msg)
+            if raise_exc_on_failure:
+                raise errors.exceptions.InvalidParameterError(error_msg)
+        else:
+            # Retrieve the field name to check
+            read_access_field = access_type_field_mapping.get(access_type.lower())
+
+            # Check to see if record access data was provided and validate that it is a dictionary
+            if record_access_data and not isinstance(record_access_data, dict):
+                error_msg = f"The record_access_data provided is Type {type(read_access_field)} but must be a dict"
+                logger.error(error_msg)
+                if raise_exc_on_failure:
+                    raise errors.exceptions.DataMismatchError(error_msg)
+
+            # Perform the API all to check the record access for the user if data not provided
+            if not record_access_data:
+                record_access_data = self.check_user_record_access(record_id=record_id, user_id=user_id)
+
+            # Return the access level value
+            can_access = self._eval_user_record_access(_field=read_access_field, _record_id=record_id,
+                                                       _record_access_data=record_access_data,
+                                                       _raise_exc_on_failure=raise_exc_on_failure)
+
+        # Emit a warning if the value is None rather than a boolean
+        if can_access is None:
+            warn_msg = 'The record access check could not be completed and the function will return a None value'
+            errors.handlers.display_warning(warn_msg)
+
+        # Return the result
+        return can_access
+
+    def can_read_record(self, record_id, user_id=None, record_access_data=None, raise_exc_on_failure=True):
+        """This method evaluates if a user has access to read a specific record.
+
+        .. version-added:: 1.4.0
+
+        :param record_id: The ID of the record
+        :type record_id: str
+        :param user_id: The ID of the user to evaluate (defaults to the current/running user if not defined)
+        :type user_id: str, None
+        :param record_access_data: The user record access data that has already been retrieved (optional)
+        :type record_access_data: dict, None
+        :param raise_exc_on_failure: Raises an exception rather than returning a ``None`` value (``True`` by default)
+        :type raise_exc_on_failure: bool
+        :returns: Boolean value indicating the access level for the given field
+        :raises: :py:exc:`errors.exceptions.InvalidFieldError`
+        """
+        return self.can_access_record(access_type='read', record_id=record_id, user_id=user_id,
+                                      record_access_data=record_access_data,
+                                      raise_exc_on_failure=raise_exc_on_failure)
+
+    def can_edit_record(self, record_id, user_id=None, record_access_data=None, raise_exc_on_failure=True):
+        """This method evaluates if a user has access to edit a specific record.
+
+        .. version-added:: 1.4.0
+
+        :param record_id: The ID of the record
+        :type record_id: str
+        :param user_id: The ID of the user to evaluate (defaults to the current/running user if not defined)
+        :type user_id: str, None
+        :param record_access_data: The user record access data that has already been retrieved (optional)
+        :type record_access_data: dict, None
+        :param raise_exc_on_failure: Raises an exception rather than returning a ``None`` value (``True`` by default)
+        :type raise_exc_on_failure: bool
+        :returns: Boolean value indicating the access level for the given field
+        :raises: :py:exc:`errors.exceptions.InvalidFieldError`
+        """
+        return self.can_access_record(access_type='edit', record_id=record_id, user_id=user_id,
+                                      record_access_data=record_access_data,
+                                      raise_exc_on_failure=raise_exc_on_failure)
+
+    def can_delete_record(self, record_id, user_id=None, record_access_data=None, raise_exc_on_failure=True):
+        """This method evaluates if a user has access to delete a specific record.
+
+        .. version-added:: 1.4.0
+
+        :param record_id: The ID of the record
+        :type record_id: str
+        :param user_id: The ID of the user to evaluate (defaults to the current/running user if not defined)
+        :type user_id: str, None
+        :param record_access_data: The user record access data that has already been retrieved (optional)
+        :type record_access_data: dict, None
+        :param raise_exc_on_failure: Raises an exception rather than returning a ``None`` value (``True`` by default)
+        :type raise_exc_on_failure: bool
+        :returns: Boolean value indicating the access level for the given field
+        :raises: :py:exc:`errors.exceptions.InvalidFieldError`
+        """
+        return self.can_access_record(access_type='edit', record_id=record_id, user_id=user_id,
+                                      record_access_data=record_access_data,
+                                      raise_exc_on_failure=raise_exc_on_failure)
+
     def create_sobject_record(self, sobject, payload):
         """This method creates a new record for a specific sObject.
         (`Reference <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_sobject_create.htm>`_)
@@ -391,7 +724,8 @@ class Salesforce(object):
         :param payload: The JSON payload with the record details
         :type payload: dict
         :returns: The API response from the POST request
-        :raises: :py:exc:`RuntimeError`, :py:exc:`TypeError`
+        :raises: :py:exc:`RuntimeError`,
+                 :py:exc:`TypeError`
         """
         # Ensure the payload is in the appropriate format
         if not isinstance(payload, dict):
@@ -412,7 +746,8 @@ class Salesforce(object):
         :param payload: The JSON payload with the record details to be updated
         :type payload: dict
         :returns: The API response from the PATCH request
-        :raises: :py:exc:`RuntimeError`, :py:exc:`TypeError`
+        :raises: :py:exc:`RuntimeError`,
+                 :py:exc:`TypeError`
         """
         # Ensure the payload is in the appropriate format
         if not isinstance(payload, dict):
@@ -596,7 +931,8 @@ class Salesforce(object):
             :param return_uri: Determines if the URI of the article should be returned rather than the ID (``False`` by default)
             :type return_uri: bool
             :returns: The Article ID or Article URI, or a blank string if no article is found
-            :raises: :py:exc:`ValueError`
+            :raises: :py:exc:`ValueError`,
+                     :py:exc:`RuntimeError`
             """
             return knowledge_module.get_article_id_from_number(self.sfdc_object, article_number=article_number,
                                                                sobject=sobject, return_uri=return_uri)
@@ -616,6 +952,7 @@ class Salesforce(object):
             :param page_num: The starting page number (``1`` by default)
             :type page_num: int
             :returns: The list of retrieved knowledge articles
+            :raises: :py:exc:`RuntimeError`
             """
             return knowledge_module.get_articles_list(self.sfdc_object, query=query, sort=sort, order=order,
                                                       page_size=page_size, page_num=page_num)
@@ -629,6 +966,7 @@ class Salesforce(object):
             :param sobject: The Salesforce object to query (``Knowledge__kav`` by default)
             :type sobject: str, None
             :returns: The details for the knowledge article
+            :raises: :py:exc:`RuntimeError`
             """
             return knowledge_module.get_article_details(self.sfdc_object, article_id=article_id, sobject=sobject)
 
@@ -680,7 +1018,8 @@ class Salesforce(object):
             :param sobject: The Salesforce object to query (``Knowledge__kav`` by default)
             :type sobject: str, None
             :returns: The article URL as a string
-            :raises: :py:exc:`ValueError`
+            :raises: :py:exc:`ValueError`,
+                     :py:exc:`RuntimeError`
             """
             return knowledge_module.get_article_url(self.sfdc_object, article_id=article_id,
                                                     article_number=article_number, sobject=sobject)
@@ -696,7 +1035,9 @@ class Salesforce(object):
             :param full_response: Determines if the full API response should be returned instead of the article ID (``False`` by default)
             :type full_response: bool
             :returns: The API response or the ID of the article draft
-            :raises: :py:exc:`ValueError`, :py:exc:`TypeError`
+            :raises: :py:exc:`ValueError`,
+                     :py:exc:`TypeError`,
+                     :py:exc:`RuntimeError`
             """
             return knowledge_module.create_article(self.sfdc_object, article_data=article_data, sobject=sobject,
                                                    full_response=full_response)
@@ -714,7 +1055,9 @@ class Salesforce(object):
             :param include_status_code: Determines if the API response status code should be returned (``False`` by default)
             :type include_status_code: bool
             :returns: A Boolean indicating if the update operation was successful, and optionally the API response status code
-            :raises: :py:exc:`ValueError`, :py:exc:`TypeError`, :py:exc:`RuntimeError`
+            :raises: :py:exc:`ValueError`,
+                     :py:exc:`TypeError`,
+                     :py:exc:`RuntimeError`
             """
             return knowledge_module.update_article(self.sfdc_object, record_id=record_id, article_data=article_data,
                                                    sobject=sobject, include_status_code=include_status_code)
@@ -781,7 +1124,9 @@ class Salesforce(object):
             :param major_version: Determines if the published article should be a major version (``True`` by default)
             :type major_version: bool
             :returns: The API response from the POST request
-            :raises: :py:exc:`RuntimeError`, :py:exc:`TypeError`, :py:exc:`ValueError`
+            :raises: :py:exc:`RuntimeError`,
+                     :py:exc:`TypeError`,
+                     :py:exc:`ValueError`
             """
             return knowledge_module.publish_multiple_articles(self.sfdc_object, article_id_list=article_id_list,
                                                               major_version=major_version)
@@ -790,7 +1135,7 @@ class Salesforce(object):
             """This method assigns a single data category for a knowledge article.
             (`Reference <https://itsmemohit.medium.com/quick-win-15-salesforce-knowledge-rest-apis-bb0725b2040e>`_)
 
-            .. versionadded:: 1.2.0
+            .. version-added:: 1.2.0
 
             :param article_id: The ID of the article to update
             :type article_id: str
@@ -809,7 +1154,7 @@ class Salesforce(object):
             """This function archives a published knowledge article.
             (`Reference <https://developer.salesforce.com/docs/atlas.en-us.knowledge_dev.meta/knowledge_dev/knowledge_REST_archive_master_version.htm>`_)
 
-            .. versionadded:: 1.3.0
+            .. version-added:: 1.3.0
 
             :param article_id: The ID of the article to archive
             :type article_id: str
@@ -818,6 +1163,23 @@ class Salesforce(object):
             """
             return knowledge_module.archive_article(self.sfdc_object, article_id=article_id)
 
+        def delete_article_draft(self, version_id: str, use_knowledge_management_endpoint: bool = True):
+            """This function deletes an unpublished knowledge article draft.
+
+            .. version-added:: 1.4.0
+
+            :param version_id: The 15-character or 18-character ``Id`` (Knowledge Article Version ID) value
+            :type version_id: str
+            :param use_knowledge_management_endpoint: Leverage the ``/knowledgeManagement/articleVersions/masterVersions/``
+                                                      endpoint rather than the ``/sobjects/Knowledge__kav/`` endpoint
+                                                      (``True`` by default)
+            :type use_knowledge_management_endpoint: bool
+            :returns: The API response from the DELETE request
+            :raises: :py:exc:`RuntimeError`
+            """
+            return knowledge_module.delete_article_draft(self.sfdc_object, version_id=version_id,
+                                                         use_knowledge_management_endpoint=use_knowledge_management_endpoint)
+
 
 def define_connection_info():
     """This function prompts the user for the connection information.

salespyforce/decorators.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            salespyforce.decorators
+:Synopsis:          Decorators that can be used to include additional functionality with functions and methods
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff
+:Modified Date:     02 Feb 2026
+"""
+
+from __future__ import annotations
+
+import functools
+import warnings
+from typing import Any, Callable, Optional, Type, TypeVar
+
+# Define the function Type bound to Callable
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def deprecated(
+    *,
+    since: str,
+    replacement: Optional[str] = None,
+    removal: Optional[str] = None,
+    category: Type[Warning] = DeprecationWarning,
+    stacklevel: int = 2,
+) -> Callable[[F], F]:
+    """This decorator marks a callable as deprecated and emits a warning at runtime.
+
+    .. version-added:: 1.4.0
+
+    :param since: Version when deprecation started
+    :param replacement: Suggested replacement usage (string)
+    :param removal: Version when it will be removed (optional)
+    :param category: Warning category (default: DeprecationWarning)
+    :param stacklevel: Warning stacklevel (default: 2)
+    """
+    def decorator(func: F) -> F:
+        message_parts = [f"{func.__name__} is deprecated since {since}."]
+        if replacement:
+            message_parts.append(f"Use {replacement} instead.")
+        if removal:
+            message_parts.append(f"It will be removed in {removal}.")
+        message = " ".join(message_parts)
+
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any):
+            warnings.warn(message, category=category, stacklevel=stacklevel)
+            return func(*args, **kwargs)
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator

salespyforce/errors/handlers.py

@@ -4,12 +4,50 @@
 :Synopsis:          Functions that handle various error situations within the namespace
 :Created By:        Jeff Shurtliff
 :Last Modified:     Jeff Shurtliff
-:Modified Date:     22 Feb 2023
+:Modified Date:     02 Feb 2026
 """
 
+from __future__ import annotations
+
 import sys
+from typing import Final
+import warnings
+
+# Define constants
+_DEFAULT_CATEGORY: Final[type[Warning]] = UserWarning
 
 
-def eprint(*args, **kwargs):
+def eprint(*args, **kwargs) -> None:
     """This function behaves the same as the ``print()`` function but is leveraged to print errors to ``sys.stderr``."""
     print(*args, file=sys.stderr, **kwargs)
+
+
+def get_exception_type(exc) -> str:
+    """This function returns the exception type (e.g. ``RuntimeError``, ``TypeError``, etc.) for a given exception.
+
+    .. version-added:: 1.4.0
+
+    :returns: The exception type as a string
+    """
+    return type(exc).__name__
+
+
+def display_warning(
+    message: str,
+    *,
+    category: type[Warning] = _DEFAULT_CATEGORY,
+    stacklevel: int = 2,
+) -> None:
+    """This function emits a warning that points to the caller by default.
+
+    .. version-added:: 1.4.0
+
+    :param message: Warning message to emit
+    :type message: str
+    :param category: Warning category class (default: ``UserWarning``)
+    :type category: type[Warning]
+    :param stacklevel: How far up the call stack to attribute the warning (``2`` by default - caller of this helper)
+    :type stacklevel: int
+    :returns: None
+    """
+    warnings.warn(message, category=category, stacklevel=stacklevel)

salespyforce/knowledge.py

@@ -4,7 +4,7 @@
 :Synopsis:          Defines the Knowledge-related functions associated with the Salesforce API
 :Created By:        Jeff Shurtliff
 :Last Modified:     Jeff Shurtliff
-:Modified Date:     14 Nov 2023
+:Modified Date:     03 Feb 2026
 """
 
 from . import errors
@@ -20,7 +20,7 @@ def check_for_existing_article(sfdc_object, title, sobject=None, return_id=False
     (`Reference 1 <https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/dome_query.htm>`_,
     `Reference 2 <https://developer.salesforce.com/docs/atlas.en-us.knowledge_dev.meta/knowledge_dev/knowledge_development_soql_sosl_intro.htm>`_)
 
-    .. versionchanged:: 1.2.2
+    .. version-changed:: 1.2.2
        You can now specify whether archived articles are included in the query results.
 
     :param sfdc_object: The instantiated SalesPyForce object
@@ -230,7 +230,7 @@ def get_article_version(sfdc_object, article_id):
 def get_article_url(sfdc_object, article_id=None, article_number=None, sobject=None):
     """This function constructs the URL to view a knowledge article in Lightning or Classic.
 
-    .. versionchanged:: 1.2.0
+    .. version-changed:: 1.2.0
        Changed when lightning URLs are defined and fixed an issue with extraneous slashes.
 
     :param sfdc_object: The instantiated SalesPyForce object
@@ -483,7 +483,7 @@ def assign_data_category(sfdc_object, article_id, category_group_name, category_
     """This function assigns a single data category for a knowledge article.
     (`Reference <https://itsmemohit.medium.com/quick-win-15-salesforce-knowledge-rest-apis-bb0725b2040e>`_)
 
-    .. versionadded:: 1.2.0
+    .. version-added:: 1.2.0
 
     :param sfdc_object: The instantiated SalesPyForce object
     :type sfdc_object: class[salespyforce.Salesforce]
@@ -512,7 +512,7 @@ def archive_article(sfdc_object, article_id):
     """This function archives a published knowledge article.
     (`Reference <https://developer.salesforce.com/docs/atlas.en-us.knowledge_dev.meta/knowledge_dev/knowledge_REST_archive_master_version.htm>`_)
 
-    .. versionadded:: 1.3.0
+    .. version-added:: 1.3.0
 
     :param sfdc_object: The instantiated SalesPyForce object
     :type sfdc_object: class[salespyforce.Salesforce]
@@ -529,3 +529,26 @@ def archive_article(sfdc_object, article_id):
     # Perform the API call
     endpoint = f'/services/data/{sfdc_object.version}/knowledgeManagement/articleVersions/masterVersions/{article_id}'
     return sfdc_object.patch(endpoint, payload)
+
+
+def delete_article_draft(sfdc_object, version_id: str, use_knowledge_management_endpoint: bool = True):
+    """This function deletes an unpublished knowledge article draft.
+    
+    .. version-added:: 1.4.0
+    
+    :param sfdc_object: The instantiated SalesPyForce object
+    :type sfdc_object: class[salespyforce.Salesforce]
+    :param version_id: The 15-character or 18-character ``Id`` (Knowledge Article Version ID) value
+    :type version_id: str
+    :param use_knowledge_management_endpoint: Leverage the ``/knowledgeManagement/articleVersions/masterVersions/``
+                                              endpoint rather than the ``/sobjects/Knowledge__kav/`` endpoint
+                                              (``True`` by default)
+    :type use_knowledge_management_endpoint: bool
+    :returns: The API response from the DELETE request
+    :raises: :py:exc:`RuntimeError`
+    """
+    if use_knowledge_management_endpoint:
+        endpoint = f'/services/data/{sfdc_object.version}/knowledgeManagement/articleVersions/masterVersions/{version_id}'
+    else:
+        endpoint = f'/services/data/{sfdc_object.version}/sobjects/Knowledge__kav/{version_id}'
+    return sfdc_object.delete(endpoint)

salespyforce/utils/core_utils.py

@@ -6,9 +6,10 @@
 :Example:           ``encoded_string = core_utils.encode_url(decoded_string)``
 :Created By:        Jeff Shurtliff
 :Last Modified:     Jeff Shurtliff
-:Modified Date:     29 May 2023
+:Modified Date:     02 Feb 2026
 """
 
+import re
 import random
 import string
 import os.path
@@ -19,10 +20,15 @@ import requests
 
 from . import log_utils
 from .. import errors
+from ..decorators import deprecated
 
 # Initialize the logger for this module
 logger = log_utils.initialize_logging(__name__)
 
+# Define constants
+SALESFORCE_ID_SUFFIX_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ012345'
+VALID_SALESFORCE_URL_PATTERN = r'^https://[a-zA-Z0-9._-]+\.salesforce\.com(/|$)'
+
 
 def url_encode(raw_string):
     """This function encodes a string for use in URLs.
@@ -44,9 +50,13 @@ def url_decode(encoded_string):
     return urllib.parse.unquote_plus(encoded_string)
 
 
+@deprecated(since='1.4.0', replacement='salespyforce.errors.handlers.display_warning', removal='2.0.0')
 def display_warning(warn_msg):
     """This function displays a :py:exc:`UserWarning` message via the :py:mod:`warnings` module.
 
+    .. deprecated:: 1.4.0
+       Use :py:func:`salespyforce.errors.handlers.display_warning` instead.
+
     :param warn_msg: The message to be displayed
     :type warn_msg: str
     :returns: None
@@ -60,7 +70,8 @@ def get_file_type(file_path):
     :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`
+    :raises: :py:exc:`FileNotFoundError`,
+             :py:exc:`salespyforce.errors.exceptions.UnknownFileTypeError`
     """
     file_type = 'unknown'
     if os.path.isfile(file_path):
@@ -97,6 +108,79 @@ def get_random_string(length=32, prefix_string=""):
     return f"{prefix_string}{''.join([random.choice(string.ascii_letters + string.digits) for _ in range(length)])}"
 
 
+def get_18_char_id(record_id: str) -> str:
+    """This function converts a 15-character Salesforce record ID to its 18-character case-insensitive form.
+
+    .. version-added:: 1.4.0
+
+    :param record_id: The Salesforce record ID to convert (or return unchanged if already 18 characters)
+    :type record_id: str
+    :returns: The 18-character Salesforce record ID
+    :raises: :py:exc:`ValueError`
+    """
+    # Ensure the provided record ID is a string
+    if not isinstance(record_id, str):
+        raise ValueError("Salesforce ID must be a string")
+
+    # Return the record ID unchanged if it is already 18 characters in length
+    if len(record_id) == 18:
+        return record_id
+
+    # Ensure the record ID is a valid 15-character value
+    if len(record_id) != 15:
+        raise ValueError("Salesforce ID must be 15 or 18 characters long")
+
+    # Define the checksum suffix (additional 3 characters)
+    suffix = ""
+    for i in range(0, 15, 5):
+        chunk = record_id[i:i + 5]
+        bitmask = 0
+
+        for index, char in enumerate(chunk):
+            if "A" <= char <= "Z":
+                bitmask |= 1 << index
+
+        suffix += SALESFORCE_ID_SUFFIX_ALPHABET[bitmask]
+
+    # Return the 18-character ID value
+    return record_id + suffix
+
+
+def matches_regex_pattern(pattern: str, text: str, full_match: bool = False, must_start_with: bool = False) -> bool:
+    """This function compares a text string against a regex pattern and determines whether they match.
+
+    .. version-added:: 1.4.0
+
+    :param pattern: The regex pattern that should match
+    :type pattern: str
+    :param text: The text string to evaluate
+    :type text: str
+    :param full_match: Determines if the entire string should be validated
+    :type full_match: bool
+    :param 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: :py:exc:`TypeError`
+    """
+    if full_match:
+        return bool(re.fullmatch(pattern, text))
+    elif must_start_with:
+        return bool(re.match(pattern, text))
+    else:
+        return bool(re.search(pattern, text))
+
+
+def is_valid_salesforce_url(url: str) -> bool:
+    """This function evaluates a URL to determine if it is a valid Salesforce URL.
+
+    .. version-added:: 1.4.0
+
+    :param url: The URL to evaluate
+    :type url: str
+    :returns: Boolean value depending on whether the URL meets the criteria
+    """
+    return True if isinstance(url, str) and matches_regex_pattern(VALID_SALESFORCE_URL_PATTERN, url) else False
+
+
 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>`_,

salespyforce/utils/log_utils.py

@@ -121,7 +121,7 @@ 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
+    :type _logger: class[logging.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
@@ -162,7 +162,7 @@ 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
+    :type _logger: class[logging.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
@@ -174,7 +174,7 @@ def _add_file_handler(_logger, _log_level, _log_file, _overwrite, _formatter):
     :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
+    :type _formatter: class[logging.Formatter]
     :returns: The :py:class:`logging.Logger` instance with the added :py:class:`logging.FileHandler`
     """
     # Define the log file to use
@@ -203,11 +203,11 @@ 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
+    :type _logger: class[logging.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
+    :type _formatter: class[logging.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
@@ -229,11 +229,11 @@ def _add_split_stream_handlers(_logger, _log_level, _formatter):
                  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
+    :type _logger: class[logging.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
+    :type _formatter: class[logging.Formatter]
     :returns: The logger instance with the two handlers added
     """
     # Configure and add the STDOUT handler

salespyforce/utils/tests/test_core_utils.py

@@ -5,7 +5,7 @@
 :Synopsis:       This module is used by pytest to test core utility functions
 :Created By:     Jeff Shurtliff
 :Last Modified:  Jeff Shurtliff
-:Modified Date:  20 Dec 2025
+:Modified Date:  30 Jan 2026
 """
 
 import os
@@ -115,6 +115,45 @@ def test_get_random_string_returns_expected_length(monkeypatch):
     assert all(char in alphabet for char in result.replace("pre_", ""))
 
 
+def test_converts_15_char_id_to_18_char():
+    """This function tests the conversion of a 15-character Salesforce ID into the 18-character equivalent.
+
+    .. version-added:: 1.4.0
+    """
+    id_15 = "ka4PO0000002hby"
+    id_18 = core_utils.get_18_char_id(id_15)
+
+    assert len(id_18) == 18
+    assert id_18.startswith(id_15)
+
+
+def test_returns_18_char_id_unchanged():
+    """This function tests that an 18-character Salesforce ID is returned unchanged during conversion attempt.
+
+    .. version-added:: 1.4.0
+    """
+    id_18 = "ka4PO0000002hbyYAA"
+    assert core_utils.get_18_char_id(id_18) == id_18
+
+
+def test_invalid_id_length_raises_error():
+    """This function tests to ensure passing an invalid Salesforce ID length raises an exception.
+
+    .. version-added:: 1.4.0
+    """
+    with pytest.raises(ValueError):
+        core_utils.get_18_char_id("short")
+
+
+def test_non_string_id_input_raises_error():
+    """This function tests to ensure passing a non-string to the get_18_char_id function raises an exception.
+
+    .. version-added:: 1.4.0
+    """
+    with pytest.raises(ValueError):
+        core_utils.get_18_char_id(12345)
+
+
 def test_get_image_ref_id_parses_query_param():
     """This function tests get_image_ref_id parsing.
 

salespyforce/utils/tests/test_log_utils.py

@@ -22,7 +22,7 @@ def _cleanup_logger(logger: logging.Logger) -> None:
     .. version-added:: 1.4.0
 
     :param logger: The logger instance to clean up
-    :type logger: logging.Logger
+    :type logger: class[logging.Logger]
     :returns: None
     """
     for handler in list(logger.handlers):
@@ -51,7 +51,7 @@ def test_initialize_logging_applies_default_level_to_console_handler(caplog: pyt
     .. version-added:: 1.4.0
 
     :param caplog: Pytest fixture capturing log records for assertions
-    :type caplog: pytest.LogCaptureFixture
+    :type caplog: class[pytest.LogCaptureFixture]
     :returns: None
     """
     logger_name = "salespyforce.test.console.default"

{salespyforce-1.4.0.dev1.dist-info → salespyforce-1.4.0rc0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: salespyforce
-Version: 1.4.0.dev1
+Version: 1.4.0rc0
 Summary: A Python toolset for performing Salesforce API calls
 License: MIT License
          
@@ -63,7 +63,7 @@ A Python toolset for performing Salesforce API calls
         <td>Latest Beta/RC Release</td>
         <td>
             <a href='https://pypi.org/project/salespyforce/#history'>
-                <img alt="PyPI" src="https://img.shields.io/badge/pypi-1.4.0.dev1-blue">
+                <img alt="PyPI" src="https://img.shields.io/badge/pypi-1.4.0.dev2-blue">
             </a>
         </td>
     </tr>
@@ -151,14 +151,6 @@ The package can be installed via pip using the syntax below.
 pip install salespyforce --upgrade
 ```
 
-You may also clone the repository and install from source using below.
-
-```sh
-git clone git://github.com/jeffshurtliff/salespyforce.git
-cd salespyforce/
-python setup.py install
-```
-
 ## Change Log
 The change log can be found in the [documentation](https://salespyforce.readthedocs.io/en/latest/changelog.html).
 

{salespyforce-1.4.0.dev1.dist-info → salespyforce-1.4.0rc0.dist-info}/RECORD

@@ -1,27 +1,28 @@
 salespyforce/__init__.py,sha256=W2RY2_kojLcXtTHJrto5FtU6q1umVPaU1RZe_QkFgNY,2031
-salespyforce/api.py,sha256=JoqYyOo7Psx-l-bEC7iFdFfQVziIkqINcOKOnlpa_jM,5763
+salespyforce/api.py,sha256=NdvPUqJ5HrcaEBaHte414eNOgwIaNweSYxz3E6-zWQE,9403
 salespyforce/chatter.py,sha256=GI9iXmq2mrbrH7daW8Kc3gt2O04dRthSVocJq4BVwCU,7494
-salespyforce/core.py,sha256=OPn5TsY9oCjg_jtEFWCq3yQz4-B7pTeYKsSGOtfo8yI,49148
+salespyforce/core.py,sha256=LW0ImVoN67E78FpmqW9BWHQ7JdNKKFM34Qtjv7oP7WI,68099
+salespyforce/decorators.py,sha256=wSUXM6hXaXwLrD9Gzn0JBj_efHWyJ4n74qg1mel_tcQ,1742
 salespyforce/errors/__init__.py,sha256=Tnl4lB2ycpK2UmwmoBoSYuWDtovDNA4CxC5Cku2hDYs,320
 salespyforce/errors/exceptions.py,sha256=6ATDNCPNXnjOzXcaaLZVUy39lsFt2Se5cCvqkd_8faM,17057
-salespyforce/errors/handlers.py,sha256=8Hp-WrpYooMlC7cuuowTkOFyBH8OQFfHKmB8XxDPlyk,479
-salespyforce/knowledge.py,sha256=YCUbVDr8n23mdUzeuqlNToHIaaD9mzcSZ5Rvr_J8kAw,24770
+salespyforce/errors/handlers.py,sha256=Ykap4LBUTKQSbbAb7OMpWGfwvIx_Rl5aDtgAQ1I9ovk,1556
+salespyforce/knowledge.py,sha256=7TQcPWvHTGUhTUsky9tvOPDCsomaVgahg6gxwMjmdP8,25983
 salespyforce/utils/__init__.py,sha256=ATE6BsWd2qDxsy1fQpvaoSJimZgfCmNPYpcFEucES6Q,292
-salespyforce/utils/core_utils.py,sha256=ESuQVb8L00KoP56_nAKTj3i09u_6BqK0MxJtYV5QbwI,5674
+salespyforce/utils/core_utils.py,sha256=Q-xtBXVkuK50Ps9lLMZuGfFrSM0JxroN_6jcZkyaK6k,8690
 salespyforce/utils/helper.py,sha256=zwbysqwddWwhp3mfzKJf0aeTTkVqoR35L9dLu6ZVJtU,5661
-salespyforce/utils/log_utils.py,sha256=zLQUljJiKU2x8YPG5mo5b5vXAwFLB8DcbrRUOJU14Qw,11831
+salespyforce/utils/log_utils.py,sha256=-7qgSNCUQRstRgz2wXBX6LRWO-GMjIXS5WjxkHGvBHk,11936
 salespyforce/utils/tests/__init__.py,sha256=Iv7M9gPyKv5f5tR-pxc089cd2nrWn5M0ZZpWqiB2htc,242
 salespyforce/utils/tests/conftest.py,sha256=zYB5pYNtRHc6cIxY_cBMQHNM52Is6NjLfcCywCD3-Bw,6661
 salespyforce/utils/tests/resources.py,sha256=-PEqzLMsEQSVj3dz_8VTHXINbSeMvmjX3gZRMTJgoac,4774
-salespyforce/utils/tests/test_core_utils.py,sha256=C8oqr4hQkkAEi36lgbtpwMd6HOoaPXgKVwGA51nIf4w,6132
+salespyforce/utils/tests/test_core_utils.py,sha256=8b3qjzr028wVeQAxBvIeajcqnWCsqUhNgqcquznGQKg,7272
 salespyforce/utils/tests/test_instantiate_object.py,sha256=O_DTljj_QCBZlDiA1KBUmSL2CZfsVU_7K2h6ypEN0D8,2002
-salespyforce/utils/tests/test_log_utils.py,sha256=saUmCNuDUXipfW5YWFtxraLNIqHIl3HwcTU4u9JCBkw,2314
+salespyforce/utils/tests/test_log_utils.py,sha256=FxPC21vXRQbFvqmTi_FL1DsGwuH8JHPkl9XytVoe7uY,2328
 salespyforce/utils/tests/test_sobjects.py,sha256=AeKli_LjSkeaspGxHZoZsM1IafKS2HkJ1wzajSXt6Dc,2120
 salespyforce/utils/tests/test_soql.py,sha256=SSOAN-4QZNpwUON-cLndb5W6AAs28Ja1u-Zt1WBx0VA,776
 salespyforce/utils/tests/test_sosl.py,sha256=3Ny1uF0onjcvI_InfMYRdh31rR5MJADTB3DWSm--EjE,868
 salespyforce/utils/tests/test_version_utils.py,sha256=njRKMiwtCCyUHEAFvfxvavuh03fJ_EupM1TUYmdsZAo,2465
 salespyforce/utils/version.py,sha256=uEWnq3DHmN9wZVohiRCRE1KzNF1XVhP4oVY4vBBgoVU,1781
-salespyforce-1.4.0.dev1.dist-info/LICENSE,sha256=b_Ch0pvcZN6Mr4dQ9Bo3It-J3MihQYcj_-EIdaZHuWw,1071
-salespyforce-1.4.0.dev1.dist-info/METADATA,sha256=ZbUy8c8YPOSLSRL3fQvyZ3KdYQtwR1Hjhv_wyR835w4,10582
-salespyforce-1.4.0.dev1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-salespyforce-1.4.0.dev1.dist-info/RECORD,,
+salespyforce-1.4.0rc0.dist-info/LICENSE,sha256=b_Ch0pvcZN6Mr4dQ9Bo3It-J3MihQYcj_-EIdaZHuWw,1071
+salespyforce-1.4.0rc0.dist-info/METADATA,sha256=uLUbEpNW2OnNfbWXak8I2oXfeQxggGHD2WS2Xl619fM,10398
+salespyforce-1.4.0rc0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+salespyforce-1.4.0rc0.dist-info/RECORD,,