salespyforce 1.4.0.dev0__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,129 @@
+# -*- 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:     17 Feb 2023
+"""
+
+import requests
+
+from .utils import log_utils
+
+# Initialize logging
+logger = log_utils.initialize_logging(__name__)
+
+
+def get(sfdc_object, 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/>`_)
+
+    :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
+
+    # Make sure the endpoint begins with a slash
+    endpoint = f'/{endpoint}' if not endpoint.startswith('/') else endpoint
+
+    # Perform the API call
+    response = requests.get(f'{sfdc_object.instance_url}{endpoint}', headers=headers, params=params, timeout=timeout)
+    if response.status_code >= 300:
+        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.')
+    if return_json:
+        response = response.json()
+    return response
+
+
+def api_call_with_payload(sfdc_object, method, endpoint, payload, params=None, headers=None, timeout=30,
+                          show_full_error=True, return_json=True):
+    """This method performs a POST call against the Salesforce instance.
+    (`Reference <https://jereze.com/code/authentification-salesforce-rest-api-python/>`_)
+
+    :param sfdc_object: The instantiated SalesPyForce object
+    :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, 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
+
+    # Make sure the endpoint begins with a slash
+    endpoint = f'/{endpoint}' if not endpoint.startswith('/') else endpoint
+
+    # 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)
+    elif method.lower() == 'patch':
+        response = requests.patch(f'{sfdc_object.instance_url}{endpoint}', 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)
+    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:
+            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.')
+    if return_json:
+        try:
+            response = response.json()
+        except Exception as exc:
+            print(f'Failed to convert the API response to JSON format due to the following exception: {exc}')
+    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 = {
+        'content-type': 'application/json',
+        'accept-encoding': 'gzip',
+        'authorization': f'Bearer {_access_token}'
+    }
+    if _header_type == 'articles':
+        headers['accept-language'] = 'en-US'
+    return headers

salespyforce/chatter.py

@@ -0,0 +1,167 @@
+# -*- 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:     13 Mar 2023
+"""
+
+from .utils import log_utils
+
+# Initialize logging
+logger = log_utils.initialize_logging(__name__)
+
+
+def _get_site_endpoint_segment(_site_id=None):
+    """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
+    :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=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, site_id=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, site_id=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, message_text=None, message_segments=None, site_id=None, created_by_id=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>`_)
+
+    :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`
+    """
+    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 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, message_text=None, message_segments=None, site_id=None, created_by_id=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_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`
+    """
+    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:
+        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):
+    """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
+