salespyforce 1.4.0.dev2__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:     29 Jan 2026
+: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:
@@ -143,14 +151,14 @@ def delete(sfdc_object, endpoint, params=None, headers=None, timeout=30, show_fu
     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.delete(f'{sfdc_object.instance_url}{endpoint}', headers=headers, params=params,
-                               timeout=timeout)
+    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:
@@ -170,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:     30 Jan 2026
+: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__)
@@ -95,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()
@@ -107,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()
@@ -143,6 +148,34 @@ 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/>`_)
@@ -162,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/>`_)
@@ -439,6 +517,204 @@ class Salesforce(object):
         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>`_)
@@ -887,17 +1163,22 @@ class Salesforce(object):
             """
             return knowledge_module.archive_article(self.sfdc_object, article_id=article_id)
 
-        def delete_article_draft(self, version_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)
+            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():

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:     30 Jan 2026
+:Modified Date:     03 Feb 2026
 """
 
 from . import errors
@@ -531,7 +531,7 @@ def archive_article(sfdc_object, article_id):
     return sfdc_object.patch(endpoint, payload)
 
 
-def delete_article_draft(sfdc_object, version_id):
+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
@@ -540,8 +540,15 @@ def delete_article_draft(sfdc_object, version_id):
     :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`
     """
-    endpoint = f'/services/data/{sfdc_object.version}/sobjects/Knowledge__kav/{version_id}'
+    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:     30 Jan 2026
+:Modified Date:     02 Feb 2026
 """
 
+import re
 import random
 import string
 import os.path
@@ -19,12 +20,14 @@ 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):
@@ -47,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
@@ -139,6 +146,41 @@ def get_18_char_id(record_id: str) -> str:
     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-1.4.0.dev2.dist-info → salespyforce-1.4.0rc0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: salespyforce
-Version: 1.4.0.dev2
+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>

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

@@ -1,13 +1,14 @@
 salespyforce/__init__.py,sha256=W2RY2_kojLcXtTHJrto5FtU6q1umVPaU1RZe_QkFgNY,2031
-salespyforce/api.py,sha256=fSMZYH1bpdZGS2sq924f1we0Bkubx8rrTx810Xyl3Ug,7732
+salespyforce/api.py,sha256=NdvPUqJ5HrcaEBaHte414eNOgwIaNweSYxz3E6-zWQE,9403
 salespyforce/chatter.py,sha256=GI9iXmq2mrbrH7daW8Kc3gt2O04dRthSVocJq4BVwCU,7494
-salespyforce/core.py,sha256=x-D8HsjsRSS7ti1XnwSxKFfqysntI8TttgKBqjsKwh4,52661
+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=5a1kllrggh83vOmFrR-NLaz2YDpoKQweQ1B4e2AwghA,25407
+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=_uVVxHcVwCb-h6m-B7IKY77ItaSsHtGwydZN923yIic,7038
+salespyforce/utils/core_utils.py,sha256=Q-xtBXVkuK50Ps9lLMZuGfFrSM0JxroN_6jcZkyaK6k,8690
 salespyforce/utils/helper.py,sha256=zwbysqwddWwhp3mfzKJf0aeTTkVqoR35L9dLu6ZVJtU,5661
 salespyforce/utils/log_utils.py,sha256=-7qgSNCUQRstRgz2wXBX6LRWO-GMjIXS5WjxkHGvBHk,11936
 salespyforce/utils/tests/__init__.py,sha256=Iv7M9gPyKv5f5tR-pxc089cd2nrWn5M0ZZpWqiB2htc,242
@@ -21,7 +22,7 @@ salespyforce/utils/tests/test_soql.py,sha256=SSOAN-4QZNpwUON-cLndb5W6AAs28Ja1u-Z
 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.dev2.dist-info/LICENSE,sha256=b_Ch0pvcZN6Mr4dQ9Bo3It-J3MihQYcj_-EIdaZHuWw,1071
-salespyforce-1.4.0.dev2.dist-info/METADATA,sha256=7Loir-UVgxd2NpPpLKFQo-0nnt540mMC2ZSh-0uIyxA,10400
-salespyforce-1.4.0.dev2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-salespyforce-1.4.0.dev2.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,,