sf-toolkit 0.1.0__tar.gz

sf_toolkit-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Culbreth
+
+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.

sf_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.3
+Name: sf_toolkit
+Version: 0.1.0
+Summary: A Salesforce API Adapter for Python
+License: MIT
+Author: David Culbreth
+Author-email: david.culbreth.256@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: lxml (>=5.3.1,<6.0.0)
+Requires-Dist: more-itertools (>=10.6.0,<11.0.0)
+Requires-Dist: pyjwt (>=2.10.1,<3.0.0)
+Description-Content-Type: text/markdown
+
+# Salesforce Toolkit for Python
+
+A modern, Pythonic interface to Salesforce APIs.
+
+## Features
+
+- Clean, intuitive API design
+- Both synchronous and asynchronous client support
+- Simple SObject modeling using Python classes
+- Powerful query builder for SOQL queries
+- Efficient batch operations
+- Automatic session management and token refresh
+
+## Installation
+
+```bash
+pip install sf-toolkit
+```
+
+## Quick Start
+
+```python
+from sf_toolkit import SalesforceClient, SObject, cli_login
+from sf_toolkit.data.fields import IdField, TextField
+
+# Define a Salesforce object model
+class Account(SObject, api_name="Account"):
+    Id = IdField()
+    Name = TextField()
+    Industry = TextField()
+    Description = TextField()
+
+# Connect to Salesforce using the CLI authentication
+with SalesforceClient(login=cli_login()) as sf:
+    # Create a new account
+    account = Account(Name="Acme Corp", Industry="Technology")
+    account.save()
+
+    # Query accounts
+    query = SoqlSelect(Account)
+    results = query.query()
+
+    for acc in results.records:
+        print(f"{acc.Name} ({acc.Industry})")
+```
+
+## Documentation
+
+For full documentation, visit [docs.example.com](https://docs.example.com).
+### Building the documentation
+
+You can build the documentation locally with:
+
+```bash
+# One-time build
+python -m sphinx -b html docs/source docs/build/html
+
+# Or with auto-reload during development
+sphinx-autobuild docs/source docs/build/html
+```
+
+The documentation is automatically built from docstrings in the code, so make sure to write
+comprehensive docstrings for all public classes and methods.
+
+## License
+
+MIT
+

sf_toolkit-0.1.0/README.md

@@ -0,0 +1,67 @@
+# Salesforce Toolkit for Python
+
+A modern, Pythonic interface to Salesforce APIs.
+
+## Features
+
+- Clean, intuitive API design
+- Both synchronous and asynchronous client support
+- Simple SObject modeling using Python classes
+- Powerful query builder for SOQL queries
+- Efficient batch operations
+- Automatic session management and token refresh
+
+## Installation
+
+```bash
+pip install sf-toolkit
+```
+
+## Quick Start
+
+```python
+from sf_toolkit import SalesforceClient, SObject, cli_login
+from sf_toolkit.data.fields import IdField, TextField
+
+# Define a Salesforce object model
+class Account(SObject, api_name="Account"):
+    Id = IdField()
+    Name = TextField()
+    Industry = TextField()
+    Description = TextField()
+
+# Connect to Salesforce using the CLI authentication
+with SalesforceClient(login=cli_login()) as sf:
+    # Create a new account
+    account = Account(Name="Acme Corp", Industry="Technology")
+    account.save()
+
+    # Query accounts
+    query = SoqlSelect(Account)
+    results = query.query()
+
+    for acc in results.records:
+        print(f"{acc.Name} ({acc.Industry})")
+```
+
+## Documentation
+
+For full documentation, visit [docs.example.com](https://docs.example.com).
+### Building the documentation
+
+You can build the documentation locally with:
+
+```bash
+# One-time build
+python -m sphinx -b html docs/source docs/build/html
+
+# Or with auto-reload during development
+sphinx-autobuild docs/source docs/build/html
+```
+
+The documentation is automatically built from docstrings in the code, so make sure to write
+comprehensive docstrings for all public classes and methods.
+
+## License
+
+MIT

sf_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[tool.poetry]
+name = "sf_toolkit"
+version = "0.1.0"
+description = "A Salesforce API Adapter for Python"
+authors = ["David Culbreth <david.culbreth.256@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.11"
+httpx = "^0.28.1"
+lxml = "^5.3.1"
+more-itertools = "^10.6.0"
+pyjwt = "^2.10.1"
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.5"
+pytest-asyncio = "^0.26.0"
+ruff = "^0.11.2"
+ipykernel = "^6.29.5"
+pytest-cov = "^6.0.0"
+pytest-mock = "^3.14.0"
+pytest-integration-mark = "^0.2.0"
+
+
+[tool.poetry.group.docs.dependencies]
+sphinx = "^8.2.3"
+sphinx-rtd-theme = "^3.0.2"
+sphinx-autobuild = "^2021.3.14"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

sf_toolkit-0.1.0/src/sf_toolkit/__init__.py

@@ -0,0 +1,15 @@
+from .client import SalesforceClient, AsyncSalesforceClient
+from .auth import SalesforceToken, SalesforceAuth, lazy_login, cli_login
+from .data.sobject import SObject
+from .data.query_builder import SoqlSelect
+
+__all__ = [
+    "SalesforceClient",
+    "AsyncSalesforceClient",
+    "SalesforceAuth",
+    "SalesforceToken",
+    "SObject",
+    "SoqlSelect",
+    "lazy_login",
+    "cli_login",
+]

sf_toolkit-0.1.0/src/sf_toolkit/_models.py

@@ -0,0 +1,69 @@
+from typing import TypedDict, Generic, TypeVar, NamedTuple
+
+
+class SObjectAttributes(NamedTuple):
+    type: str
+    connection: str
+    id_field: str
+    tooling: bool
+
+
+class SObjectDictAttrs(TypedDict):
+    type: str
+    url: str
+
+
+class SObjectDict(TypedDict, total=False):
+    attributes: SObjectDictAttrs
+
+
+class SObjectSaveError(NamedTuple):
+    statusCode: str
+    message: str
+    fields: list[str]
+
+    def __str__(self):
+        return f"({self.statusCode}) {self.message} ({', '.join(self.fields)})"
+
+
+class SObjectSaveResult:
+    id: str
+    success: bool
+    errors: list[SObjectSaveError]
+    created: bool | None
+
+    def __init__(
+        self,
+        id: str,
+        success: bool,
+        errors: list[SObjectSaveError | dict],
+        created: bool | None = None,
+    ):
+        self.id = id
+        self.success = success
+        self.errors = [
+            error if isinstance(error, SObjectSaveError) else SObjectSaveError(**error)
+            for error in errors
+        ]
+        self.created = created
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} id:{self.id} success:{self.success} errors:[{', '.join(map(str, self.errors))}]>"
+
+    def __str__(self):
+        message = f"Save Result for record {self.id} | "
+        message += "SUCCESS" if self.success else "FAILURE"
+        if self.errors:
+            message += "\n errors:[\n  " + "\n  ".join(map(str, self.errors)) + "\n]"
+
+        return message
+
+
+SObjectRecordJSON = TypeVar("SObjectRecordJSON", bound=SObjectDict)
+
+
+class QueryResultJSON(TypedDict, Generic[SObjectRecordJSON]):
+    totalSize: int
+    done: bool
+    nextRecordsUrl: str
+    records: list[SObjectRecordJSON]

sf_toolkit-0.1.0/src/sf_toolkit/apimodels.py

@@ -0,0 +1,220 @@
+from typing import TypeVar
+
+
+_T_ApiVer = TypeVar("_T_ApiVer", bound="ApiVersion")
+
+
+class ApiVersion:
+    """
+    Data structure representing a Salesforce API version.
+    https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_versions.htm
+    """
+
+    version: float
+    label: str
+    url: str
+
+    def __init__(self, version: float | str, label: str, url: str):
+        """
+        Initialize an ApiVersion object.
+
+        Args:
+            version: The API version number as a float
+            label: The display label for the API version
+            url: The URL for accessing this API version
+        """
+        self.version = float(version)
+        self.label = label
+        self.url = url
+
+    @classmethod
+    def lazy_build(cls, value) -> "ApiVersion":
+        if isinstance(value, cls):
+            return value
+        elif isinstance(value, str):
+            if value.startswith("/services/data/v"):
+                version_number = float(value.removeprefix("/services/data/v"))
+                return cls(version_number, f"{version_number:.01f}", value)
+            else:
+                # attempt to isolate version number from any other characters
+                value = "".join(c for c in value if c.isdigit() or c == ".")
+                version_number = float(value)
+                return cls(
+                    version_number,
+                    f"{version_number:.01f}",
+                    f"/services/data/v{version_number:.01f}",
+                )
+
+        elif isinstance(value, float):
+            return cls(value, f"{value:.01f}", f"/services/data/v{value:.01f}")
+
+        elif isinstance(value, int):
+            value = float(value)
+            return cls(value, f"{value:.01f}", f"/services/data/v{value:.01f}")
+
+        elif isinstance(value, dict):
+            return cls(**value)
+
+        raise TypeError("Unable to build an ApiVersion from value %s", repr(value))
+
+
+        raise TypeError("Unable to build an ApiVersion from value %s", repr(value))
+
+    def __repr__(self) -> str:
+        return f"ApiVersion(version={self.version}, label='{self.label}')"
+
+    def __str__(self) -> str:
+        return f"Salesforce API Version {self.label} ({self.version:.01f})"
+
+    def __float__(self) -> float:
+        return self.version
+
+    def __eq__(self, other) -> bool:
+        if isinstance(other, ApiVersion):
+            return self.version == other.version and self.url == other.url
+        elif isinstance(other, (int, float)):
+            return self.version == float(other)
+        return False
+
+    def __hash__(self) -> int:
+        return hash(self.version)
+
+
+class OrgLimit:
+    """
+    Data structure representing a Salesforce Org Limit.
+    https://developer.salesforce.com/docs/atlas.en-us.api_rest.meta/api_rest/resources_limits.htm
+    """
+
+    def __init__(self, name: str, max_value: int, current_value: int):
+        """
+        Initialize an OrgLimit object.
+
+        Args:
+            name: The name of the limit
+            max_value: The maximum allowed value for this limit
+            current_value: The current consumption value for this limit
+        """
+        self.name = name
+        self.max_value = max_value
+        self.current_value = current_value
+
+    def __repr__(self) -> str:
+        return f"OrgLimit(name='{self.name}', current_value={self.current_value}, max_value={self.max_value})"
+
+    def remaining(self) -> int:
+        """
+        Calculate the remaining capacity for this limit.
+
+        Returns:
+            The difference between max_value and current_value
+        """
+        return self.max_value - self.current_value
+
+    def usage_percentage(self) -> float:
+        """
+        Calculate the percentage of the limit that has been used.
+
+        Returns:
+            The percentage of the limit used as a float between 0 and 100
+        """
+        if self.max_value == 0:
+            return 0.0
+        return (self.current_value / self.max_value) * 100
+
+    def is_critical(self, threshold: float = 90.0) -> bool:
+        """
+        Determine if the limit usage exceeds a critical threshold.
+
+        Args:
+            threshold: The percentage threshold to consider critical (default: 90%)
+
+        Returns:
+            True if usage percentage exceeds the threshold, False otherwise
+        """
+        return self.usage_percentage() >= threshold
+
+
+class UserInfo:
+    """
+    Data structure representing user information returned from the Salesforce OAuth2 userinfo endpoint.
+    https://help.salesforce.com/s/articleView?id=sf.remoteaccess_using_userinfo_endpoint.htm
+    """
+
+    def __init__(
+        self,
+        user_id: str,
+        name: str,
+        email: str,
+        organization_id: str,
+        sub: str,
+        email_verified: bool,
+        given_name: str,
+        family_name: str,
+        zoneinfo: str,
+        photos: dict[str, str],
+        profile: str,
+        picture: str,
+        address: dict,
+        urls: dict[str, str],
+        active: bool,
+        user_type: str,
+        language: str,
+        locale: str,
+        utcOffset: int,
+        updated_at: str,
+        preferred_username: str,
+        **kwargs,
+    ):
+        """
+        Initialize a UserInfo object.
+
+        Args:
+            user_id: The user's Salesforce ID
+            name: The user's full name
+            email: The user's email address
+            organization_id: The organization's Salesforce ID
+            sub: Subject identifier
+            email_verified: Whether the email has been verified
+            given_name: The user's first name
+            family_name: The user's last name
+            zoneinfo: The user's timezone (e.g., "America/Los_Angeles")
+            photos: Dictionary of profile photos (picture, thumbnail)
+            profile: URL to the user's profile
+            picture: URL to the user's profile picture
+            address: Dictionary containing address information
+            urls: Dictionary of various API endpoints for this user
+            active: Whether the user is active
+            user_type: The type of user (e.g., "STANDARD")
+            language: The user's language preference
+            locale: The user's locale setting
+            utcOffset: The user's UTC offset in milliseconds
+            updated_at: When the user information was last updated
+            preferred_username: The user's preferred username (typically email)
+            **kwargs: Additional attributes from the response
+        """
+        self.user_id = user_id
+        self.name = name
+        self.email = email
+        self.organization_id = organization_id
+        self.sub = sub
+        self.email_verified = email_verified
+        self.given_name = given_name
+        self.family_name = family_name
+        self.zoneinfo = zoneinfo
+        self.photos = photos or {}
+        self.profile = profile
+        self.picture = picture
+        self.address = address or {}
+        self.urls = urls or {}
+        self.active = active
+        self.user_type = user_type
+        self.language = language
+        self.locale = locale
+        self.utcOffset = utcOffset
+        self.updated_at = updated_at
+        self.preferred_username = preferred_username
+        self.additional_info = kwargs
+
+    def __repr__(self) -> str:
+        return f"UserInfo(name='{self.name}', user_id='{self.user_id}', organization_id='{self.organization_id}')"

sf_toolkit-0.1.0/src/sf_toolkit/async_utils.py

@@ -0,0 +1,31 @@
+from asyncio import BoundedSemaphore, gather
+from collections.abc import Iterable
+from typing import Callable, TypeVar, Awaitable
+from types import CoroutineType
+
+T = TypeVar("T")
+
+
+async def run_concurrently(
+    limit: int,
+    coroutines: Iterable[Awaitable[T]],
+    task_callback: Callable[[T], Awaitable[None] | None] | None = None,
+) -> list[T]:
+    """Runs the provided coroutines with maxumum `n` concurrently running."""
+    semaphore = BoundedSemaphore(limit)
+
+    async def bounded_task(task: Awaitable[T]):
+        async with semaphore:
+            result = await task
+            if task_callback:
+                callback_result = task_callback(result)
+                if isinstance(callback_result, CoroutineType):
+                    await callback_result
+            return result
+
+    # Wrap all coroutines in the semaphore-controlled task
+    tasks = [bounded_task(coro) for coro in coroutines]
+
+    # Run and wait for all tasks to complete
+    results: list[T] = await gather(*tasks)
+    return results

sf_toolkit-0.1.0/src/sf_toolkit/auth/__init__.py

@@ -0,0 +1,33 @@
+from .httpx import SalesforceAuth
+from .types import SalesforceLogin, SalesforceToken, TokenRefreshCallback
+from .login_lazy import lazy_login
+from .login_cli import cli_login
+from .login_soap import (
+    ip_filtering_non_service_login,
+    ip_filtering_org_login,
+    security_token_login,
+    lazy_soap_login,
+)
+from .login_oauth import (
+    lazy_oauth_login,
+    password_login,
+    public_key_auth_login,
+    client_credentials_flow_login,
+)
+
+__all__ = [
+    "SalesforceAuth",
+    "SalesforceLogin",
+    "SalesforceToken",
+    "TokenRefreshCallback",
+    "lazy_login",
+    "cli_login",
+    "ip_filtering_non_service_login",
+    "ip_filtering_org_login",
+    "security_token_login",
+    "lazy_soap_login",
+    "lazy_oauth_login",
+    "password_login",
+    "public_key_auth_login",
+    "client_credentials_flow_login",
+]

sf_toolkit-0.1.0/src/sf_toolkit/auth/httpx.py

@@ -0,0 +1,76 @@
+import typing
+
+import httpx
+
+from ..logger import getLogger
+from .types import SalesforceLogin, SalesforceToken, TokenRefreshCallback
+
+LOGGER = getLogger("auth")
+
+
+class SalesforceAuth(httpx.Auth):
+    login: SalesforceLogin | None
+    callback: TokenRefreshCallback | None
+    token: SalesforceToken | None
+
+    def __init__(
+        self,
+        login: SalesforceLogin | None = None,
+        session_token: SalesforceToken | None = None,
+        callback: TokenRefreshCallback | None = None,
+    ):
+        self.login = login
+        self.token = session_token
+        self.callback = callback
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> typing.Generator[httpx.Request, httpx.Response, None]:
+        if self.token is None or request.url.is_relative_url:
+            assert self.login is not None, "No login method provided"
+            try:
+                login_flow = self.login()
+                login_request = next(login_flow)
+                while True:
+                    if login_request is not None:
+                        login_response = yield login_request
+                        login_request = login_flow.send(login_response)
+                    else:
+                        login_request = next(login_flow)
+
+            except StopIteration as login_result:
+                new_token: SalesforceToken = login_result.value
+                self.token = SalesforceToken(*new_token)
+                if self.callback is not None:
+                    self.callback(new_token)
+            assert self.token is not None, "Failed to perform initial login"
+
+        if request.url.is_relative_url:
+            absolute_url = self.token.instance.raw_path + request.url.raw_path.lstrip(
+                b"/"
+            )
+            request.url = self.token.instance.copy_with(raw_path=absolute_url)
+            request._prepare({**request.headers})
+
+        request.headers["Authorization"] = f"Bearer {self.token.token}"
+        response = yield request
+
+        if (
+            response.status_code == 401
+            and self.login
+            and response.json()[0]["errorDetails"] == "INVALID_SESSION_ID"
+        ):
+            try:
+                for login_request in (login_flow := self.login()):
+                    if login_request is not None:
+                        login_response = yield login_request
+                        login_flow.send(login_response)
+
+            except StopIteration as login_result:
+                new_token: SalesforceToken = login_result.value
+                self.token = new_token
+                if self.callback is not None:
+                    self.callback(new_token)
+
+            request.headers["Authorization"] = f"Bearer {self.token.token}"
+            response = yield request