salespyforce 1.3.0rc3__tar.gz → 1.4.0.dev1__tar.gz

{salespyforce-1.3.0rc3/src/salespyforce.egg-info → salespyforce-1.4.0.dev1}/PKG-INFO

@@ -1,33 +1,51 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: salespyforce
-Version: 1.3.0rc3
+Version: 1.4.0.dev1
 Summary: A Python toolset for performing Salesforce API calls
-Home-page: https://github.com/jeffshurtliff/salespyforce
+License: MIT License
+         
+         Copyright (c) 2023 Jeff Shurtliff
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Keywords: salesforce,sfdc,api,rest,tooling,python
 Author: Jeff Shurtliff
-Author-email: jeff.shurtliff@rsa.com
-Project-URL: Issue Tracker, https://github.com/jeffshurtliff/salespyforce/issues
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Web Environment
-Classifier: Intended Audience :: Information Technology
-Classifier: Intended Audience :: System Administrators
+Author-email: jeffshurtliff@gmail.com
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Natural Language :: English
-Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.6
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
-Classifier: Topic :: Communications
-Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: Content Management System
-Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
-Classifier: Topic :: Office/Business
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.6
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Dist: PyYAML (>=6.0.3,<7)
+Requires-Dist: requests (>=2.32.5)
+Project-URL: Documentation, https://salespyforce.readthedocs.io/en/latest/
+Project-URL: Homepage, https://github.com/jeffshurtliff/salespyforce
+Project-URL: Issue Tracker, https://github.com/jeffshurtliff/salespyforce/issues
+Project-URL: Repository, https://github.com/jeffshurtliff/salespyforce
 Description-Content-Type: text/markdown
-Provides-Extra: sphinx
-License-File: LICENSE
 
 # salespyforce
 A Python toolset for performing Salesforce API calls
@@ -45,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.3.0rc2-blue">
+                <img alt="PyPI" src="https://img.shields.io/badge/pypi-1.4.0.dev1-blue">
             </a>
         </td>
     </tr>
@@ -122,6 +140,10 @@ A Python toolset for performing Salesforce API calls
     </tr>
 </table>
 
+## Overview
+salespyforce is a Python toolkit focused on interacting with Salesforce APIs, with a primary `Salesforce` class 
+that centralizes authentication, version selection, and access to helper feature sets (Chatter, Knowledge).
+
 ## Installation
 The package can be installed via pip using the syntax below.
 
@@ -232,3 +254,4 @@ If you would like to donate to this project then you can do so using [this PayPa
 
 ## Disclaimer
 This package is considered unofficial and is in no way endorsed or supported by [Salesforce Inc](https://www.salesforce.com).
+

{salespyforce-1.3.0rc3 → salespyforce-1.4.0.dev1}/README.md

@@ -14,7 +14,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.3.0rc2-blue">
+                <img alt="PyPI" src="https://img.shields.io/badge/pypi-1.4.0.dev1-blue">
             </a>
         </td>
     </tr>
@@ -91,6 +91,10 @@ A Python toolset for performing Salesforce API calls
     </tr>
 </table>
 
+## Overview
+salespyforce is a Python toolkit focused on interacting with Salesforce APIs, with a primary `Salesforce` class 
+that centralizes authentication, version selection, and access to helper feature sets (Chatter, Knowledge).
+
 ## Installation
 The package can be installed via pip using the syntax below.
 

salespyforce-1.4.0.dev1/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "salespyforce"
+version = "1.4.0.dev1"
+description = "A Python toolset for performing Salesforce API calls"
+readme = "README.md"
+requires-python = ">=3.9,<4.0"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Jeff Shurtliff", email = "jeffshurtliff@gmail.com" }
+]
+keywords = ["salesforce", "sfdc", "api", "rest", "tooling", "python"]
+
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Internet :: WWW/HTTP"
+]
+
+dependencies = [
+  "PyYAML>=6.0.3,<7",
+  "requests>=2.32.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/jeffshurtliff/salespyforce"
+Repository = "https://github.com/jeffshurtliff/salespyforce"
+Documentation = "https://salespyforce.readthedocs.io/en/latest/"
+"Issue Tracker" = "https://github.com/jeffshurtliff/salespyforce/issues"
+
+# --------------------------------------------------------------------
+# Poetry-specific config
+# --------------------------------------------------------------------
+[tool.poetry]
+packages = [
+  { include = "salespyforce", from = "src" }
+]
+
+include = ["LICENSE", "README.md"]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.2"
+bandit = { version = "^1.7.8", extras = ["sarif"] }
+# Sphinx = "^7.0"
+# sphinxcontrib-applehelp = ">=1.0.2"
+# sphinxcontrib-devhelp = ">=1.0.2"
+# sphinxcontrib-htmlhelp = ">=2.0.0"
+# sphinxcontrib-jsmath = ">=1.0.1"
+# sphinxcontrib-qthelp = ">=1.0.3"
+# sphinxcontrib-serializinghtml = ">=1.1.4"
+
+[build-system]
+requires = ["poetry-core>=1.2.0"]
+build-backend = "poetry.core.masonry.api"

{salespyforce-1.3.0rc3 → salespyforce-1.4.0.dev1}/src/salespyforce/core.py

@@ -3,10 +3,10 @@
 :Module:            salespyforce.core
 :Synopsis:          This module performs the core Salesforce-related operations
 :Usage:             ``from salespyforce import Salesforce``
-:Example:           ``sfdc = Salesforce()``
+:Example:           ``sfdc = Salesforce(helper=helper_file_path)``
 :Created By:        Jeff Shurtliff
 :Last Modified:     Jeff Shurtliff
-:Modified Date:     22 Nov 2023
+:Modified Date:     17 Nov 2025
 """
 
 import re
@@ -20,7 +20,7 @@ from .utils import core_utils, log_utils
 from .utils.helper import get_helper_settings
 
 # Define constants
-CURRENT_SFDC_VERSION = '58.0'
+FALLBACK_SFDC_API_VERSION = '65.0'      # Used if querying the org for the version fails
 
 # Initialize logging
 logger = log_utils.initialize_logging(__name__)
@@ -29,14 +29,18 @@ logger = log_utils.initialize_logging(__name__)
 class Salesforce(object):
     """This is the class for the core object leveraged in this module."""
     # Define the function that initializes the object instance (i.e. instantiates the object)
-    def __init__(self, connection_info=None, version=CURRENT_SFDC_VERSION, base_url=None, org_id=None, username=None,
+    def __init__(self, connection_info=None, version=None, base_url=None, org_id=None, username=None,
                  password=None, endpoint_url=None, client_id=None, client_secret=None, security_token=None, helper=None):
         """This method instantiates the core Salesforce object.
 
+        .. version-changed:: 1.4.0
+           The authorized Salesforce org is now queried to determine the latest API version to leverage unless
+           explicitly defined with the ``version`` parameter when instantiating the object.
+
         :param connection_info: The information for connecting to the Salesforce instance
         :type connection_info: dict, None
-        :param version: The Salesforce API version to utilize (Default: ``57.0``)
-        :type version: str
+        :param version: The Salesforce API version to utilize (uses latest version from org if not explicitly defined)
+        :type version: str, None
         :param base_url: The base URL of the Salesforce instance
         :type base_url: str, None
         :param org_id: The Org ID of the Salesforce instance
@@ -93,15 +97,15 @@ class Salesforce(object):
         # Define the base URL value
         self.base_url = self.connection_info.get('base_url')
 
-        # Define the version value
-        self.version = f'v{version}'
-
         # Define the connection response data variables
         auth_response = self.connect()
         self.access_token = auth_response.get('access_token')
         self.instance_url = auth_response.get('instance_url')
         self.signature = auth_response.get('signature')
 
+        # 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()}'
+
         # 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()
@@ -271,12 +275,33 @@ class Salesforce(object):
                                          headers=headers, timeout=timeout, show_full_error=show_full_error,
                                          return_json=return_json)
 
-    def get_api_versions(self):
+    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.
         """
         return self.get('/services/data')
 
+    def get_latest_api_version(self) -> str:
+        """This method returns the latest Salesforce API version by querying the authorized org.
+
+        .. version-added:: 1.4.0
+
+        :returns: The latest Salesforce API version for the authorized org as a string (e.g. ``65.0``)
+        """
+        versions = self.get_api_versions()
+        try:
+            latest_version = versions[-1]['version']
+        except Exception as exc:
+            exc_type = type(exc).__name__
+            logger.warning(
+                f"Failed to retrieve API version due to a(n) {exc_type} exception; defaulting to "
+                f"the fallback version {FALLBACK_SFDC_API_VERSION}"
+            )
+            latest_version = FALLBACK_SFDC_API_VERSION
+        return latest_version
+
     def get_org_limits(self):
         """This method returns a list of all org limits.
 
@@ -357,7 +382,6 @@ class Salesforce(object):
         query = core_utils.url_encode(query)
         return self.get(f'/services/data/{self.version}/search/?q={query}')
 
-
     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>`_)

{salespyforce-1.3.0rc3 → salespyforce-1.4.0.dev1}/src/salespyforce/utils/log_utils.py

@@ -6,7 +6,7 @@
 :Example:           ``logger = log_utils.initialize_logging(__name__)``
 :Created By:        Jeff Shurtliff
 :Last Modified:     Jeff Shurtliff
-:Modified Date:     22 Jan 2023
+:Modified Date:     31 Dec 2025
 """
 
 import os
@@ -59,7 +59,7 @@ class LessThanFilter(logging.Filter):
         self.max_level = exclusive_maximum
 
     def filter(self, record):
-        """This method returns a Boolean integer value indicating whether or not a message should be logged.
+        """This method returns a Boolean integer value indicating whether a message should be logged.
 
         .. note:: A non-zero return indicates that the message will be logged.
         """
@@ -69,6 +69,9 @@ class LessThanFilter(logging.Filter):
 def _apply_defaults(_logger_name, _formatter, _debug, _log_level, _file_level, _console_level, _syslog_level):
     """This function applies default values to the configuration settings if not explicitly defined.
 
+    .. version-changed:: 1.4.0
+       The default logging level is now defined.
+
     :param _logger_name: The name of the logger instance
     :type _logger_name: str, None
     :param _formatter: The log format to utilize for the logger instance
@@ -79,8 +82,9 @@ def _apply_defaults(_logger_name, _formatter, _debug, _log_level, _file_level, _
     :type _log_level: str, None
     :returns: The values that will be used for the configuration settings
     """
+    _default_log_level = LOGGING_DEFAULTS.get('log_level')
     _log_levels = {
-        'general': _log_level,
+        'general': _log_level or _default_log_level,
         'file': _file_level,
         'console': _console_level,
         'syslog': _syslog_level,
@@ -90,12 +94,9 @@ def _apply_defaults(_logger_name, _formatter, _debug, _log_level, _file_level, _
         for _log_type in _log_levels:
             _log_levels[_log_type] = 'debug'
     else:
-        if _log_level:
-            for _lvl_type, _lvl_value in _log_levels.items():
-                if _lvl_type != 'general' and _lvl_value is None:
-                    _log_levels[_lvl_type] = _log_level
-        else:
-            _log_level = LOGGING_DEFAULTS.get('log_level')
+        for _lvl_type, _lvl_value in _log_levels.items():
+            if _lvl_value is None:
+                _log_levels[_lvl_type] = _log_levels['general']
     if _formatter and isinstance(_formatter, str):
         _formatter = logging.Formatter(_formatter)
     _formatter = LOGGING_DEFAULTS.get('formatter') if not _formatter else _formatter

salespyforce-1.4.0.dev1/src/salespyforce/utils/tests/conftest.py

@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+"""
+:Module:            salespyforce.utils.tests.conftest
+:Synopsis:          Configuration for performing unit testing with pytest
+:Usage:             Leveraged by pytest in test modules
+:Example:           ``soql_response = salesforce_unit.soql_query(soql_statement)``
+:Created By:        Jeff Shurtliff
+:Last Modified:     Jeff Shurtliff
+:Modified Date:     13 Dec 2025
+
+Pytest fixtures for ``salespyforce.utils.tests``.
+
+This module centralizes helpers used across the test suite to avoid
+repeated setup in individual test files. It introduces two key fixtures:
+
+* ``salesforce_integration`` — Instantiates the real ``Salesforce``
+  client when a helper file is available. Tests using this fixture are
+  marked as ``integration`` and are skipped unless ``--integration`` is
+  provided.
+* ``salesforce_unit`` — Provides a lightweight stub that mimics the
+  public API used by existing tests without performing any network I/O.
+
+The goal is to make it easy to switch between fast, isolated unit tests
+and opt-in integration runs against a real Salesforce org. Additional
+fixtures can be added here to share common mocking or configuration.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Iterator
+
+import pytest
+
+from salespyforce.core import Salesforce
+
+# Define constants
+HELPER_FILE_NAME = "helper_dm_conn.yml"
+
+
+# -----------------------------
+# Pytest configuration hooks
+# -----------------------------
+
+def pytest_addoption(parser: pytest.Parser) -> None:
+    """This function registers custom CLI options.
+
+    .. version-added:: 1.4.0
+
+    ``--integration`` enables tests that require access to a real
+    Salesforce org. Keeping this opt-in protects routine runs from
+    network or credential dependencies.
+    """
+    parser.addoption(
+        "--integration",
+        action="store_true",
+        default=False,
+        help="run tests that require a Salesforce helper file",
+    )
+
+
+def pytest_configure(config: pytest.Config) -> None:
+    """This function declares custom markers so pytest will not warn during collection.
+
+    .. version-added:: 1.4.0
+    """
+    config.addinivalue_line(
+        "markers",
+        "integration: marks tests that require a real Salesforce org",
+    )
+
+
+def pytest_collection_modifyitems(
+    config: pytest.Config, items: list[pytest.Item]
+) -> None:
+    """This function skips integration tests when ``--integration`` is not provided.
+
+    .. version-added:: 1.4.0
+    """
+    if config.getoption("--integration"):
+        return
+
+    skip_integration = pytest.mark.skip(
+        reason="requires --integration to run against a Salesforce org"
+    )
+    for item in items:
+        if "integration" in item.keywords:
+            item.add_marker(skip_integration)
+
+
+# -----------------------------
+# Helper utilities
+# -----------------------------
+
+def _find_helper_file() -> Path | None:
+    """This function locates a helper file in common locations used by this project.
+
+    .. version-added:: 1.4.0
+    """
+    helper_locations = [
+        Path(os.environ.get("HOME", "")) / "secrets" / HELPER_FILE_NAME,
+        Path("local") / HELPER_FILE_NAME,
+    ]
+    for helper_path in helper_locations:
+        if helper_path.is_file():
+            return helper_path.resolve()
+    return None
+
+
+# -----------------------------
+# Fixtures
+# -----------------------------
+
+@pytest.fixture(scope="session")
+def integration_helper_file() -> Path:
+    """This fixture returns the helper file path or skips the test if none is available.
+
+    .. version-added:: 1.4.0
+
+    Keeping this lookup in a session-scoped fixture ensures we only
+    perform filesystem checks once per test run and provides a single
+    source of truth for integration tests.
+    """
+    helper_path = _find_helper_file()
+    if helper_path is None:
+        pytest.skip("No Salesforce helper file found for integration tests")
+    return helper_path
+
+
+@pytest.fixture(scope="session")
+def salesforce_integration(integration_helper_file: Path) -> Iterator[Salesforce]:
+    """This fixture instantiates the real Salesforce client for integration tests.
+
+    .. version-added:: 1.4.0
+
+    The fixture is session-scoped to avoid repeated authentication and
+    to reuse connections across tests. It is intended only for tests
+    marked with ``@pytest.mark.integration``.
+    """
+    client = Salesforce(helper=str(integration_helper_file))
+    yield client
+
+
+@pytest.fixture()
+def salesforce_unit(monkeypatch: pytest.MonkeyPatch) -> SimpleNamespace:
+    """This fixture provides a lightweight stub that mimics the ``Salesforce`` API.
+
+    .. version-added:: 1.4.0
+
+    This fixture avoids network calls by supplying deterministic return
+    values for the subset of methods exercised by the current tests.
+    It can be extended as coverage grows to keep unit tests fast and
+    self-contained.
+    """
+    # Minimal data used across tests
+    sample_urls = {
+        "base_url": "https://example.force.com",
+        "rest_resources": {"metadata": "available"},
+        "org_limits": {"DailyApiRequests": {"Remaining": 15000}},
+        "sobjects": {"sobjects": []},
+        "account": {
+            "objectDescribe": {},
+            "activateable": False,
+        },
+        "soql_result": {
+            "done": True,
+            "totalSize": 1,
+            "records": [{"Id": "001XX000003NGqqYAG"}],
+        },
+        "sosl_result": {
+            "searchRecords": [
+                {"attributes": {"type": "Account"}, "Id": "001XX000003NGqqYAG"}
+            ]
+        },
+    }
+
+    def _create_response(**overrides):
+        """This function creates an API response payload mimicking the Salesforce REST API responses.
+
+        .. version-added:: 1.4.0
+        """
+        response = {"id": "001D000000IqhSLIAZ", "success": True, "errors": []}
+        response.update(overrides)
+        return response
+
+    stub = SimpleNamespace()
+    stub.base_url = sample_urls["base_url"]
+    stub.get_api_versions = lambda: [{"version": "v65.0"}]
+    stub.get_rest_resources = lambda: sample_urls["rest_resources"]
+    stub.get_org_limits = lambda: sample_urls["org_limits"]
+    stub.get_all_sobjects = lambda: sample_urls["sobjects"]
+    stub.get_sobject = lambda *_args, **_kwargs: sample_urls["account"]
+    stub.describe_object = lambda *_args, **_kwargs: sample_urls["account"]
+    stub.create_sobject_record = (
+        lambda *_args, **_kwargs: _create_response()
+    )
+    stub.soql_query = lambda *_args, **_kwargs: sample_urls["soql_result"]
+    stub.search_string = lambda *_args, **_kwargs: sample_urls["sosl_result"]
+
+    return stub

{salespyforce-1.3.0rc3 → salespyforce-1.4.0.dev1}/src/salespyforce/utils/tests/resources.py

@@ -6,7 +6,7 @@
 :Example:           ``exceptions = resources.import_exceptions_module()``
 :Created By:        Jeff Shurtliff
 :Last Modified:     Jeff Shurtliff
-:Modified Date:     27 May 2023
+:Modified Date:     14 Nov 2025
 """
 
 import os
@@ -17,7 +17,7 @@ import pytest
 
 # Define constants
 SKIP_LOCAL_TEST_MSG = 'skipping local-only tests'
-HELPER_FILE_NAME = 'helper_shurt.yml'
+HELPER_FILE_NAME = 'helper_dm_conn.yml'
 
 
 class MockResponse: