aio-sf 0.1.0b1__py3-none-any.whl

aio_salesforce/api/describe/types.py

@@ -0,0 +1,303 @@
+"""
+TypedDict definitions for Salesforce API responses.
+"""
+
+from typing import Any, Dict, List, Optional, TypedDict, Union
+
+
+class SalesforceAttributes(TypedDict):
+    """Standard Salesforce record attributes."""
+
+    type: str
+    url: str
+
+
+class OrganizationInfo(TypedDict):
+    """Organization information from SOQL query."""
+
+    attributes: SalesforceAttributes
+    Id: str
+    Name: str
+    OrganizationType: str
+    InstanceName: str
+    IsSandbox: bool
+
+
+class LimitInfo(TypedDict):
+    """Individual limit information."""
+
+    Max: int
+    Remaining: int
+
+
+class OrganizationLimits(TypedDict, total=False):
+    """Organization limits - using total=False since keys vary by org."""
+
+    # API Limits
+    DailyApiRequests: LimitInfo
+    DailyBulkApiBatches: LimitInfo
+    DailyBulkV2QueryJobs: LimitInfo
+    DailyStreamingApiEvents: LimitInfo
+
+    # Storage Limits
+    DataStorageMB: LimitInfo
+    FileStorageMB: LimitInfo
+
+    # Email Limits
+    DailyWorkflowEmails: LimitInfo
+    MassEmail: LimitInfo
+    SingleEmail: LimitInfo
+
+    # Other common limits - there are many more, but these are the most common
+    # Using Any for the rest since there are 60+ different limit types
+    # and they vary by org type and features
+
+
+class SObjectUrls(TypedDict):
+    """URLs for various SObject operations."""
+
+    sobject: str
+    describe: str
+    rowTemplate: str
+
+
+class SObjectInfo(TypedDict):
+    """Basic SObject information from list_sobjects."""
+
+    activateable: bool
+    associateEntityType: Optional[str]
+    associateParentEntity: Optional[str]
+    createable: bool
+    custom: bool
+    customSetting: bool
+    deepCloneable: bool
+    deletable: bool
+    deprecatedAndHidden: bool
+    feedEnabled: bool
+    hasSubtypes: bool
+    isInterface: bool
+    isSubtype: bool
+    keyPrefix: Optional[str]
+    label: str
+    labelPlural: str
+    layoutable: bool
+    mergeable: bool
+    mruEnabled: bool
+    name: str
+    queryable: bool
+    replicateable: bool
+    retrieveable: bool
+    searchable: bool
+    triggerable: bool
+    undeletable: bool
+    updateable: bool
+    urls: SObjectUrls
+
+
+class ActionOverride(TypedDict):
+    """Action override information."""
+
+    formFactor: str
+    isAvailableInTouch: bool
+    name: str
+    pageId: Optional[str]
+    url: Optional[str]
+
+
+class ChildRelationship(TypedDict):
+    """Child relationship information."""
+
+    cascadeDelete: bool
+    childSObject: str
+    deprecatedAndHidden: bool
+    field: str
+    junctionIdListNames: List[str]
+    junctionReferenceTo: List[str]
+    relationshipName: Optional[str]
+    restrictedDelete: bool
+
+
+class PicklistValue(TypedDict):
+    """Picklist value information."""
+
+    active: bool
+    defaultValue: bool
+    label: str
+    validFor: Optional[str]
+    value: str
+
+
+class FilteredLookupInfo(TypedDict):
+    """Filtered lookup information."""
+
+    controllingFields: List[str]
+    dependent: bool
+    optionalFilter: bool
+
+
+class RecordTypeInfo(TypedDict):
+    """Record type information."""
+
+    available: bool
+    defaultRecordTypeMapping: bool
+    developerName: str
+    master: bool
+    name: str
+    recordTypeId: str
+    urls: Dict[str, str]
+
+
+class NamedLayoutInfo(TypedDict):
+    """Named layout information."""
+
+    name: str
+    urls: Dict[str, str]
+
+
+class ScopeInfo(TypedDict):
+    """Scope information."""
+
+    label: str
+    name: str
+
+
+class FieldInfo(TypedDict, total=False):
+    """Field information from describe_sobject - using total=False due to many optional fields."""
+
+    # Core field properties (always present)
+    name: str
+    type: str
+    label: str
+
+    # Common properties (usually present)
+    length: int
+    nillable: bool
+    createable: bool
+    updateable: bool
+    custom: bool
+
+    # Boolean flags
+    aggregatable: bool
+    aiPredictionField: bool
+    autoNumber: bool
+    calculated: bool
+    caseSensitive: bool
+    dependentPicklist: bool
+    deprecatedAndHidden: bool
+    encrypted: bool
+    externalId: bool
+    filterable: bool
+    formulaTreatNullNumberAsZero: bool
+    groupable: bool
+    highScaleNumber: bool
+    htmlFormatted: bool
+    idLookup: bool
+    nameField: bool
+    namePointing: bool
+    permissionable: bool
+    polymorphicForeignKey: bool
+    queryByDistance: bool
+    restrictedPicklist: bool
+    searchPrefilterable: bool
+    sortable: bool
+    unique: bool
+    writeRequiresMasterRead: bool
+
+    # Numeric properties
+    byteLength: int
+    digits: int
+    precision: int
+    scale: int
+
+    # String properties
+    calculatedFormula: Optional[str]
+    compoundFieldName: Optional[str]
+    controllerName: Optional[str]
+    defaultValue: Optional[str]
+    defaultValueFormula: Optional[str]
+    extraTypeInfo: Optional[str]
+    inlineHelpText: Optional[str]
+    mask: Optional[str]
+    maskType: Optional[str]
+    referenceTargetField: Optional[str]
+    relationshipName: Optional[str]
+    soapType: str
+
+    # Boolean properties with defaults
+    cascadeDelete: bool
+    defaultedOnCreate: bool
+    displayLocationInDecimal: bool
+    restrictedDelete: bool
+
+    # Numeric properties
+    relationshipOrder: Optional[int]
+
+    # Array properties
+    picklistValues: List[PicklistValue]
+    referenceTo: List[str]
+
+    # Object properties
+    filteredLookupInfo: Optional[FilteredLookupInfo]
+
+
+class SObjectDescribe(TypedDict):
+    """Complete SObject describe information."""
+
+    # Basic properties
+    name: str
+    label: str
+    labelPlural: str
+    keyPrefix: Optional[str]
+    custom: bool
+
+    # Capabilities
+    activateable: bool
+    createable: bool
+    deletable: bool
+    mergeable: bool
+    queryable: bool
+    replicateable: bool
+    retrieveable: bool
+    searchable: bool
+    triggerable: bool
+    undeletable: bool
+    updateable: bool
+
+    # Layout and UI properties
+    compactLayoutable: bool
+    feedEnabled: bool
+    layoutable: bool
+    listviewable: bool
+    lookupLayoutable: bool
+    mruEnabled: bool
+    searchLayoutable: bool
+
+    # Advanced properties
+    customSetting: bool
+    deepCloneable: bool
+    deprecatedAndHidden: bool
+    hasSubtypes: bool
+    isInterface: bool
+    isSubtype: bool
+
+    # Optional properties
+    associateEntityType: Optional[str]
+    associateParentEntity: Optional[str]
+    defaultImplementation: Optional[str]
+    extendedBy: Optional[str]
+    extendsInterfaces: Optional[str]
+    implementedBy: Optional[str]
+    implementsInterfaces: Optional[str]
+    networkScopeFieldName: Optional[str]
+    sobjectDescribeOption: Optional[str]
+
+    # Array properties
+    actionOverrides: List[ActionOverride]
+    childRelationships: List[ChildRelationship]
+    fields: List[FieldInfo]
+    namedLayoutInfos: List[NamedLayoutInfo]
+    recordTypeInfos: List[RecordTypeInfo]
+    supportedScopes: List[ScopeInfo]
+
+    # URLs
+    urls: Dict[str, str]

aio_salesforce/api/query/__init__.py

@@ -0,0 +1,18 @@
+"""Salesforce Query API module."""
+
+from .client import QueryAPI, QueryResult
+from .types import (
+    QueryResponse,
+    QueryAllResponse,
+    QueryMoreResponse,
+    QueryErrorResponse,
+)
+
+__all__ = [
+    "QueryAPI",
+    "QueryResult",
+    "QueryResponse",
+    "QueryAllResponse",
+    "QueryMoreResponse",
+    "QueryErrorResponse",
+]

aio_salesforce/api/query/client.py

@@ -0,0 +1,216 @@
+"""Salesforce Query API client."""
+
+import logging
+import re
+import urllib.parse
+from typing import Any, Dict, List, Optional, AsyncGenerator
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...connection import SalesforceConnection
+
+from .types import QueryResponse, QueryMoreResponse
+
+
+class QueryResult:
+    """
+    A query result that supports len() and acts as an async iterator over individual records.
+    Handles pagination automatically via QueryMore.
+    """
+
+    def __init__(
+        self,
+        query_api: "QueryAPI",
+        initial_response: QueryResponse,
+    ):
+        """
+        Initialize QueryResult.
+
+        :param query_api: QueryAPI instance for making follow-up requests
+        :param initial_response: Initial query response
+        """
+        self._query_api = query_api
+        self._total_size = initial_response["totalSize"]
+        self._done = initial_response["done"]
+        self._records = initial_response["records"]
+        self._next_records_url = initial_response.get("nextRecordsUrl")
+        self._current_index = 0
+
+    def __len__(self) -> int:
+        """Return the total number of records."""
+        return self._total_size
+
+    @property
+    def total_size(self) -> int:
+        """Get the total number of records."""
+        return self._total_size
+
+    @property
+    def done(self) -> bool:
+        """Check if all records have been fetched."""
+        return self._done and self._current_index >= len(self._records)
+
+    async def __aiter__(self):
+        """Async iterator that yields individual records."""
+        # First, yield records from the initial response
+        for record in self._records[self._current_index :]:
+            self._current_index += 1
+            yield record
+
+        # Then handle pagination if needed
+        next_url = self._next_records_url
+        while next_url and not self._done:
+            # Make QueryMore request
+            more_response = await self._query_api.query_more(next_url)
+
+            # Yield records from this batch
+            for record in more_response["records"]:
+                yield record
+
+            # Update pagination state
+            self._done = more_response["done"]
+            next_url = more_response.get("nextRecordsUrl")
+
+    async def collect_all(self) -> List[Dict[str, Any]]:
+        """Collect all records into a list."""
+        records = []
+        async for record in self:
+            records.append(record)
+        return records
+
+
+class QueryAPI:
+    """Salesforce Query API client."""
+
+    def __init__(self, connection: "SalesforceConnection"):
+        """Initialize QueryAPI with a Salesforce connection."""
+        self._connection = connection
+
+    def _get_query_url(self, api_version: Optional[str] = None) -> str:
+        """Get the base URL for query requests."""
+        version = api_version or self._connection.version
+        return f"{self._connection.instance_url}/services/data/{version}/query"
+
+    def _get_queryall_url(self, api_version: Optional[str] = None) -> str:
+        """Get the base URL for queryAll requests (includes deleted records)."""
+        version = api_version or self._connection.version
+        return f"{self._connection.instance_url}/services/data/{version}/queryAll"
+
+    def _sanitize_soql(self, soql: str) -> str:
+        """
+        Basic SOQL sanitization to prevent injection attacks.
+
+        :param soql: SOQL query string
+        :returns: Sanitized SOQL string
+        :raises ValueError: If query contains potentially dangerous patterns
+        """
+        # Remove leading/trailing whitespace
+        soql = soql.strip()
+
+        # other sanitization?
+
+        return soql
+
+    async def soql(
+        self,
+        query: str,
+        include_deleted: bool = False,
+        api_version: Optional[str] = None,
+    ) -> QueryResult:
+        """
+        Execute a SOQL query.
+
+        :param query: SOQL query string
+        :param include_deleted: If True, include deleted and archived records (uses queryAll endpoint)
+        :param api_version: API version to use
+        :returns: QueryResult that can be iterated over
+        :raises ValueError: If SOQL is invalid or potentially dangerous
+        """
+        # Sanitize the SOQL query
+        sanitized_soql = self._sanitize_soql(query)
+
+        # Choose endpoint based on include_deleted parameter
+        if include_deleted:
+            url = self._get_queryall_url(api_version)
+        else:
+            url = self._get_query_url(api_version)
+
+        # Prepare the request
+        params = {"q": sanitized_soql}
+
+        # Make the request
+        response = await self._connection.get(url, params=params)
+        response.raise_for_status()
+
+        # Return QueryResult for iteration
+        return QueryResult(self, response.json())
+
+    async def query_more(self, next_records_url: str) -> QueryMoreResponse:
+        """
+        Execute a QueryMore request to get the next batch of records.
+
+        :param next_records_url: The nextRecordsUrl from a previous query response
+        :returns: QueryMoreResponse with the next batch of records
+        """
+        # The next_records_url is relative to the instance, so we need to construct the full URL
+        if next_records_url.startswith("/"):
+            url = f"{self._connection.instance_url}{next_records_url}"
+        else:
+            url = next_records_url
+
+        # Make the request
+        response = await self._connection.get(url)
+        response.raise_for_status()
+        return response.json()
+
+    async def explain(
+        self,
+        query: str,
+        api_version: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """
+        Get query execution plan for a SOQL query.
+
+        :param query: SOQL query string
+        :param api_version: API version to use
+        :returns: Query execution plan
+        """
+        # Sanitize the SOQL query
+        sanitized_soql = self._sanitize_soql(query)
+
+        # Prepare the request
+        url = self._get_query_url(api_version)
+        params = {"q": sanitized_soql, "explain": "true"}
+
+        # Make the request
+        response = await self._connection.get(url, params=params)
+        response.raise_for_status()
+        return response.json()
+
+    async def sosl(
+        self,
+        search: str,
+        api_version: Optional[str] = None,
+    ) -> List[Dict[str, Any]]:
+        """
+        Execute a SOSL (Salesforce Object Search Language) search.
+
+        :param search: SOSL search string
+        :param api_version: API version to use
+        :returns: List of search results
+        """
+        # Basic SOSL validation
+        if not search.strip().upper().startswith("FIND"):
+            raise ValueError("SOSL queries must start with FIND")
+
+        # Prepare the request
+        version = api_version or self._connection.version
+        url = f"{self._connection.instance_url}/services/data/{version}/search"
+        params = {"q": search.strip()}
+
+        # Make the request
+        response = await self._connection.get(url, params=params)
+        response.raise_for_status()
+        data = response.json()
+        return data.get("searchRecords", [])

aio_salesforce/api/query/types.py

@@ -0,0 +1,38 @@
+"""TypedDict definitions for Salesforce Query API responses."""
+
+from typing import TypedDict, List, Dict, Any, Optional
+
+
+class QueryResponse(TypedDict):
+    """Response from a SOQL query."""
+
+    totalSize: int
+    done: bool
+    records: List[Dict[str, Any]]
+    nextRecordsUrl: Optional[str]
+
+
+class QueryAllResponse(TypedDict):
+    """Response from a SOQL QueryAll query (includes deleted records)."""
+
+    totalSize: int
+    done: bool
+    records: List[Dict[str, Any]]
+    nextRecordsUrl: Optional[str]
+
+
+class QueryMoreResponse(TypedDict):
+    """Response from a QueryMore request."""
+
+    totalSize: int
+    done: bool
+    records: List[Dict[str, Any]]
+    nextRecordsUrl: Optional[str]
+
+
+class QueryErrorResponse(TypedDict):
+    """Error response from Query API."""
+
+    message: str
+    errorCode: str
+    fields: Optional[List[str]]