0
# Simple-Salesforce
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: simple-salesforce
7
- **Version**: 1.12.9
8
- **Language**: Python
9
- **Installation**: `pip install simple-salesforce`
10
- **License**: Apache 2.0
11

12
## Core Imports
13

14
```python
15
from simple_salesforce import Salesforce, SalesforceLogin
16
```
17

18
Common for specific functionality:
19

20
```python
21
from simple_salesforce import (
22
    SFType, SFBulkHandler, format_soql, format_external_id
23
)
24
```
25

26
Exception handling:
27

28
```python
29
from simple_salesforce import (
30
    SalesforceError, SalesforceAuthenticationFailed,
31
    SalesforceExpiredSession, SalesforceResourceNotFound
32
)
33
```
34

35
## Basic Usage
36

37
```python
38
from simple_salesforce import Salesforce
39

40
# Password authentication
41
sf = Salesforce(
42
    username='user@example.com',
43
    password='mypassword',
44
    security_token='mytoken'
45
)
46

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

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

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

63
# Bulk operations
64
bulk_data = [
65
    {'Name': 'Bulk Account 1', 'Type': 'Customer'},
66
    {'Name': 'Bulk Account 2', 'Type': 'Partner'}
67
]
68
bulk_results = sf.bulk.Account.insert(bulk_data)
69

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

77
## Architecture
78

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

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

87
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.
88

89
## Capabilities
90

91
### Authentication
92

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

95
```python { .api }
96
def SalesforceLogin(username=None, password=None, security_token=None, **kwargs): ...
97
```
98

99
[Authentication Methods](./authentication.md)
100

101
### REST API Operations
102

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

105
```python { .api }
106
class Salesforce:
107
    def query(self, query, include_deleted=False, **kwargs): ...
108
    def search(self, search): ...
109
    def describe(self, **kwargs): ...
110
    
111
class SFType:
112
    def create(self, data, headers=None): ...
113
    def get(self, record_id, headers=None, **kwargs): ...
114
    def update(self, record_id, data, **kwargs): ...
115
    def delete(self, record_id, **kwargs): ...
116
```
117

118
[REST API Operations](./rest-api.md)
119

120
### Bulk API v1.0 Operations
121

122
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.
123

124
```python { .api }
125
class SFBulkHandler:
126
    def submit_dml(self, object_name, dml, data, **kwargs): ...
127

128
class SFBulkType:
129
    def insert(self, data, batch_size=10000, **kwargs): ...
130
    def update(self, data, batch_size=10000, **kwargs): ...
131
    def query(self, data, lazy_operation=False, **kwargs): ...
132
```
133

134
[Bulk API v1.0 Operations](./bulk-operations.md)
135

136
### Bulk API v2.0 Operations
137

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

140
```python { .api }
141
class SFBulk2Handler:
142
    def create_job(self, operation, object_name=None, **kwargs): ...
143
    def upload_job_data(self, job_id, data, **kwargs): ...
144
    def wait_for_job(self, job_id, is_query, **kwargs): ...
145
    def get_query_results(self, job_id, **kwargs): ...
146
```
147

148
[Bulk API v2.0 Operations](./bulk2-operations.md)
149

150
### Metadata API Operations
151

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

154
```python { .api }
155
class SfdcMetadataApi:
156
    def deploy(self, zipfile, sandbox, **kwargs): ...
157
    def retrieve(self, async_process_id, **kwargs): ...
158
    def describe_metadata(self): ...
159
    def list_metadata(self, queries): ...
160
```
161

162
[Metadata API Operations](./metadata-api.md)
163

164
### Utility Functions
165

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

168
```python { .api }
169
def format_soql(query, *args, **kwargs): ...
170
def format_external_id(field, value): ...
171
def quote_soql_value(value): ...
172
```
173

174
[Utility Functions](./utilities.md)
175

176
### Exception Handling
177

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

180
```python { .api }
181
class SalesforceError(Exception): ...
182
class SalesforceAuthenticationFailed(SalesforceError): ...
183
class SalesforceExpiredSession(SalesforceError): ...
184
class SalesforceResourceNotFound(SalesforceError): ...
185
```
186

187
[Exception Classes and Error Handling](./exceptions.md)