salespyforce 1.4.0__py3-none-any.whl

salespyforce/__init__.py

@@ -0,0 +1,53 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            salespyforce
+:Synopsis:          This is the ``__init__`` module for the salespyforce package
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff
+:Modified Date:     08 May 2023
+"""
+
+from . import core
+from .core import Salesforce
+from .utils import version
+
+__all__ = ['core', 'Salesforce']
+
+# Define the package version by pulling from the highspot.utils.version module
+__version__ = version.get_full_version()
+
+
+# Allow the core.define_connection_info() function to be executed directly
+def define_connection_info():
+    """This function prompts the user for the connection information.
+
+    :returns: The connection info in a dictionary
+    """
+    return core.define_connection_info()
+
+
+# Allow the core.compile_connection_info() function to be executed directly
+def compile_connection_info(base_url, org_id, username, password, endpoint_url,
+                            client_id, client_secret, security_token):
+    """This function compiles the connection info into a dictionary that can be consumed by the core object.
+
+    :param base_url: The base URL of the Salesforce instance
+    :type base_url: str
+    :param org_id: The Org ID of the Salesforce instance
+    :type org_id: str
+    :param username: The username of the API user
+    :type username: str
+    :param password: The password of the API user
+    :type password: str
+    :param endpoint_url: The endpoint URL for the Salesforce instance
+    :type endpoint_url: str
+    :param client_id: The Client ID for the Salesforce instance
+    :type client_id: str
+    :param client_secret: The Client Secret for the Salesforce instance
+    :type client_secret: str
+    :param security_token: The Security Token for the Salesforce instance
+    :type security_token: str
+    :returns: The connection info in a dictionary
+    """
+    return core.compile_connection_info(base_url, org_id, username, password, endpoint_url,
+                                        client_id, client_secret, security_token)

salespyforce/api.py

@@ -0,0 +1,272 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            salespyforce.api
+:Synopsis:          Defines the basic functions associated with the Salesforce API
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff
+:Modified Date:     03 Feb 2026
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import requests
+
+from . import errors
+from .utils import core_utils, log_utils
+
+# Define constants
+DEFAULT_API_REQUEST_TIMEOUT = 30
+
+# Initialize logging
+logger = log_utils.initialize_logging(__name__)
+
+
+def get(
+        sfdc_object,
+        endpoint: str,
+        params: Optional[dict] = None,
+        headers: Optional[dict] = None,
+        timeout: Optional[int] = None,
+        show_full_error: bool = True,
+        return_json: bool = True,
+):
+    """This method performs a GET request against the Salesforce instance.
+    (`Reference <https://jereze.com/code/authentification-salesforce-rest-api-python/>`_)
+
+    .. versionchanged:: 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. Additionally, a global constant is now leveraged
+       for the API timeout value instead of hardcoding the value. (Timeout is still **30** seconds in this version)
+
+    :param sfdc_object: The instantiated SalesPyForce object
+    :type sfdc_object: class[salespyforce.Salesforce]
+    :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, 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:`TypeError`,
+             :py:exc:`RuntimeError`,
+             :py:exc:`salespyforce.errors.exceptions.InvalidURLError`
+    """
+    # 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)
+
+    # Define the API request timeout (using default value if not explicitly defined with parameter)
+    timeout = DEFAULT_API_REQUEST_TIMEOUT if not timeout else timeout
+
+    # Perform the API call
+    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}')
+        else:
+            raise RuntimeError(f'The GET request failed with a {response.status_code} status code.')
+    # TODO: Leverage private function for this section across all API call functions (see TODO in api_call_with_payload)
+    if return_json:
+        response = response.json()
+    return response
+
+
+def api_call_with_payload(
+        sfdc_object,
+        method: str,
+        endpoint: str,
+        payload: dict,
+        params: Optional[dict] = None,
+        headers: Optional[dict] = None,
+        timeout: Optional[int] = None,
+        show_full_error: bool = True,
+        return_json: bool = True,
+):
+    """This method performs a POST call against the Salesforce instance.
+    (`Reference <https://jereze.com/code/authentification-salesforce-rest-api-python/>`_)
+
+    .. versionchanged:: 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. Additionally, a global constant is now leveraged
+       for the API timeout value instead of hardcoding the value. (Timeout is still **30** seconds in this version)
+
+    :param sfdc_object: The instantiated SalesPyForce object
+    :type sfdc_object: class[salespyforce.Salesforce]
+    :param method: The API method (``post``, ``put``, or ``patch``)
+    :type method: str
+    :param endpoint: The API endpoint to query
+    :type endpoint: str
+    :param payload: The payload to leverage in the API call
+    :type payload: dict
+    :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, 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:`TypeError`,
+             :py:exc:`RuntimeError`,
+             :py:exc:`ValueError`,
+             :py:exc:`salespyforce.errors.exceptions.InvalidURLError`
+    """
+    # 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)
+
+    # Define the API request timeout (using default value if not explicitly defined with parameter)
+    timeout = DEFAULT_API_REQUEST_TIMEOUT if not timeout else timeout
+
+    # Perform the API call
+    if method.lower() == 'post':
+        response = requests.post(url, json=payload, headers=headers, params=params, timeout=timeout)
+    elif method.lower() == 'patch':
+        response = requests.patch(url, json=payload, headers=headers, params=params, timeout=timeout)
+    elif method.lower() == 'put':
+        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')
+
+    # 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:
+            raise RuntimeError(f'The POST request failed with a {response.status_code} status code.')
+    # TODO: Break this out into a separate private function so it can be reused and standardized
+    if return_json:
+        try:
+            response = response.json()
+        except Exception as exc:
+            # TODO: log the exception rather than using a print statement
+            print(f'Failed to convert the API response to JSON format due to the following exception: {exc}')
+    return response
+
+
+def delete(
+        sfdc_object,
+        endpoint: str,
+        params: Optional[dict] = None,
+        headers: Optional[dict] = None,
+        timeout: Optional[int] = None,
+        show_full_error: bool = True,
+        return_json: bool = True):
+    """This method performs a DELETE request against the Salesforce instance.
+
+    .. versionadded:: 1.4.0
+
+    :param sfdc_object: The instantiated SalesPyForce object
+    :type sfdc_object: class[salespyforce.Salesforce]
+    :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, 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:`TypeError`,
+             :py:exc:`RuntimeError`,
+             :py:exc:`salespyforce.errors.exceptions.InvalidURLError`
+    """
+    # 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)
+
+    # Define the API request timeout (using default value if not explicitly defined with parameter)
+    timeout = DEFAULT_API_REQUEST_TIMEOUT if not timeout else timeout
+
+    # 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.')
+    # TODO: Leverage private function for this section across all API call functions (see TODO in api_call_with_payload)
+    if return_json:
+        response = response.json()
+    return response
+
+
+def _get_headers(_access_token: str, _header_type: str = 'default') -> dict:
+    """This function returns the appropriate HTTP headers to use for different types of API calls."""
+    headers = {
+        'content-type': 'application/json',
+        'accept-encoding': 'gzip',
+        'authorization': f'Bearer {_access_token}'
+    }
+    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.
+
+    .. versionadded:: 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:`salespyforce.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/chatter.py

@@ -0,0 +1,192 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            salespyforce.chatter
+:Synopsis:          Defines the Chatter-related functions associated with the Salesforce Connect API
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff
+:Modified Date:     03 Feb 2026
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from . import errors
+from .utils import log_utils
+
+# Initialize logging
+logger = log_utils.initialize_logging(__name__)
+
+
+def _get_site_endpoint_segment(_site_id: Optional[str] = None) -> str:
+    """This function constructs the endpoint segment when querying a specific Experience Cloud site.
+
+    :param _site_id: The Site ID of the Experience Cloud site
+    :type _site_id: str, None
+    :returns: The API endpoint segment (or a blank string if no Site ID was provided)
+    """
+    _endpoint_segment = f'/connect/communities/{_site_id}' if _site_id else ''
+    return _endpoint_segment
+
+
+def get_my_news_feed(sfdc_object, site_id: Optional[str] = None):
+    """This function retrieves the news feed for the user calling the function.
+    (`Reference <https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/quickreference_get_news_feed.htm>`_)
+
+    :param sfdc_object: The instantiated SalesPyForce object
+    :type sfdc_object: class[salespyforce.Salesforce]
+    :param site_id: The ID of an Experience Cloud site against which to query (optional)
+    :type site_id: str, None
+    :returns: The news feed data
+    :raises: :py:exc:`RuntimeError`
+    """
+    site_segment = _get_site_endpoint_segment(site_id)
+    endpoint = f'/services/data/{sfdc_object.version}{site_segment}/chatter/feeds/news/me/feed-elements'
+    return sfdc_object.get(endpoint)
+
+
+def get_user_news_feed(sfdc_object, user_id: str, site_id: Optional[str] = None):
+    """This function retrieves another user's news feed.
+    (`Reference <https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/quickreference_get_user_profile_feed.htm>`_)
+
+    :param sfdc_object: The instantiated SalesPyForce object
+    :type sfdc_object: class[salespyforce.Salesforce]
+    :param user_id: The ID of the user whose feed you wish to return
+    :type user_id: str
+    :param site_id: The ID of an Experience Cloud site against which to query (optional)
+    :type site_id: str, None
+    :returns: The news feed data
+    :raises: :py:exc:`RuntimeError`
+    """
+    site_segment = _get_site_endpoint_segment(site_id)
+    endpoint = f'/services/data/{sfdc_object.version}{site_segment}/chatter/feeds/user-profile/{user_id}/feed-elements'
+    return sfdc_object.get(endpoint)
+
+
+def get_group_feed(sfdc_object, group_id: str, site_id: Optional[str] = None):
+    """This function retrieves a group's news feed.
+    (`Reference <https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/quickreference_get_group_feed.htm>`_)
+
+    :param sfdc_object: The instantiated SalesPyForce object
+    :type sfdc_object: class[salespyforce.Salesforce]
+    :param group_id: The ID of the group whose feed you wish to return
+    :type group_id: str
+    :param site_id: The ID of an Experience Cloud site against which to query (optional)
+    :type site_id: str, None
+    :returns: The news feed data
+    :raises: :py:exc:`RuntimeError`
+    """
+    site_segment = _get_site_endpoint_segment(site_id)
+    endpoint = f'/services/data/{sfdc_object.version}{site_segment}/chatter/feeds/record/{group_id}/feed-elements'
+    return sfdc_object.get(endpoint)
+
+
+def post_feed_item(
+        sfdc_object,
+        subject_id: str,
+        message_text: Optional[str] = None,
+        message_segments: Optional[list] = None,
+        site_id: Optional[str] = None,
+        created_by_id: Optional[str] = None,
+):
+    """This function publishes a new Chatter feed item.
+    (`Reference <https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/quickreference_post_feed_item.htm>`_)
+
+    .. versionchanged:: 1.4.0
+       The function now raises the :py:exc:`salespyforce.errors.exceptions.MissingRequiredDataError` exception rather than the
+       generic :py:exc:`RuntimeError` exception.
+
+    :param sfdc_object: The instantiated SalesPyForce object
+    :type sfdc_object: class[salespyforce.Salesforce]
+    :param subject_id: The Subject ID against which to publish the feed item (e.g. ``0F9B000000000W2``)
+    :type subject_id: str
+    :param message_text: Plaintext to be used as the message body
+    :type message_segments: str, None
+    :param message_segments: Collection of message segments to use instead of a plaintext message
+    :type message_segments: list, None
+    :param site_id: The ID of an Experience Cloud site against which to query (optional)
+    :type site_id: str, None
+    :param created_by_id: The ID of the user to impersonate (**Experimental**)
+    :type created_by_id: str, None
+    :returns: The response of the POST request
+    :raises: :py:exc:`RuntimeError`,
+             :py:exc:`salespyforce.errors.exceptions.MissingRequiredDataError`
+    """
+    site_segment = _get_site_endpoint_segment(site_id)
+    if not any((message_text, message_segments)):
+        raise errors.exceptions.MissingRequiredDataError('Message text or message segments are required to post a feed item.')
+    if not message_segments:
+        message_segments = _construct_simple_message_segment(message_text)
+    body = {
+        'body': {
+            'messageSegments': message_segments
+        },
+        'feedElementType': 'FeedItem',
+        'subjectId': subject_id,
+    }
+    if created_by_id:
+        body['createdById'] = created_by_id
+    endpoint = f'/services/data/{sfdc_object.version}{site_segment}/chatter/feed-elements?' \
+               f'feedElementType=FeedItem&subjectId={subject_id}'
+    return sfdc_object.post(endpoint=endpoint, payload=body)
+
+
+def post_comment(
+        sfdc_object,
+        feed_element_id: str,
+        message_text: Optional[str] = None,
+        message_segments: Optional[list] = None,
+        site_id: Optional[str] = None,
+        created_by_id: Optional[str] = None,
+):
+    """This function publishes a comment on a Chatter feed item.
+    (`Reference <https://developer.salesforce.com/docs/atlas.en-us.chatterapi.meta/chatterapi/quickreference_post_comment_to_feed_element.htm>`_)
+
+    :param sfdc_object: The instantiated SalesPyForce object
+    :type sfdc_object: class[salespyforce.Salesforce]
+    :param feed_element_id: The ID of the feed element on which to post the comment
+    :type feed_element_id: str
+    :param message_text: Plaintext to be used as the message body
+    :type message_text: str, None
+    :param message_segments: Collection of message segments to use instead of a plaintext message
+    :type message_segments: list, None
+    :param site_id: The ID of an Experience Cloud site against which to query (optional)
+    :type site_id: str, None
+    :param created_by_id: The ID of the user to impersonate (**Experimental**)
+    :type created_by_id: str, None
+    :returns: The response of the POST request
+    :raises: :py:exc:`RuntimeError`
+    """
+    site_segment = _get_site_endpoint_segment(site_id)
+    if not any((message_text, message_segments)):
+        raise RuntimeError('Message text or message segments are required to post a feed comment.')
+
+    if not message_segments:
+        message_segments = _construct_simple_message_segment(message_text)
+    body = {
+        'body': {
+            'messageSegments': message_segments
+        }
+    }
+    if created_by_id:
+        # noinspection PyTypeChecker
+        body['createdById'] = created_by_id
+    endpoint = f'/services/data/{sfdc_object.version}{site_segment}/chatter/feed-elements/' \
+               f'{feed_element_id}/capabilities/comments/items'
+    return sfdc_object.post(endpoint=endpoint, payload=body)
+
+
+def _construct_simple_message_segment(_message_text: str) -> list:
+    """This function constructs a simple message segments collection to be used in an API payload.
+
+    :param _message_text: The plaintext message to be embedded in a message segment.
+    :type _message_text: str
+    :returns: The constructed message segments payload
+    """
+    _message_segments = [
+        {
+            'type': 'text',
+            'text': _message_text
+        }
+    ]
+    return _message_segments