aio-sf 0.1.0b1__py3-none-any.whl

aio_salesforce/__init__.py

@@ -0,0 +1,27 @@
+"""aio-salesforce: Async Salesforce library for Python with Bulk API 2.0 support."""
+
+__version__ = "0.1.0b1"
+__author__ = "Jonas"
+__email__ = "charlie@callaway.cloud"
+
+# Connection functionality
+from .connection import (  # noqa: F401
+    SalesforceConnection,
+    SalesforceAuthError,
+    AuthStrategy,
+    ClientCredentialsAuth,
+    RefreshTokenAuth,
+    StaticTokenAuth,
+)
+
+# Core package only exports connection functionality
+# Users import exporter functions directly: from aio_salesforce.exporter import bulk_query
+
+__all__ = [
+    "SalesforceConnection",
+    "SalesforceAuthError",
+    "AuthStrategy",
+    "ClientCredentialsAuth",
+    "RefreshTokenAuth",
+    "StaticTokenAuth",
+]

aio_salesforce/api/README.md

@@ -0,0 +1,107 @@
+# Salesforce API Organization
+
+This directory contains organized Salesforce API clients following a consistent convention.
+
+## Directory Structure Convention
+
+Each API module follows this structure:
+
+```
+api/
+├── {api_name}/
+│   ├── __init__.py          # Export API client and types
+│   ├── client.py            # Main API client class
+│   └── types.py             # TypedDict definitions for responses
+└── __init__.py              # Export all APIs and types
+```
+
+## Current APIs
+
+### `describe/` - Describe API
+- **Client**: `DescribeAPI`
+- **Purpose**: Object describe/metadata, organization info, limits
+- **Key Methods**: 
+  - `describe_sobject()` → `SObjectDescribe`
+  - `list_sobjects()` → `List[SObjectInfo]`
+  - `get_organization_info()` → `OrganizationInfo`
+  - `get_limits()` → `OrganizationLimits`
+
+### `bulk_v2/` - Bulk API v2
+- **Client**: `BulkV2API`  
+- **Purpose**: Large data operations, bulk queries
+- **Key Methods**:
+  - `create_job()` → `BulkJobInfo`
+  - `get_job_status()` → `BulkJobStatus`
+  - `get_job_results()` → `Tuple[str, Optional[str]]`
+  - `wait_for_job_completion()` → `BulkJobStatus`
+
+### `query/` - Query API
+- **Client**: `QueryAPI`
+- **Purpose**: SOQL queries, QueryMore, SOSL search
+- **Key Methods**:
+  - `soql(query, include_deleted=False)` → `QueryResult` (with async iteration)
+  - `sosl(search)` → `List[Dict[str, Any]]` (SOSL search)
+  - `explain(query)` → `Dict[str, Any]` (query execution plan)
+  - `query_more()` → `QueryMoreResponse` (internal pagination)
+- **Features**: SOQL injection protection, automatic pagination, deleted records support
+- **Note**: Batch size is controlled by Salesforce, not configurable in Query API
+
+## Naming Conventions
+
+### API Clients
+- **Class Name**: `{ApiName}API` (e.g., `DescribeAPI`, `BulkV2API`)
+- **File**: `client.py`
+- **Connection Property**: `sf.{api_name}` (e.g., `sf.describe`, `sf.bulk_v2`)
+
+### Types
+- **File**: `types.py`
+- **Naming**: Descriptive, specific to the API
+- **Examples**: `SObjectDescribe`, `BulkJobInfo`, `OrganizationLimits`
+
+### Methods
+- **Return Types**: Always use TypedDict for structured responses
+- **Naming**: Clear, action-oriented (e.g., `get_job_status`, `describe_sobject`)
+- **Parameters**: Use typed parameters with Optional where appropriate
+
+## Adding New APIs
+
+When adding a new API (e.g., `query` for SOQL):
+
+1. **Create directory**: `api/query/`
+2. **Create files**:
+   ```python
+   # api/query/__init__.py
+   from .client import QueryAPI
+   from .types import QueryResult, QueryError
+   __all__ = ["QueryAPI", "QueryResult", "QueryError"]
+   
+   # api/query/client.py  
+   class QueryAPI:
+       def __init__(self, connection): ...
+       async def execute(self, soql: str) -> QueryResult: ...
+   
+   # api/query/types.py
+   class QueryResult(TypedDict): ...
+   ```
+3. **Add to main API `__init__.py`**:
+   ```python
+   from .query import QueryAPI, QueryResult, QueryError
+   ```
+4. **Add to connection**:
+   ```python
+   @property
+   def query(self):
+       if self._query_api is None:
+           from .api.query import QueryAPI
+           self._query_api = QueryAPI(self)
+       return self._query_api
+   ```
+
+## Benefits
+
+- **Organization**: Each API is self-contained
+- **Type Safety**: Full TypedDict coverage
+- **Discoverability**: Clear structure and naming
+- **Maintainability**: Easy to add/modify APIs
+- **Testing**: Each API can be tested independently
+- **Documentation**: Types serve as API documentation

aio_salesforce/api/__init__.py

@@ -0,0 +1,65 @@
+"""
+Salesforce API modules.
+
+This package provides organized access to Salesforce APIs:
+- describe: Object and organization describe/metadata
+- bulk_v2: Bulk API v2 for large data operations
+- query: SOQL queries and QueryMore operations
+"""
+
+# Import API clients and types from organized submodules
+from .bulk_v2 import (
+    BulkV2API,
+    BulkJobCreateRequest,
+    BulkJobInfo,
+    BulkJobStatus,
+    BulkJobError,
+)
+from .describe import (
+    DescribeAPI,
+    FieldInfo,
+    LimitInfo,
+    OrganizationInfo,
+    OrganizationLimits,
+    PicklistValue,
+    RecordTypeInfo,
+    SObjectDescribe,
+    SObjectInfo,
+    SalesforceAttributes,
+)
+from .query import (
+    QueryAPI,
+    QueryResult,
+    QueryResponse,
+    QueryAllResponse,
+    QueryMoreResponse,
+    QueryErrorResponse,
+)
+
+__all__ = [
+    # API Clients
+    "BulkV2API",
+    "DescribeAPI",
+    "QueryAPI",
+    # Bulk v2 Types
+    "BulkJobCreateRequest",
+    "BulkJobInfo",
+    "BulkJobStatus",
+    "BulkJobError",
+    # Describe Types
+    "FieldInfo",
+    "LimitInfo",
+    "OrganizationInfo",
+    "OrganizationLimits",
+    "PicklistValue",
+    "RecordTypeInfo",
+    "SObjectDescribe",
+    "SObjectInfo",
+    "SalesforceAttributes",
+    # Query Types
+    "QueryResult",
+    "QueryResponse",
+    "QueryAllResponse",
+    "QueryMoreResponse",
+    "QueryErrorResponse",
+]

aio_salesforce/api/bulk_v2/__init__.py

@@ -0,0 +1,21 @@
+"""
+Salesforce Bulk API v2.
+"""
+
+from .client import BulkV2API
+from .types import (
+    BulkJobCreateRequest,
+    BulkJobInfo,
+    BulkJobStatus,
+    BulkJobError,
+)
+
+__all__ = [
+    # API Client
+    "BulkV2API",
+    # Types
+    "BulkJobCreateRequest",
+    "BulkJobInfo",
+    "BulkJobStatus",
+    "BulkJobError",
+]

aio_salesforce/api/bulk_v2/client.py

@@ -0,0 +1,200 @@
+"""
+Salesforce Bulk API v2 methods.
+"""
+
+import asyncio
+import logging
+import time
+from typing import Optional, Tuple, TYPE_CHECKING
+
+from .types import (
+    BulkJobCreateRequest,
+    BulkJobInfo,
+    BulkJobStatus,
+)
+
+if TYPE_CHECKING:
+    from ...connection import SalesforceConnection
+
+logger = logging.getLogger(__name__)
+
+
+class BulkV2API:
+    """Salesforce Bulk API v2 methods."""
+
+    def __init__(self, connection: "SalesforceConnection"):
+        self.connection = connection
+
+    def _get_base_url(self, api_version: Optional[str] = None) -> str:
+        """Get the base URL for Bulk API v2 requests."""
+        return self.connection.get_base_url(api_version)
+
+    def _get_job_url(self, job_id: str, api_version: Optional[str] = None) -> str:
+        """Get the URL for a specific bulk job."""
+        base_url = self._get_base_url(api_version)
+        return f"{base_url}/jobs/query/{job_id}"
+
+    def _get_job_results_url(
+        self, job_id: str, api_version: Optional[str] = None
+    ) -> str:
+        """Get the URL for fetching bulk job results."""
+        base_url = self._get_base_url(api_version)
+        return f"{base_url}/jobs/query/{job_id}/results"
+
+    def _get_jobs_url(self, api_version: Optional[str] = None) -> str:
+        """Get the URL for creating bulk jobs."""
+        base_url = self._get_base_url(api_version)
+        return f"{base_url}/jobs/query"
+
+    async def create_job(
+        self,
+        soql_query: str,
+        all_rows: bool = False,
+        api_version: Optional[str] = None,
+    ) -> BulkJobInfo:
+        """
+        Create a new bulk query job.
+
+        :param soql_query: The SOQL query to execute
+        :param all_rows: If True, includes deleted and archived records (queryAll)
+        :param api_version: API version to use (defaults to connection version)
+        :returns: Job information
+        """
+        job_url = self._get_jobs_url(api_version)
+        job_data: BulkJobCreateRequest = {
+            "operation": "queryAll" if all_rows else "query",
+            "query": soql_query,
+            "contentType": "CSV",
+        }
+
+        response = await self.connection.post(job_url, json=job_data)
+        response.raise_for_status()
+        job_info = response.json()
+
+        logger.info(
+            f"Created bulk job {job_info['id']} for query: {soql_query[:100]}..."
+        )
+        return job_info
+
+    async def get_job_status(
+        self,
+        job_id: str,
+        api_version: Optional[str] = None,
+    ) -> BulkJobStatus:
+        """
+        Get the status of a bulk job.
+
+        :param job_id: The job ID
+        :param api_version: API version to use (defaults to connection version)
+        :returns: Job status information
+        """
+        status_url = self._get_job_url(job_id, api_version)
+        response = await self.connection.get(status_url)
+        response.raise_for_status()
+        return response.json()
+
+    async def get_job_results(
+        self,
+        job_id: str,
+        locator: Optional[str] = None,
+        max_records: int = 10000,
+        api_version: Optional[str] = None,
+    ) -> Tuple[str, Optional[str]]:
+        """
+        Get results from a completed bulk job.
+
+        :param job_id: The job ID
+        :param locator: Query locator for pagination (optional)
+        :param max_records: Maximum number of records to fetch
+        :param api_version: API version to use (defaults to connection version)
+        :returns: Tuple of (CSV response text, next locator or None)
+        """
+        results_url = self._get_job_results_url(job_id, api_version)
+        params = {"maxRecords": max_records}
+        if locator:
+            params["locator"] = locator
+
+        response = await self.connection.get(results_url, params=params)
+        response.raise_for_status()
+
+        # Get next locator from headers
+        next_locator = response.headers.get("Sforce-Locator")
+        if next_locator == "null":
+            next_locator = None
+
+        return response.text, next_locator
+
+    async def wait_for_job_completion(
+        self,
+        job_id: str,
+        poll_interval: int = 5,
+        timeout: Optional[int] = None,
+        api_version: Optional[str] = None,
+    ) -> BulkJobStatus:
+        """
+        Wait for a bulk job to complete.
+
+        :param job_id: The job ID to monitor
+        :param poll_interval: Time in seconds between status checks
+        :param timeout: Maximum time to wait (None for no timeout)
+        :param api_version: API version to use (defaults to connection version)
+        :returns: Final job status
+        :raises TimeoutError: If job doesn't complete within timeout
+        :raises Exception: If job fails
+        """
+        logger.info(f"Waiting for job {job_id} to complete...")
+        start_time = time.time()
+
+        while True:
+            job_status = await self.get_job_status(job_id, api_version)
+            state = job_status["state"]
+
+            if state == "JobComplete":
+                total_records = job_status.get("numberRecordsProcessed", 0)
+                logger.info(
+                    f"Job {job_id} completed successfully. Total records: {total_records}"
+                )
+                return job_status
+            elif state == "Failed":
+                raise Exception(f"Job {job_id} failed: {job_status}")
+            else:
+                # Check timeout
+                if timeout and (time.time() - start_time) > timeout:
+                    raise TimeoutError(
+                        f"Job {job_id} did not complete within {timeout} seconds"
+                    )
+
+                # Job is still running
+                logger.debug(
+                    f"Job {job_id} state: {state}, waiting {poll_interval}s..."
+                )
+                await asyncio.sleep(poll_interval)
+
+    async def execute_query(
+        self,
+        soql_query: str,
+        all_rows: bool = False,
+        poll_interval: int = 5,
+        timeout: Optional[int] = None,
+        api_version: Optional[str] = None,
+    ) -> BulkJobStatus:
+        """
+        Execute a SOQL query via Bulk API v2 and wait for completion.
+
+        This is a convenience method that creates a job and waits for it to complete.
+
+        :param soql_query: The SOQL query to execute
+        :param all_rows: If True, includes deleted and archived records
+        :param poll_interval: Time in seconds between status checks
+        :param timeout: Maximum time to wait (None for no timeout)
+        :param api_version: API version to use (defaults to connection version)
+        :returns: Final job status
+        """
+        # Create the job
+        job_info = await self.create_job(soql_query, all_rows, api_version)
+        job_id = job_info["id"]
+
+        # Wait for completion
+        return await self.wait_for_job_completion(
+            job_id, poll_interval, timeout, api_version
+        )

aio_salesforce/api/bulk_v2/types.py

@@ -0,0 +1,71 @@
+"""
+TypedDict definitions for Salesforce Bulk API v2 responses.
+"""
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+class BulkJobInfo(TypedDict):
+    """Bulk job information."""
+
+    id: str
+    operation: str
+    object: str
+    createdById: str
+    createdDate: str
+    systemModstamp: str
+    state: str
+    concurrencyMode: str
+    contentType: str
+    apiVersion: str
+    jobType: str
+    lineEnding: str
+    columnDelimiter: str
+
+
+class BulkJobCreateRequest(TypedDict):
+    """Request payload for creating a bulk job."""
+
+    operation: str
+    query: str
+    contentType: str
+
+
+class BulkJobStatus(TypedDict):
+    """Bulk job status information."""
+
+    id: str
+    operation: str
+    object: str
+    createdById: str
+    createdDate: str
+    systemModstamp: str
+    state: str
+    concurrencyMode: str
+    contentType: str
+    apiVersion: str
+    jobType: str
+    lineEnding: str
+    columnDelimiter: str
+    numberBatchesQueued: int
+    numberBatchesInProgress: int
+    numberBatchesCompleted: int
+    numberBatchesFailed: int
+    numberBatchesTotal: int
+    numberRequestsCompleted: int
+    numberRequestsFailed: int
+    numberRequestsTotal: int
+    numberRecordsProcessed: int
+    numberRecordsFailed: int
+    numberRetries: int
+    apiActiveProcessingTime: int
+    apexProcessingTime: int
+    totalProcessingTime: int
+
+
+class BulkJobError(TypedDict):
+    """Bulk job error information."""
+
+    message: str
+    errorCode: str
+    fields: List[str]

aio_salesforce/api/describe/__init__.py

@@ -0,0 +1,31 @@
+"""
+Salesforce Describe API.
+"""
+
+from .client import DescribeAPI
+from .types import (
+    FieldInfo,
+    LimitInfo,
+    OrganizationInfo,
+    OrganizationLimits,
+    PicklistValue,
+    RecordTypeInfo,
+    SObjectDescribe,
+    SObjectInfo,
+    SalesforceAttributes,
+)
+
+__all__ = [
+    # API Client
+    "DescribeAPI",
+    # Types
+    "FieldInfo",
+    "LimitInfo",
+    "OrganizationInfo",
+    "OrganizationLimits",
+    "PicklistValue",
+    "RecordTypeInfo",
+    "SObjectDescribe",
+    "SObjectInfo",
+    "SalesforceAttributes",
+]

aio_salesforce/api/describe/client.py

@@ -0,0 +1,94 @@
+"""
+Salesforce Describe API methods.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional, TYPE_CHECKING
+
+from .types import (
+    OrganizationInfo,
+    OrganizationLimits,
+    SObjectDescribe,
+    SObjectInfo,
+)
+
+if TYPE_CHECKING:
+    from ...connection import SalesforceConnection
+
+logger = logging.getLogger(__name__)
+
+
+class DescribeAPI:
+    """Salesforce Describe API methods."""
+
+    def __init__(self, connection: "SalesforceConnection"):
+        self.connection = connection
+
+    async def sobject(
+        self, sobject_type: str, api_version: Optional[str] = None
+    ) -> SObjectDescribe:
+        """
+        Get metadata for a Salesforce object.
+
+        :param sobject_type: Name of the Salesforce object (e.g., 'Account', 'Contact')
+        :param api_version: API version to use (defaults to connection version)
+        :returns: Object metadata dictionary
+        """
+        url = self.connection.get_describe_url(sobject_type, api_version)
+        response = await self.connection.get(url)
+        response.raise_for_status()
+        return response.json()
+
+    async def list_sobjects(
+        self, api_version: Optional[str] = None
+    ) -> List[SObjectInfo]:
+        """
+        List all available Salesforce objects.
+
+        :param api_version: API version to use (defaults to connection version)
+        :returns: List of object metadata dictionaries
+        """
+        base_url = self.connection.get_base_url(api_version)
+        url = f"{base_url}/sobjects"
+        response = await self.connection.get(url)
+        response.raise_for_status()
+        data = response.json()
+        return data.get("sobjects", [])
+
+    async def get_limits(self, api_version: Optional[str] = None) -> OrganizationLimits:
+        """
+        Get organization limits.
+
+        :param api_version: API version to use (defaults to connection version)
+        :returns: Organization limits dictionary
+        """
+        base_url = self.connection.get_base_url(api_version)
+        url = f"{base_url}/limits"
+        response = await self.connection.get(url)
+        response.raise_for_status()
+        return response.json()
+
+    async def get_organization_info(
+        self, api_version: Optional[str] = None
+    ) -> OrganizationInfo:
+        """
+        Get organization information.
+
+        :param api_version: API version to use (defaults to connection version)
+        :returns: Organization info dictionary
+        """
+        # Query the Organization object for basic org info
+        base_url = self.connection.get_base_url(api_version)
+        url = f"{base_url}/query"
+        params = {
+            "q": "SELECT Id, Name, OrganizationType, InstanceName, IsSandbox FROM Organization LIMIT 1"
+        }
+        response = await self.connection.get(url, params=params)
+        response.raise_for_status()
+        data = response.json()
+
+        records = data.get("records", [])
+        if records:
+            return records[0]
+        else:
+            raise RuntimeError("Unable to retrieve organization information")