or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

authentication.mdbulk-operations.mdbulk2-operations.mdexceptions.mdindex.mdmetadata-api.mdrest-api.mdutilities.md
tile.json

tessl/pypi-simple-salesforce

A basic Salesforce.com REST API client for Python applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/simple-salesforce@1.12.x

To install, run

npx @tessl/cli install tessl/pypi-simple-salesforce@1.12.0

index.mddocs/

Simple-Salesforce

A comprehensive Python library providing a basic REST API client for Salesforce.com. Simple-Salesforce offers unified access to Salesforce's REST API, Bulk API v1.0 and v2.0, and Metadata API through a clean, Pythonic interface. The library supports multiple authentication methods and provides both low-level and high-level operations for Salesforce data management.

Package Information

  • Package Name: simple-salesforce
  • Version: 1.12.9
  • Language: Python
  • Installation: pip install simple-salesforce
  • License: Apache 2.0

Core Imports

from simple_salesforce import Salesforce, SalesforceLogin

Common for specific functionality:

from simple_salesforce import (
    SFType, SFBulkHandler, format_soql, format_external_id
)

Exception handling:

from simple_salesforce import (
    SalesforceError, SalesforceAuthenticationFailed,
    SalesforceExpiredSession, SalesforceResourceNotFound
)

Basic Usage

from simple_salesforce import Salesforce

# Password authentication
sf = Salesforce(
    username='user@example.com',
    password='mypassword',
    security_token='mytoken'
)

# Query records
results = sf.query("SELECT Id, Name FROM Account LIMIT 10")
for record in results['records']:
    print(f"Account: {record['Name']} (ID: {record['Id']})")

# Access specific SObject operations
account = sf.Account.get('001XX000003DHPr')
print(f"Account Name: {account['Name']}")

# Create new record
new_account = sf.Account.create({
    'Name': 'Test Account',
    'Type': 'Customer'
})
print(f"Created Account ID: {new_account['id']}")

# Bulk operations
bulk_data = [
    {'Name': 'Bulk Account 1', 'Type': 'Customer'},
    {'Name': 'Bulk Account 2', 'Type': 'Partner'}
]
bulk_results = sf.bulk.Account.insert(bulk_data)

# SOQL formatting with proper escaping
from simple_salesforce import format_soql
name = "O'Reilly Corp"
safe_query = format_soql("SELECT Id FROM Account WHERE Name = {}", name)
results = sf.query(safe_query)

Architecture

Simple-Salesforce provides a layered architecture that mirrors Salesforce's API structure:

  • Salesforce Class: Primary client managing authentication, session state, and providing access to all API endpoints
  • SFType Interface: Object-specific operations (CRUD, metadata) for individual Salesforce SObject types
  • Bulk Handlers: Specialized interfaces for high-volume operations using Bulk API v1.0 and v2.0
  • Authentication Layer: Multiple authentication methods including password, OAuth 2.0, JWT, and session-based auth
  • Utilities: Formatting functions for safe SOQL construction and data transformation

This design enables both simple interactions for basic use cases and sophisticated bulk operations for enterprise scenarios, while maintaining consistent error handling and session management across all Salesforce APIs.

Capabilities

Authentication

Multiple authentication methods supporting various Salesforce deployment scenarios including password authentication, OAuth 2.0 flows, JWT bearer tokens, and direct session access.

def SalesforceLogin(username=None, password=None, security_token=None, **kwargs): ...

Authentication Methods

REST API Operations

Core Salesforce class and SFType interface providing complete CRUD operations, queries, searches, and metadata access for Salesforce objects through the REST API.

class Salesforce:
    def query(self, query, include_deleted=False, **kwargs): ...
    def search(self, search): ...
    def describe(self, **kwargs): ...
    
class SFType:
    def create(self, data, headers=None): ...
    def get(self, record_id, headers=None, **kwargs): ...
    def update(self, record_id, data, **kwargs): ...
    def delete(self, record_id, **kwargs): ...

REST API Operations

Bulk API v1.0 Operations

High-performance bulk operations for large-scale data manipulation using Salesforce's original Bulk API, supporting insert, update, upsert, delete, and query operations with batching.

class SFBulkHandler:
    def submit_dml(self, object_name, dml, data, **kwargs): ...

class SFBulkType:
    def insert(self, data, batch_size=10000, **kwargs): ...
    def update(self, data, batch_size=10000, **kwargs): ...
    def query(self, data, lazy_operation=False, **kwargs): ...

Bulk API v1.0 Operations

Bulk API v2.0 Operations

Next-generation bulk operations with improved performance, simplified job management, and enhanced monitoring capabilities for modern high-volume data processing.

class SFBulk2Handler:
    def create_job(self, operation, object_name=None, **kwargs): ...
    def upload_job_data(self, job_id, data, **kwargs): ...
    def wait_for_job(self, job_id, is_query, **kwargs): ...
    def get_query_results(self, job_id, **kwargs): ...

Bulk API v2.0 Operations

Metadata API Operations

Complete metadata management including deployment, retrieval, and CRUD operations on Salesforce metadata components like custom objects, fields, workflows, and Apex classes.

class SfdcMetadataApi:
    def deploy(self, zipfile, sandbox, **kwargs): ...
    def retrieve(self, async_process_id, **kwargs): ...
    def describe_metadata(self): ...
    def list_metadata(self, queries): ...

Metadata API Operations

Utility Functions

Formatting and utility functions for safe SOQL construction, external ID handling, data transformation, and error management across all Salesforce operations.

def format_soql(query, *args, **kwargs): ...
def format_external_id(field, value): ...
def quote_soql_value(value): ...

Utility Functions

Exception Handling

Comprehensive exception hierarchy mapping HTTP status codes and Salesforce errors to specific Python exceptions for precise error handling and debugging.

class SalesforceError(Exception): ...
class SalesforceAuthenticationFailed(SalesforceError): ...
class SalesforceExpiredSession(SalesforceError): ...
class SalesforceResourceNotFound(SalesforceError): ...

Exception Classes and Error Handling